Getting it into your agent
One page per mod, every tool's command on it. A separate URL per tool would split the same page into five that compete with each other.
npx agentmods add skills/wade-devcode/awesome-coding-skills-cn/writing-docsnpx skills add Wade-DevCode/awesome-coding-skills-cn --skill writing-docsgit clone --depth 1 https://github.com/Wade-DevCode/awesome-coding-skills-cnWhat it costs to keep this loaded
Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.
| Model | Per session | Once invoked |
|---|---|---|
| Fable 5 | $0.00020 | $0.02183 |
| Opus 5 | $0.00010 | $0.01092 |
| Sonnet 5 | $0.00004 | $0.00437 |
| Haiku 4.5 | $0.00002 | $0.00218 |
Grade A, and why
writing-docs scanned grade A with 0 findings against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured 2d ago.
A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.
Nothing flagged
None of the 26 patterns this scan looks for appear in this file: no shell pipes, no recursive deletes, no credential paths, no hidden text, no instruction-override or anti-refusal phrasing, no agent-config snooping. That is not a guarantee, it is the absence of the things that are checkable.
How it starts
The opening of the file, as written. The whole thing — 190 lines — stays where its author put it; the contents beside it link to each section on GitHub.
写文档
何时用
- 新建一个库、工具或服务,需要写 README。
- 现有文档与代码脱节,需要更新。
- 接到"补充文档"的任务,不确定该写什么、写多少。
- 写内部技术方案或 API 参考文档。
核心规则
1. 开头讲"这是什么、解决什么问题、给谁用",30 秒能判断要不要继续读
规则： 文档第一屏必须回答三个问题:这个东西是什么、它解决了什么具体问题、目标读者是谁——不废话,不卖关子。
为什么： AI 写文档时惯于先铺一大段背景介绍和设计理念,把"这是什么"埋在第三段。读者在 30 秒内判断不了这个东西是不是自己需要的,直接关掉。常见事故:README 开头一段"现代分布式系统面临的挑战……",读到第五段才出现一句"本库用于…"——用户早已离开。
怎么做：
- 第一行:一句话说清是什么。
xxx 是一个用于 yyy 的 zzz 工具。 - 第二段:说清它解决什么痛点,以及不解决什么(边界)。
- 第三段或 badge 区:目标用户(前端?后端?DevOps?)、语言/运行时要求。
- 整个"是什么"部分控制在 5-8 行以内。
2. 快速开始可复制即用:安装命令、最小示例,真实可跑
规则： "快速开始"章节必须包含可直接复制执行的安装命令和最小完整示例,运行后能看到预期输出。
为什么： AI 写的"快速开始"常用伪代码或省略关键步骤:用 <your-api-key> 占位符但没说去哪里拿,import 路径和实际包名对不上,示例依赖某个环境变量但没说明。读者跟着做一遍跑不起来,信任立刻崩塌。文档最大的用途就是让人第一次能跑通——跑不通的文档比没文档更打击信心。
怎么做：
- 安装命令给出完整版本(
npm install [email protected]或pip install xxx==1.5.0)。 - 示例代码能"无脑复制到空项目里跑通",不依赖未说明的前置条件。
- 如果有必填的环境变量或配置,在示例旁边紧接着给出怎么获取/生成的说明。
- 文档发布前自己跑一遍快速开始章节,确认没有步骤缺失。
3. 结构按读者需求组织(上手→用法→进阶),不按代码结构
规则： 文档目录顺序应遵循读者的使用旅程:从快速上手到常见用法到高级配置,不要按照代码文件/模块的组织方式排列。
为什么： AI 生成文档时容易"按代码写文档"——每个 class 一个章节,每个方法一条记录,按字母序排列。这是 API reference 的写法,不是入门文档的写法。结果:新用户找不到"我应该先做什么",所有内容平铺在同一层级,没有优先级感。常见事故:一份有 30 个章节的 README,读者需要的"基本使用"在第 17 章。
怎么做：
- 固定骨架:
简介 → 快速开始 → 常见用例 → 配置参考 → 常见问题 → 贡献指南。 - 把 90% 的用户只需要一次的内容(部署、迁移、高级配置)放到"进阶"或单独页面。
- API reference 独立一份,不要混在入门文档里。
4. 示例胜过描述;术语一致,避免内部黑话
规则： 能用代码示例说明的,不用长段文字描述;全文使用统一术语,不造自己发明的词。
为什么： AI 写文档时爱用"该组件通过注册策略模式实现了可扩展的生命周期钩子机制"这类内部黑话——只有写代码的人知道"策略模式"和"生命周期钩子"在这里指什么。外部读者完全无法映射到自己的使用场景。而一个具体的代码示例,10 行能传递 3 段文字无法表达的信息量。
怎么做：
- 凡是涉及"如何使用",优先给代码示例,文字作为辅助说明。
- 术语首次出现时给一句通俗解释:
钩子(hook)——在特定生命周期节点被自动调用的回调函数。 - 不用内部代号、项目昵称、公司方言,假设读者是第一次接触这个项目的外部人员。
5. 与代码同步更新,过期文档比没文档更糟
规则： 每次改动影响到 API 或使用方式时,必须同步更新对应文档;过期或错误的文档要删除或标注,不能留着误导读者。
为什么： AI 实现新功能时经常忘记更新 README 和示例代码。结果是新用户照着文档里的旧 API 写,运行报错,以为是自己的问题。或者文档里有个"将在下一版本实现"的 TODO 留了两年,功能早实现了但文档从没更新。过期文档产生的信任成本比没文档更高——读者不知道哪些是真的,只能全部怀疑。
怎么做：
- PR checklist 里加一项:"文档是否需要更新?"(参考 PR 描述 skill)。
- 已删除的功能/API 同步从文档中删除,不要留注释说"此功能已废弃"三年。
- 对确实暂时没精力更新的部分,在文档顶部明确标注版本号和更新日期。
What this file has done since we first saw it
Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.
- 2d ago First seen · 190 lines · 20 tokens per session scan A ea636448de15
writing-docs is a skill published in the GitHub repository Wade-DevCode/awesome-coding-skills-cn (6 stars, last pushed 2mo ago), licensed MIT. It adds 20 tokens to every session and 2,183 once invoked, about $0.0001 per session on Opus 5. A static security scan graded it A with 0 findings. No closer match exists in the catalogue, so it is treated as the original; first seen 2026-08-31.
Other skills, from other repositories
chinese-documentation
中文文档排版参考——中英文空格、全半角标点、术语保留、链接格式、中文文案排版指北约定。仅在用户显式 /chinese-documentation 时调用，不要根据上下文自动触发。.
chinese-git-workflow
国内 Git 平台配置参考——Gitee、Coding.net、极狐 GitLab、CNB 的 SSH/HTTPS/凭据/CI 接入差异与镜像同步配置。仅在用户显式 /chinese-git-workflow 时调用，不要根据上下文自动触发。.
brainstorming
在任何创造性工作之前必须使用此技能——创建功能、构建组件、添加功能或修改行为。在实现之前先探索用户意图、需求和设计。.
chinese-code-review
中文 review 沟通参考——话术模板、分级标注（必须修复/建议修改/仅供参考）、国内团队常见反模式应对。仅在用户显式 /chinese-code-review 时调用，不要根据上下文自动触发。.
chinese-commit-conventions
中文 commit 与 changelog 配置参考——Conventional Commits 中文适配、commitlint/husky/commitizen 中文模板、conventional-changelog 中文配置。仅在用户显式 /chinese-commit-conventions 时调用，不要根据上下文自动触发。.
mcp-builder
MCP 服务器构建方法论 — 系统化构建生产级 MCP 工具，让 AI 助手连接外部能力.