SuperAPI AI 工具集

technical-writing

写作与研究

查看项目

更新于 10-27 16:23

技能介绍

用途

本技能用于在基于 Basilic 的仓库中撰写、编辑和审阅技术文档,覆盖 Docu MDX、README 以及根目录产品 Markdown(如 PRODUCT.md、ARCHITECTURE.md、DESIGN.md)。目标读者是开发者与编码智能体,要求每个章节都易于扫描、检索和直接执行,不依赖未说明的上下文。

主要能力

  • 撰写面向任务的技术文档,每页聚焦一个主要任务。
  • 编辑与审阅现有文档,保持作者原有含义、细微差别与不确定性,做最小有效修改。
  • 对照来源核实每一条声明,确保准确。
  • 统一语气与用词:以“你”称呼读者,步骤使用祈使动词,主动语态、现在时、具体名词,美式英语并使用牛津逗号;命名运行时 eve 时使用小写。
  • 禁用填充与夸张词(easy、simple、quick、just、obviously、utilize、facilitate、leverage、robust、seamless、促销性形容词、反问句、诱导互动内容),并禁用 AI 痕迹(总结式过渡、断续片段、数据表式动词、无先行词的开头、模板式结尾、为显得像人而制造的细节)。
  • 支持三种文档模式:Docu MDX、README、根产品 Markdown。

使用方式

写作前先阅读所在仓库的 AGENTS.md,了解文档分层、公开一句话介绍、能力名称、禁用文案以及 DESIGN.md 的位置。.cursor/rules/ 中的 Glob 规则优先于本技能。若不确定应更新哪一层(MDX、README 还是规则),使用 /w-docs,不要在本技能中重复其路由表。

来源核实顺序:

  1. 仓库中拥有该行为的源码、公开类型与测试;
  2. 最近 README 中提到的 CLI 帮助与包脚本;
  3. AGENTS.md 指定文档层中已有的 MDX 或 Markdown;
  4. ADR 与架构页面——在合并行为匹配之前仅视为提案意图;
  5. Issue 与用户报告——用于了解读者问题,不作为产品事实依据。

若某条声明无法核实,应省略或注明缺失的负责人。完成稿中不得保留 [VERIFY]。不得将提案行为记录为已发布行为。

方法步骤:

  1. 明确该篇文档的唯一任务与读者的任务。
  2. 找到已拥有该主题的页面,优先扩展而非新建页面。
  3. 列提纲:结果 → 前置条件 → 顺利路径 → 替代方案 → 失败情况 → 相关链接。
  4. 起草与核实声明同步进行。
  5. 自编辑以利于检索:关键陈述中重复完整名词,把关键事实放在本地而非仅藏在链接后。
  6. 多轮审阅:目的与结构、准确性、完整性、风格与检索、diff 纪律(不做顺手重写)。

三种模式的具体要求:

  • Docu MDX(当仓库有 apps/docu/content/docs/ 时):使用 title 与 description frontmatter;导航变化时更新文件夹 meta.json;从相关枢纽页加入正文链接(避免孤立页面);路由移动时在 doc 应用配置中设置永久重定向;仅在邻近页面已使用时才使用 MDX 组件。准备发布文档变更时,以 pnpm --filter @repo/docu checktypes 收尾。
  • README(**/README.md):遵循 .cursor/rules/base/readme.mdc——根 README 负责产品故事,应用与包保持精简并链接到技术文档。
  • 根产品 Markdown(如 PRODUCT.md、ARCHITECTURE.md,以及 AGENTS.md 指定的 DESIGN.md):使用相同语气;能力名称与该仓库架构来源一致;仅当 AGENTS.md 说明上游托管文档覆盖本地项目文档时,才以上游为准。

适用场景

适用于在 Basilic 系仓库中新增或更新 Docu MDX 页面、README、根产品 Markdown;也适用于审阅已有技术文档的准确性、结构与检索性。

限制

  • 绝不虚构标志、端点、默认值、示例、指标或用户反应。
  • 绝不将单个支持线程直接变成新页面,除非先确定属于文档范围还是产品范围。
  • 当某个章节或交叉链接即可弥补缺口时,绝不重复编写宽泛指南。
  • 绝不为了叙事方便而违背所在仓库的公开一句话介绍、禁用文案或能力名称。
  • 支持证据只能说明存在困惑;行为由实现与测试确立。

本技能不负责:/w-docs(决定修补哪一层)、/w-api-docs(OpenAPI 与生成客户端)、/w-deslop(分支上的代码 slop)、/w-architecture(ADR 与边界规划)、个人或营销语气目录(如 gabo)。