Skip to content
Back to search

zh-tech-writing

写中文技术文档的 Agent Skill,基于阮一峰《中文技术文档的写作规范》:短句、平实、没有 AI 腔

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/leter--zh-tech-writing/badge.svg)](/listings/leter--zh-tech-writing)

HTML

<a href="/listings/leter--zh-tech-writing"><img src="/api/listings/leter--zh-tech-writing/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

用 [skills](https://github.com/vercel-labs/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/

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 124 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # zh-tech-writing
  2. 一个写中文技术文档的 Agent Skill。用它写 README、设计文档、接口说明和教程,读起来像工程师写的,没有 AI 腔。
  3. 规则基于阮一峰的[《中文技术文档的写作规范》](https://github.com/ruanyf/document-style-guide)整理,另外补充了一份“AI 腔清单”。
  4. 适用于 Claude Code,以及其他支持 Agent Skills 的工具。
  5. ## 效果
  6. 下面是一段常见的 AI 写法:
  7. > 随着微服务架构的不断发展,配置管理已经成为一个不容忽视的问题。值得注意的是,ConfigHub 不仅提供了强大的配置管理能力,更实现了与现有系统的无缝集成——让你轻松应对各种复杂场景!
  8. 用这个 skill 以后:
  9. > ConfigHub 用来集中管理多个服务的配置。修改配置后,服务会在 5 秒内加载新值,不用重启。接入时,在启动命令里加上 `--config-hub=<地址>` 即可。
  10. 改动有三处:
  11. - 删掉开场套话和感叹号。
  12. - 去掉“不仅……更……”这种句式和破折号。
  13. - 用具体事实替换“强大”“无缝”这类形容词。
  14. 事实需要来自你的项目。skill 找不到事实时,会删掉空话,或者直接问你。
  15. ## 安装
  16. 用 [skills](https://github.com/vercel-labs/skills) 命令行工具安装到全局:
  17. ```bash
  18. npx skills add leter/zh-tech-writing -g
  19. ```
  20. 也可以手动安装。把 `skills/zh-tech-writing` 目录复制到 `~/.claude/skills/` 下面:
  21. ```bash
  22. git clone https://github.com/leter/zh-tech-writing.git
  23. cp -r zh-tech-writing/skills/zh-tech-writing ~/.claude/skills/
  24. ```
  25. ## 安装 autocorrect(推荐)
  26. [autocorrect](https://github.com/huacnlee/autocorrect) 是一个命令行工具。它会自动在中英文之间补空格,并把中文句子里的半角标点改成全角。装了它,AI 写完文档后会按 skill 的要求运行一遍;没装就跳过这一步。
  27. ```bash
  28. # macOS
  29. brew install autocorrect
  30. # Linux:从 Releases 页面下载二进制文件,放到 PATH 里的任意目录
  31. # https://github.com/huacnlee/autocorrect/releases
  32. # 已经装了 Rust 工具链
  33. cargo install autocorrect
  34. ```
  35. 装好后运行 `autocorrect -V`,能看到版本号就说明装好了。
  36. ## 使用
  37. 你让 AI 写或修改中文技术文档时,skill 通常会自动加载。比如:
  38. ```
  39. 帮我给这个项目写一份 README
  40. 把 docs/deploy.md 改得更易读一些
  41. ```
  42. 也可以手动调用:
  43. ```
  44. /zh-tech-writing 改一下 docs/api.md
  45. ```
  46. 如果只想看修改意见,不想让它直接改文件,就说出来:
  47. ```
  48. /zh-tech-writing 检查 docs/api.md,只列问题,不要改
  49. ```
  50. 它会按“原句 → 改后 → 原因”的格式列出问题。
  51. ## 它做了什么
  52. skill 让 AI 按下面的流程写文档:
  53. 1. 先确定读者是谁,读完要能做成什么事。
  54. 2. 按规则写:句子、语气、段落与结构、排版。
  55. 3. 用“AI 腔清单”逐条检查全文,命中的地方全部改掉。
  56. 4. 运行 `autocorrect --fix`,修正空格和标点。
  57. 5. 手动检查 autocorrect 不管的引号、省略号和破折号。
  58. 主要规则:
  59. - 句子:逗号隔开的每一截尽量在 20 字以内。多用肯定句和主动语态。直接用动词,不套“进行”“做出”。
  60. - 语气:像给同事讲清楚一件事。用数字、命令和报错原文代替形容词。
  61. - 结构:每段第一句说重点。标题不跳级。少用四级标题。加粗和列表都不滥用。
  62. - AI 腔清单:共 14 条,包括开场和结尾套话、“不是 A,而是 B”句式、硬凑三个排比、宣传腔形容词、黑话、破折号和翻译腔。
  63. 完整规则见 [SKILL.md](skills/zh-tech-writing/SKILL.md)。
  64. ## 目录结构
  65. ```
  66. skills/zh-tech-writing/
  67. ├── SKILL.md 主文件:流程、核心规则、AI 腔清单
  68. └── references/
  69. ├── typography.md 数字、标点、英文缩写的细则
  70. └── manual-structure.md 产品手册的目录结构和文件命名
  71. ```
  72. `references/` 下的文件只在需要时读取。比如,文档里有数字范围时才读 `typography.md`。
  73. ## 来源与致谢
  74. - 句子、段落、标题、标点和数字的规则,整理自阮一峰的[《中文技术文档的写作规范》](https://github.com/ruanyf/document-style-guide)。原项目放在公共领域(public domain)。
  75. - 原规范里有两处符号写错了,这里改成了标准写法:破折号用 `——`,省略号用 `……`。
  76. - 原规范说数字和中文之间加不加空格都可以。这里统一定为加空格,这样和 autocorrect 的结果一致。
  77. - 原规范要求“不使用非正式语言”。这里放宽为:可以口语化,但不用网络流行语。
  78. - 原规范本身参考了华为《产品手册中文写作规范》、LeanCloud《文档风格指南》、[中文文案排版指北](https://github.com/sparanoid/chinese-copywriting-guidelines)、Google Developer Documentation Style Guide 和国家标准 GB/T 15835-2011。
  79. - “AI 腔清单”“用事实代替形容词”和整套写作流程,是这个项目新增的内容。
  80. - 空格和标点的自动修正由 [autocorrect](https://github.com/huacnlee/autocorrect)(MIT 许可)完成。本项目只调用这个工具,没有包含它的代码。
  81. ## 许可
  82. [MIT](LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.