SuperAPI AI 工具集

documentation

写作与研究

查看项目

更新于 10-16 08:49

技能介绍

用途:当新功能、架构决策、事故或工作流变更需要沉淀为可长期复用的技术文档时使用,例如教程、参考文档、ADR 等。文档被视为产品,需与代码一样版本化、评审、测试和维护。

主要能力:采用 Diataxis 框架将文档分为四类——教程(学习导向、入门分步)、操作指南(任务导向、解决具体问题)、参考(信息导向、如 API 文档)、解释(理解导向、背景与决策)。按受众区分写法:面向开发者给代码示例、API 参考与架构文档;面向运维给运行手册、部署指南与监控看板;面向用户给教程、操作指南与 FAQ;面向干系人给架构决策记录与设计文档。

使用方式:从项目上下文即可开始。第一步识别需求并明确分类:must_consider 只需确认无需更新持久文档并记录决定;must_produce 需创建或更新持久文档;仅当路线明确为 fast-track 且不产生持久知识债时可用 skip_when_fast_track 豁免。第二步按受众写作。第三步让文档贴近代码,采用 docs-as-code,用仓库中的 Markdown 与代码一同版本化,通过 OpenAPI、JSDoc、docstrings 等注解自动生成 API 文档,重点目录放 README,ADR 放 docs/adr/。第四步评审与维护,在 PR 流程中评审改动过的文档,每季度审计清理过时内容,并把文档债与技术债一同跟踪。

适用场景:功能发布、架构决策、事故复盘、新人入职等需要留下持久知识的情况。

质量门与限制:目标是受众仅凭文档即可完成任务;文档需可发现(README 链接、可搜索);自动生成文档接入 CI;无过时信息(近一季度内核实)。应避免写完即弃、文档堆砌、另建独立文档系统、完全无文档等反模式。安装与分发包信息:公开安装面为 skills/.curated,规范来源为 skills/cross-cutting/documentation/SKILL.md,支持 npx skills add/update 兼容导出;打包稳定性与能力就绪度均为 beta。具体教程示例、命令细节与更多配置资料暂未提供。