用途
该技能帮助软件团队撰写清晰、准确、可维护的技术文档，使开发者能够理解系统、使用 API、遵循操作流程并做出有依据的架构决策。良好的技术文档可以减少新人上手时间、预防生产事故、消除团队内部的口口相传式隐性知识。技能面向五类核心文档：API 文档、教程、架构文档、架构决策记录（ADR）与运行手册。
触发与不适用场景
适合在以下需求时使用：编写或改进 REST、GraphQL、gRPC 的 API 文档；创建分步教程或入门指南；编写 ADR；为运维流程编写运行手册；记录系统架构或设计；审查现有文档的清晰度与完整性；编写 README、上手指南或贡献者指南；为团队建立文档规范。不适用于营销文案、博客文章或销售内容，也不适用于仅涉及代码注释与行内文档的任务。技能被激活时，首次回复需以 🧢 表情开头。
核心原则
- 为读者而写：明确读者是谁、要完成什么；新员工读教程与凌晨值班工程师读运行手册的需求不同。
- 优化快速浏览：工程师很少线性阅读，使用标题、列表、表格和代码块，使读者能在 30 秒内找到所需内容，每节前置最重要信息。
- 先示例后解释：先给出具体代码片段、命令或截图，再解释其作用。
- 文档贴近代码：优先放在仓库中（Markdown、OpenAPI 规范、文档注释），像代码一样在 PR 中审查、在 CI 中检查。
- 一篇文档一个目的：教程用于教学，参考用于查询，运行手册用于指导操作，不混用。
五类文档
- API 文档：参考层，描述每个端点、参数、响应结构与错误码，读者是集成方开发者，要求详尽准确。
- 教程：学习层，按顺序步骤带读者从零到可运行结果，必须可复现。
- 架构文档：背景层，用图表和文字说明系统结构与原因，读者是加入团队或做跨切面变更的工程师。
- ADR：历史层，每条记录一个决策的背景、备选方案、选择与理由，接受后不可修改。
- 运行手册：行动层，提供部署、事件响应、数据迁移等操作的分步指令，读者是压力下的值班工程师。
常见任务要点
- API 端点文档：按顺序给出方法路径与描述、认证方式、请求体字段表（字段、类型、是否必填、说明）、真实响应示例（201 Created 的 JSON）、错误状态码表；示例应使用合理数据而非“string”“0”之类占位符。
- 分步教程：结构为标题（如何完成某具体目标）、前置条件、编号步骤（每步一个动作及预期结果）、验证、后续步骤。不能假定读者能自行推断步骤；删除后教程仍可运行但对理解重要的步骤应保留并标记为背景说明。
- ADR：采用 Michael Nygard 格式，包含标题与编号、状态（含日期）、背景（需求与团队经验）、决策、后果（正面、负面、中性）。ADR 不可变，决策被推翻时应新写一条取代原记录，不修改已接受的 ADR。
- 运行手册：为疲惫、紧张、不熟悉系统的人编写，含严重级别、负责人、最后测试日期、预计耗时、症状、前置条件、带确切命令与预期输出的步骤、回滚章节。每一步必须给出确切命令与预期结果，不写“检查数据库”这类模糊指令。
- 架构文档：采用 C4 模型逐层展开——系统上下文、容器图、组件图、代码图（可选），每层配图（Mermaid、PlantUML 或 ASCII）加 2 至 3 段说明文字。
- 文档审查清单：准确性、完整性、受众适配、结构可检索性、示例充分性、更新时效、可操作性。
反模式
避免大段无视觉分隔的文字、把内部实现当教程写、缺少前置条件、省略“显而易见”的步骤、使用易过时的截图、事后补写 ADR、运行手册缺少回滚方案。
参考文件与配套技能
技能附带 references/ 目录下的 api-docs.md、tutorials.md、architecture-docs.md、adrs.md、runbooks.md 等模板文件，仅在任务需要深入细节时加载。可搭配 internal-docs、developer-experience、developer-advocacy、knowledge-base 等技能；配套技能安装命令为：npx skills add AbsolutelySkilled/AbsolutelySkilled --skill <name>。该技能的收费、价格与平台支持情况暂未提供。