写中文技术文档的 Agent Skill，基于阮一峰《中文技术文档的写作规范》：短句、平实、没有 AI 腔
Catalog skill by leter: 写中文技术文档的 Agent Skill，基于阮一峰《中文技术文档的写作规范》：短句、平实、没有 AI 腔 Install into Cursor, Claude, Codex, or VS Code from this page or review the source for zh-tech-writing.
Ads
git clone https://github.com/leter/zh-tech-writing
Install guides: Cursor skills, Claude Code skills, Codex skills, or VS Code Copilot skills.
目标：写出像资深工程师写的中文技术文档。平实、具体、短句。
写新文档：
autocorrect --fix <文件>，修空格和标点。命令不存在就跳过，改为按“排版”手动检查。修改已有文档：
每一步都做完才算完成。第 3 步的标准是：清单每一条都对照过，全文没有命中。
**（1）xxx** 或列表。每篇都要守的规则：
在 Linux 上安装 5 个包。，。：；？（）。整句是英文时用半角标点。他用的是 MacBook Air。“ ”，引号里再套引号用 ‘ ’。、 隔开，最后一项用“和”连接：Google、腾讯和百度。……，不写 ... 或 。。。，也不和“等”连用。数字（千分位、单位、范围、倍数）、括号、冒号、连接号、英文缩写的细则，见 references/typography.md。文档里出现这些内容时读它。
写一整套产品手册或文档站、需要规划目录和文件名时，读 references/manual-structure.md。
自检时逐条对照。左边是要找的写法，右边是改法。
| 找这种写法 | 改成 |
|---|---|
| 开场套话：“随着……的发展”“在当今……”“值得注意的是”“需要指出的是”“让我们来看看”“接下来我们将介绍” | 删掉，第一句直接说内容 |
| 结尾套话：“总的来说”“综上所述”“总而言之”，或重复前文的总结段 | 删掉。确实需要结尾，只写新信息，比如下一步做什么 |
| 客套话：“希望对你有帮助”“如有问题欢迎交流” | 删掉 |
| 对比句式：“不是 A，而是 B”“与其说 A，不如说 B” | 直接说 B |
| 递进句式：“不仅……而且/更……” | 拆成两个陈述句 |
| 硬凑三个：三个排比形容词、每组都是三项的列表 | 有几项写几项 |
| 设问自答：“关键是什么？答案很简单：”“原因很简单：” | 直接给结论 |
| 宣传腔形容词：强大、灵活、无缝、全面、极致、优雅、轻松、一站式 | 换成具体事实，没有事实就删 |
| 黑话：赋能、抓手、闭环、链路、沉淀、对齐、颗粒度、维度、底层逻辑、范式、打通 | 换成白话。代码或业务里的正式名称（如“调用链路”）保留 |
破折号 —— 用来插入解释 | 改用逗号、冒号、括号，或拆成两句。全文最多一两处 |
| 翻译腔：“进行 + 动词”“通过……的方式”“作为一个……”、一句里多个“的” | 直接用动词，拆开长定语 |
| 过度含糊：“在某种程度上”“在一定情况下可能会” | 确定就直接说；不确定就说清条件 |
| 感叹号、emoji 标题或列表符号 | 句号，纯文字标题 |
| 每段都加粗、一两句话也拆成列表、小标题比段落还密 | 按“段落与结构”重排 |