# zh-tech-writing

Adopt this skill: https://proskills.md/skills/other/leter-zh-tech-writing-skills-zh-tech-writing

Page: https://proskills.md/skills/other/leter-zh-tech-writing-skills-zh-tech-writing
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: skills/zh-tech-writing/SKILL.md
size: 6359
upstream: https://github.com/leter/zh-tech-writing/blob/main/skills/zh-tech-writing/SKILL.md

```text
---
name: zh-tech-writing
description: 中文技术文档写作规范。写或修改中文技术文档、开发文档（README、设计文档、接口说明、教程）时使用。
---

# 中文技术文档写作

目标：写出像资深工程师写的中文技术文档。**平实**、**具体**、**短句**。

## 流程

**写新文档：**

1. 先想清楚读者是谁，读完要能做成什么事。一句话说不清，先问用户。
2. 按下面的“句子”“语气”“段落与结构”“排版”写。
3. 自检：拿“AI 腔清单”逐条对照全文，命中的全部改掉。
4. 跑 `autocorrect --fix <文件>`，修空格和标点。命令不存在就跳过，改为按“排版”手动检查。
5. 手动检查 autocorrect 管不到的：引号、省略号、破折号。

**修改已有文档：**

1. 通读全文，再动手。
2. 用户只要意见：按“原句 → 改后 → 原因”列出问题，不改文件。
3. 否则直接改，然后做上面的第 3～5 步。最后用两三句话说明改了哪几类问题。

每一步都做完才算完成。第 3 步的标准是：清单每一条都对照过，全文没有命中。

## 句子

- 用逗号隔开的每一截，尽量在 20 字以内。超过 30 字就拆开。整句不超过 100 字。
- 一句只说一个意思。多用简单句和并列句，把长定语拆出去。
  - 差：那个昨天生病的人没有参加会议。
  - 好：他昨天生病了，没有参加会议。
- 用肯定句，不用双重否定。
  - 差：请确认没有接通装置的电源。 → 好：请确认装置的电源已关闭。
  - 差：没有删除权限的用户，不能删除此文件。 → 好：用户必须有删除权限，才能删除此文件。
- 用主动语态，少用“被”。
  - 差：假如此软件尚未被安装 → 好：假如还没安装这个软件
- 动词直接用，不套“进行”“做出”。
  - 差：对配置文件进行修改 → 好：修改配置文件
- “这”“其”“该”只指一个明确的对象。可能有歧义就把名词重复一遍。
- 名词前的修饰语不超过两层，多了就拆成两句。
- 用现代汉语常用词，不用文言、生造词。
  - 差：这是唯二的方法。 → 好：只有这两种方法。
- 分清“的、地、得”：开心的笑容、开心地笑、笑得开心。

## 语气

- 像给同事讲清楚一件事：口语化可以，网络流行语不用。
- 称呼读者用“你”，称呼项目方用“我们”。
- 用陈述语气，句末用句号。
- 用事实代替形容词：给出数字、命令、文件名、报错原文。
  - 差：性能得到了大幅提升。
  - 好：p99 延迟从 120 ms 降到 40 ms。
- 确定的事直接说。不确定就说清楚哪里不确定、怎么验证。

## 段落与结构

- 每段第一句说这段的重点，后面的句子为它服务。一段一个主题。
- 一段最好不超过 4 行，最多 7 行。
- 标题用二级、三级为主：
  - 一级标题下直接接二级，不跳级。
  - 同级标题只有一个时，去掉这层标题。
  - 下级标题不重复上级标题的名字。
  - 需要四级标题时，改用 `**（1）xxx**` 或列表。
  - 标题末尾不加句号、逗号、冒号。
- 列表只放真正并列、可以单独扫读的条目。有因果、转折关系的内容，写成段落。
- 加粗只给读者必须注意的警告或关键词，一屏最多一两处。
- 引用别人的内容或图片，注明出处。

## 排版

每篇都要守的规则：

- 中文与英文、数字之间加一个半角空格：`在 Linux 上安装 5 个包`。
- 中文句子用全角标点：`，。：；？（）`。整句是英文时用半角标点。
- 英文、数字后面紧跟全角标点时，中间不加空格：`他用的是 MacBook Air。`
- 引号用全角 `“ ”`，引号里再套引号用 `‘ ’`。
- 并列的词用顿号 `、` 隔开，最后一项用“和”连接：`Google、腾讯和百度`。
- 省略号写成 `……`，不写 `...` 或 `。。。`，也不和“等”连用。
- 数字一律用半角。

数字（千分位、单位、范围、倍数）、括号、冒号、连接号、英文缩写的细则，见 [references/typography.md](references/typography.md)。文档里出现这些内容时读它。

写一整套产品手册或文档站、需要规划目录和文件名时，读 [references/manual-structure.md](references/manual-structure.md)。

## AI 腔清单

自检时逐条对照。左边是要找的写法，右边是改法。

| 找这种写法 | 改成 |
|---|---|
| 开场套话：“随着……的发展”“在当今……”“值得注意的是”“需要指出的是”“让我们来看看”“接下来我们将介绍” | 删掉，第一句直接说内容 |
| 结尾套话：“总的来说”“综上所述”“总而言之”，或重复前文的总结段 | 删掉。确实需要结尾，只写新信息，比如下一步做什么 |
| 客套话：“希望对你有帮助”“如有问题欢迎交流” | 删掉 |
| 对比句式：“不是 A，而是 B”“与其说 A，不如说 B” | 直接说 B |
| 递进句式：“不仅……而且/更……” | 拆成两个陈述句 |
| 硬凑三个：三个排比形容词、每组都是三项的列表 | 有几项写几项 |
| 设问自答：“关键是什么？答案很简单：”“原因很简单：” | 直接给结论 |
| 宣传腔形容词：强大、灵活、无缝、全面、极致、优雅、轻松、一站式 | 换成具体事实，没有事实就删 |
| 黑话：赋能、抓手、闭环、链路、沉淀、对齐、颗粒度、维度、底层逻辑、范式、打通 | 换成白话。代码或业务里的正式名称（如“调用链路”）保留 |
| 破折号 `——` 用来插入解释 | 改用逗号、冒号、括号，或拆成两句。全文最多一两处 |
| 翻译腔：“进行 + 动词”“通过……的方式”“作为一个……”、一句里多个“的” | 直接用动词，拆开长定语 |
| 过度含糊：“在某种程度上”“在一定情况下可能会” | 确定就直接说；不确定就说清条件 |
| 感叹号、emoji 标题或列表符号 | 句号，纯文字标题 |
| 每段都加粗、一两句话也拆成列表、小标题比段落还密 | 按“段落与结构”重排 |
```

