⏳ This skill is pending AI review.

Scores will appear once the review pipeline completes.

version unknown

zh-tech-writing

leter@leter⭐ 419 stars· last commit 1mo ago· 0 open issues

中文技术文档写作规范。写或修改中文技术文档、开发文档(README、设计文档、接口说明、教程)时使用。

Choose how to use this skill

You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.

1. Native installer

This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.

Do not guess an installer command or replace an existing version without reviewing the diff.

2. Complete package recommended

Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.

No complete ProSkills package is published for this listing yet.

3. Prompt-only

Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.

Need only the instruction file?

Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.

No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.

—/10

// RATINGS

⭐GitHub Stars
⭐⭐⭐ 419 on GitHubGitHub ↗

Popular

🟢ProSkills Score
—
📍

Not yet listed on ClawHub or SkillsMP

// README

zh-tech-writing

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

规则基于阮一峰的《中文技术文档的写作规范》整理,另外补充了一份“AI 腔清单”。

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

效果

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

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

用这个 skill 以后:

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

改动有三处:

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

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

安装

用 skills 命令行工具安装到全局:

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

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

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

安装 autocorrect(推荐)

autocorrect 是一个命令行工具。它会自动在中英文之间补空格,并把中文句子里的半角标点改成全角。装了它,AI 写完文档后会按 skill 的要求运行一遍;没装就跳过这一步。

# 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                     主文件:流程、核心规则、AI 腔清单
└── references/
    ├── typography.md            数字、标点、英文缩写的细则
    └── manual-structure.md      产品手册的目录结构和文件命名

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

来源与致谢

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

许可

MIT

// HOW IT'S BUILT

// FILES

2 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.

  • skills/zh-tech-writing/SKILL.md6.2 KBupstream ↗
    ---
    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 标题或列表符号 | 句号,纯文字标题 |
    | 每段都加粗、一两句话也拆成列表、小标题比段落还密 | 按“段落与结构”重排 |
    
  • README.mdupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

Plain-text copy, no login: /skill-bundles/leter-zh-tech-writing-skills-zh-tech-writing.md

// REPO STATS

419 stars
0 open issues
Last commit: 1mo ago