SuperAPI AI 工具集

documentation-standards

写作与研究

查看项目

更新于 10-15 23:41

技能介绍

用途:为 Markdown 文档(README、技能说明、指南、规格)提供统一写作规范,使其既便于 LLM 读取,也能通过 Pandoc 转为专业 PDF,并可用于审查文档合规性。

主要能力与原则:

  1. 机器可读优先:工作流用 OpenAPI 3.1.1 YAML,数据结构用 JSON Schema,配置用带校验的 YAML;人类文档引用这些规范而非替代。
  2. 中心-分支渐进披露:中心文件(如 CLAUDE.md、INDEX.md)只放要点并链接到详细分支(技能、docs 目录),每个主题单一事实来源,避免重复。
  3. 章节编号:禁止手动给标题编号,使用语义化标题层级(##、###),由 Pandoc 的 --number-sections 自动编号,避免出现“1. 1. Introduction”重复。

使用方式:按检查清单执行——结构遵循中心-分支、链接更深文档、无重复内容;格式上不手动编号、正确使用标题层级、代码块标注语言、链接用 text;机器可读内容按上述格式;文件按全局标准、技能文档、项目文档分别放置,并提供 INDEX.md 或 README.md 导航。

适用场景:编写或审查 Markdown 文档、创建含 Markdown 的新技能、撰写可能转 PDF 的内容。

限制与排查:资料未提供具体安装命令或平台要求。常见问题包括 PDF 中章节号重复(因手动编号)、PDF 链接失效(相对路径错误)、代码块无高亮(缺语言标识)、表格渲染差(列过宽)、中心文档过长(细节应移至分支)、内容重复(应确定单一事实来源)、YAML 规格不渲染(扩展名错误)、缺少索引导航。该技能为自进化型,遇到真实可复现问题时应立即修正本文件。