## File: README.md
upstream: https://github.com/leter/zh-tech-writing/blob/main/README.md

````text
# zh-tech-writing

一个写中文技术文档的 Agent Skill。用它写 README、设计文档、接口说明和教程，读起来像工程师写的，没有 AI 腔。

规则基于阮一峰的[《中文技术文档的写作规范》](https://github.com/ruanyf/document-style-guide)整理，另外补充了一份“AI 腔清单”。

适用于 Claude Code，以及其他支持 Agent Skills 的工具。

## 效果

下面是一段常见的 AI 写法：

> 随着微服务架构的不断发展，配置管理已经成为一个不容忽视的问题。值得注意的是，ConfigHub 不仅提供了强大的配置管理能力，更实现了与现有系统的无缝集成——让你轻松应对各种复杂场景！

用这个 skill 以后：

> ConfigHub 用来集中管理多个服务的配置。修改配置后，服务会在 5 秒内加载新值，不用重启。接入时，在启动命令里加上 `--config-hub=<地址>` 即可。

改动有三处：
- 删掉开场套话和感叹号。
- 去掉“不仅……更……”这种句式和破折号。
- 用具体事实替换“强大”“无缝”这类形容词。

事实需要来自你的项目。skill 找不到事实时，会删掉空话，或者直接问你。

## 安装

用 [skills](https://github.com/vercel-labs/skills) 命令行工具安装到全局：

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

也可以手动安装。把 `skills/zh-tech-writing` 目录复制到 `~/.claude/skills/` 下面：

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

## 安装 autocorrect（推荐）

[autocorrect](https://github.com/huacnlee/autocorrect) 是一个命令行工具。它会自动在中英文之间补空格，并把中文句子里的半角标点改成全角。装了它，AI 写完文档后会按 skill 的要求运行一遍；没装就跳过这一步。

```bash
# macOS
brew install autocorrect

# Linux：从 Releases 页面下载二进制文件，放到 PATH 里的任意目录
# https://github.com/huacnlee/autocorrect/releases

# 已经装了 Rust 工具链
cargo install autocorrect
```

装好后运行 `autocorrect -V`，能看到版本号就说明装好了。

## 使用

你让 AI 写或修改中文技术文档时，skill 通常会自动加载。比如：

```
帮我给这个项目写一份 README
把 docs/deploy.md 改得更易读一些
```

也可以手动调用：

```
/zh-tech-writing 改一下 docs/api.md
```

如果只想看修改意见，不想让它直接改文件，就说出来：

```
/zh-tech-writing 检查 docs/api.md，只列问题，不要改
```

它会按“原句 → 改后 → 原因”的格式列出问题。

## 它做了什么

skill 让 AI 按下面的流程写文档：

1. 先确定读者是谁，读完要能做成什么事。
2. 按规则写：句子、语气、段落与结构、排版。
3. 用“AI 腔清单”逐条检查全文，命中的地方全部改掉。
4. 运行 `autocorrect --fix`，修正空格和标点。
5. 手动检查 autocorrect 不管的引号、省略号和破折号。

主要规则：

- 句子：逗号隔开的每一截尽量在 20 字以内。多用肯定句和主动语态。直接用动词，不套“进行”“做出”。
- 语气：像给同事讲清楚一件事。用数字、命令和报错原文代替形容词。
- 结构：每段第一句说重点。标题不跳级。少用四级标题。加粗和列表都不滥用。
- AI 腔清单：共 14 条，包括开场和结尾套话、“不是 A，而是 B”句式、硬凑三个排比、宣传腔形容词、黑话、破折号和翻译腔。

完整规则见 [SKILL.md](skills/zh-tech-writing/SKILL.md)。

## 目录结构

```
skills/zh-tech-writing/
├── SKILL.md                     主文件：流程、核心规则、AI 腔清单
└── references/
    ├── typography.md            数字、标点、英文缩写的细则
    └── manual-structure.md      产品手册的目录结构和文件命名
```

`references/` 下的文件只在需要时读取。比如，文档里有数字范围时才读 `typography.md`。

## 来源与致谢

- 句子、段落、标题、标点和数字的规则，整理自阮一峰的[《中文技术文档的写作规范》](https://github.com/ruanyf/document-style-guide)。原项目放在公共领域（public domain）。
  - 原规范里有两处符号写错了，这里改成了标准写法：破折号用 `——`，省略号用 `……`。
  - 原规范说数字和中文之间加不加空格都可以。这里统一定为加空格，这样和 autocorrect 的结果一致。
  - 原规范要求“不使用非正式语言”。这里放宽为：可以口语化，但不用网络流行语。
- 原规范本身参考了华为《产品手册中文写作规范》、LeanCloud《文档风格指南》、[中文文案排版指北](https://github.com/sparanoid/chinese-copywriting-guidelines)、Google Developer Documentation Style Guide 和国家标准 GB/T 15835-2011。
- “AI 腔清单”“用事实代替形容词”和整套写作流程，是这个项目新增的内容。
- 空格和标点的自动修正由 [autocorrect](https://github.com/huacnlee/autocorrect)（MIT 许可）完成。本项目只调用这个工具，没有包含它的代码。

## 许可

[MIT](LICENSE)
````
