SuperAPI AI 工具集

doc-writing-best-practices

写作与研究

查看项目

更新于 10-15 23:33

技能介绍

用途:为中文技术文档提供一套跨项目通用的写作规范,共 8 条规则,分内容质量、文档结构、中文排版三类,用于编写或修改 README、设计文档、运维手册、变更说明、注释块等面向人阅读的中文文档,尤其适合产出 Markdown、写提交说明或整理已有文档。

主要能力:内容质量类(HIGH)含 content-example-copy-ready,要求示例用真实值、可直接粘贴执行,避免占位符被抄错;content-why-not-just-what,要求写清为什么,只写怎么做的文档在情况变化时无法判断是否仍适用。文档结构类(MEDIUM)含 struct-code-fence-language,代码块必须标语言,标错比不标更糟,纯输出显式标 text;struct-heading-no-skip,层级不跳级、一篇一个 H1、深度控制在 H4 内;struct-table-vs-list,有共同维度用表格、无共同维度用列表,表格里不放长段落。中文排版类(MEDIUM)含 cjk-latin-spacing,中文与西文、行内代码之间加空格,一致性比选哪种更重要;cjk-number-spacing,中文与数字之间加空格;cjk-punctuation,中文句子用全角标点,判据是这一段的主语言而非整篇文档。

使用方式:规则总量小,可先读索引再按需取用;若在集中整理一批文档,可直接通读 AGENTS.md。按任务选择:写任何中文文档先读 cjk-;写 README 或设计文档读 content- 与 struct-heading-no-skip;写运维手册或操作步骤读 content-example-copy-ready 与 struct-code-fence-language;整理已有文档则读全部。

适用场景与限制:本技能是跨项目通用基线,具体术语表、平台称谓、对外文案口径属于项目事实,应写在项目的 CLAUDE.md,不写入本技能;冲突时以项目自身约定为准。改动 rules/ 后必须重新生成全量版,命令为 bash scripts/build.sh。资料未提供安装方式、收费与平台支持等信息。