zh-tech-writing

技能简介

zh-tech-writing 是一款专用于中文技术文档写作的 Agent Skill，适用于 Claude Code 及所有支持 Agent Skills 的工具。它的核心使命是：让 AI 写出的 README、设计文档、接口说明和教程读起来像工程师写的，没有常见的 AI 腔。

核心能力

• 消除 AI 腔：自动识别并改写 14 条常见 AI 腔模式，包括开场套话、感叹号堆砌、"不仅……更……"句式、破折号滥用、翻译腔形容词等
• 用事实替换形容词：遇到"强大""无缝""灵活"等空洞形容词时，强制要求 AI 用项目中的具体事实替换
• 中文排版规范化：自动在中英文之间补空格，将中文句子里的半角标点改为全角标点
• 结构规范：要求每段第一句说重点，标题不跳级，少用四级标题，加粗和列表不滥用
• 多工具兼容：支持 Claude Code、Codex、OpenClaw 及所有遵循 Agent Skills 协议的工具
• 规则透明：基于阮一峰《中文技术文档的写作规范》整理，规则完全公开可查

安装配置

方式一：命令行工具安装（推荐）

npx skills add leter/zh-tech-writing -g

方式二：手动安装

git clone https://github.com/leter/zh-tech-writing.git
cp -r zh-tech-writing/skills/zh-tech-writing ~/.claude/skills/

方式三：安装 autocorrect（推荐配套）

autocorrect 是自动修正空格和标点的命令行工具，安装后 AI 写完文档会自动运行修正：

# macOS
brew install autocorrect
# Linux: 从 https://github.com/huacnlee/autocorrect/releases 下载二进制
# Rust 工具链
cargo install autocorrect

使用步骤

1. 自动加载：当你对 AI 说"帮我给这个项目写一份 README"时，skill 通常会自动加载
2. 手动调用：也可以直接说/zh-tech-writing 改一下 docs/api.md
3. 仅检查不修改：说"检查 docs/api.md，只列问题，不要改"，AI 会按"原句 → 改后 → 原因"格式列出问题
4. autocorrect 自动修正：安装 autocorrect 后，skill 会自动运行autocorrect --fix修正空格和标点

适用场景

• 工程师用 AI 辅助写 README 文档
• 开发团队统一项目文档风格
• 写设计文档、接口说明、技术教程
• 评审他人提交的中文技术文档质量
• 建立团队内部中文文档写作规范
• 翻译英文文档时消除翻译腔
• 日常技术沟通中消除空话套话

适用人群

• 软件工程师和全栈开发者
• 技术文档工程师（Technical Writer）
• 开源项目维护者
• 技术团队负责人
• 需要写技术文档的产品经理

工作原理

skill 让 AI 按以下流程写文档：

1. 确定读者：先明确读者是谁、读完要能做成什么事
2. 按规则撰写：按句子、语气、段落结构、排版的规则写作
3. AI 腔清单扫描：用 14 条 AI 腔清单逐段检查全文，命中的地方全部改掉
4. autocorrect 修正：运行修正命令处理空格和标点
5. 人工复核：手动检查引号、省略号和破折号

主要规则包括：句子每截尽量在 20 字以内；多用肯定句和主动语态；语气像给同事讲清楚一件事；直接用数字、命令和报错原文代替形容词。

官方链接

• GitHub 仓库：https://github.com/leter/zh-tech-writing
• 阮一峰《中文技术文档的写作规范》：https://github.com/ruanyf/document-style-guide
• autocorrect 工具：https://github.com/huacnlee/autocorrect