用途
diataxis-docs 用于把文档请求转化为正确文档类型、正确详细程度、面向正确读者的文档。核心理念是先分类再写作。它可用于撰写、改写、重构或审查文档页面；用罗盘对页面或请求进行分类；把混杂页面拆分为正确形式；逐个页面审计或迁移现有文档集；为 SDK、API、CLI 或产品设计文档体系；把用户问题映射到正确的文档形式。
主要能力
Diataxis 罗盘通过两个问题区分文档：内容是关于行动（实践步骤、动手）还是认知（命题知识、思考）？用户是在获取技能（学习）还是应用技能（工作）？由此得到四种形式：教程（关于行动、获取技能）、操作指南（关于行动、应用技能）、参考（关于认知、应用技能）、解释（关于认知、获取技能）。
该技能提供快速决策树：读者正在获取全新技能？有完整引导课程则写教程，追求最短首次成功路径则写快速入门。读者在把已知技能应用到真实任务？有明确目标的通用任务写操作指南，卡在错误上写故障排查。查找确切事实、字段、命令或限制写参考。想理解为什么或如何运作写解释。请求措辞同样映射："为我的新用户写指南"对应教程或快速入门；"如何做 X"对应操作指南；"这个字段是什么意思"对应参考；"为什么这样设计"对应解释。如果请求命中多个分支，应拆分为多个文档而不是混合。
四种形式各有要求：教程面向学习者，写作模式是引导课程，必须有单一线性路径、可见的预期结果、已声明的前置条件，不应有分支、选项、背景长文。操作指南面向工作者，必须有单一目标、简短逻辑序列、验证步骤，不应有教学、概念介绍。参考面向查阅者，必须有镜像所描述事物的结构、确切值、示例，不应有指令、建议、模糊措辞。解释面向反思者，必须有单一有界主题、观点、权衡与替代方案，不应有过程指令、"如何做"框架。
使用方式
工作流：先识别读者及其当前状态（学习、工作、查阅或反思），再识别请求背后的需求（任务、事实、概念或学习路径），用罗盘分类并明确要排除什么，仅在仍不明显时澄清文档类型、受众、目标和范围（问一个简短问题，而非审批循环），用该形式的蓝图列大纲，仅按该形式写作并链接到其他形式而不是混入，最后运行质量检查。如果请求跨越多种需求，应交付配套文档而非一个混合页面。用用户写作时所用语言写作。
当读者状态确实模糊时（通常是教程与操作指南之间），应询问：读者是通过引导练习学习新技能，还是完成他们已经理解的真实任务？如果用户无法澄清，说明假设并写一份聚焦的操作指南，把教学材料链接出去。
适用场景与限制
适用场景包括：撰写、改写、重构或审查文档页面；用罗盘分类页面或请求；将混杂页面拆分为正确形式；逐个页面审计或迁移现有文档集；为 SDK、API、CLI 或产品设计文档体系；把用户问题映射到正确文档形式。当对页面形式感到怀疑，或页面看似一回事却抗拒当前写法时最有用。
不适用场景包括：营销文案、博客文章或非技术写作；纯视觉内容如 UI 模型、幻灯片或设计规范；代码审查、重构、调试或实现工作；无需文档结构的单段或短回答；翻译已遵循清晰结构的文档。一个有用测试：如果请求更多关于说什么而不是写哪种文档，则超出范围。
该技能还列出反模式：一个页面做所有事（教学、指导、列事实、解释权衡）应拆分；教程给选项应选一条路径并把替代方案移到操作指南；操作指南教学应去掉教学并链接到教程或解释；参考叙述应去掉叙述只保留中立描述。混合文档气味测试：若页面同时有两项或以上，如"背景"或"概念"节与"步骤"或"过程"节、叙事段落与参数表权重相当、"为什么这样构建"框架与"运行此命令"指令、教程标题包含可选分支或故障排查、操作指南以"在本教程中你将学到……"开头、约 500 行的 README 试图同时教学、指导、列举和解释，则该页面可能在混合形式，应拆分而非添加标题。
README 是入口点而非文档站点，不要内联完整教程、列出每个标志或混合安装、配置、部署、故障排查和贡献。故障排查为症状→原因→解决方案，把"为什么发生"移到解释。术语表是术语列表，把用法示例移到操作指南或参考。发行说明是变更与影响，把理由移到解释。快速入门优化首次成功而非完整性。风格指南描述语气和规则，不重新推导 Diataxis。
规模化工作时：Diataxis 是指南而非计划。对现有材料先应用罗盘，给每个页面打上罗盘单元格标签并移动放错位置的页面，然后再添加新内容。一次写一个页面。让顶层结构在足够页面出现后自然形成。如果被要求预先提出结构，将其视为草图而非契约。不要预先创建空节、按象限分配内容配额、在内容良好前强制信息架构，或把"文档系统"当作交付物——它是一种实践。
捆绑工具：scripts/audit_docs.py 是该技能附带的启发式混合形式扫描器，在审计超过少数页面时用作机械预检，然后对标记页面应用罗盘。命令示例：python scripts/audit_docs.py docs/（Markdown 报告）；python scripts/audit_docs.py docs/ --format json（机器可读）；python scripts/audit_docs.py . --exclude 'CHANGELOG.md'（跳过已知混合文件）。它报告风险级别及其背后信号，不是权威分类器，只缩小查看范围，切勿将其输出作为最终分类。
参考文件按需加载：references/doc-blueprints.md 在列大纲或起草文档并需要该形式的节结构时加载；references/reader-analysis.md 在起草前读者或其状态不清晰时加载；references/template-map.md 在把工件或 Good Docs Project 模板映射到形式或罗盘单元格时加载；references/zh-cn-anti-patterns.md 在审查中文技术文档或中文本地化草稿时加载。
质量检查：完成前运行意图检查、按形式检查和混合文档气味测试。意图检查：是否在起草前识别读者及其状态？是否先用罗盘分类？是否为读者实际状态而非自己心智模型写作？是否让文档聚焦一个需求？是否避免发明内容尚未要求的结构？是否留有链接配套文档的空间？按形式检查：教程应让完全新手不读其他内容即可完成，每步有可见结果；操作指南应让有经验用户在不到一分钟内找到答案，页面恰好覆盖一个目标；参考应让每个条目结构一致，无缺失或冗余；解释应一个概念、清晰观点、无过程。绝不声称文档已验证而实际未验证。如果代码示例或命令未运行，应说明。
该技能提炼自 diataxis.fr，特别是 start here、compass、how to use Diataxis 以及教程、操作指南、参考和解释各页面，并结合 The Good Docs Project 模板。