关于 diataxis
diataxis 是一项文档治理技能，依据 Diátaxis 框架对文档进行分类、审查、生成或重组，供文档维护者和 Agent 使用。它通过规则区分教程、操作指南、参考和解释内容。
主要功能
- 01按四个象限分类文档
- 02审查覆盖缺口与混合内容
- 03按象限生成文档
- 04按内容类型重组文档
- 05生成前要求确认象限
适用场景
- 01判定现有文档页面的类型
- 02查找文档集合中的缺口
- 03为指定象限起草内容
- 04规划混合用途文档的拆分
安装
复制下面的命令，在终端中运行。
npx skills add https:/安装后在 Claude Code 中输入/diataxis确认已加载。
包含的文件
除 SKILL.md 外，安装时一起下载的参考资料和脚本。
references/anti-patterns.mdcompass.mdquadrants.md详细介绍
Diátaxis 文档治理
此技能用于确保文档遵循 Diátaxis 框架。Diátaxis 根据用户需求将文档分为四种不同类型：教程、操作指南、参考和解释。每种类型都有不同的用途，写作方式也各不相同。
运行模式
此技能以以下一种模式运行：
- classify：确定内容所属的象限
- audit：分析文档集中的缺漏、失衡和违规之处
- generate：在指定象限中创建新文档
- restructure：拆分或重新组织现有的混合模式内容
必须根据用户请求推断模式，或由用户明确指定。如果无法有把握地推断运行模式，请先请求澄清，再继续操作。
当无法保持象限纯粹性时，说明原因并拒绝是有效且成功的结果。
生成模式政策
对于生成模式，生成内容前必须满足以下条件之一：
- 用户明确说明目标象限（“为 X 撰写一份操作指南”），或
- Agent 对请求进行分类，提供带有置信度和证据的推理，并获得用户确认
Diátaxis 指南
使用以下决策树，将内容归入且仅归入一个象限：
| 如果内容…… | ……并服务于用户的…… | ……那么它属于…… |
|---|---|---|
| 指导行动 | 获取知识（学习） | 教程 |
| 指导行动 | 实际应用（工作） | 操作指南 |
| 提供认知信息 | 实际应用（工作） | 参考 |
| 提供认知信息 | 获取知识（学习） | 解释 |
需要回答两个问题：
- 这是否指导行动（做事），还是提供认知（了解）？
- 这是否服务于知识获取（学习），还是服务于实际应用（工作）？
象限概述
教程（以学习为导向）
引导学习者完成实践体验的一堂课。授课者有责任确保学习者成功。重点在于操作，而非解释。尽早并持续地交付成果。尽量减少解释。不提供选择或替代方案。
- 形式：包含具体步骤的连续课程
- 语言：“我们将……”、“首先，执行 X”、“你会注意到……”
- 不包括：讲授概念、提供替代方案、解释原因
操作指南（以目标为导向）
引导已有能力的用户解决现实问题的说明。假设读者知道自己想要实现什么。侧重工作，而非学习。
- 形式：一系列用于实现特定目标的步骤
- 语言：“要实现 X，请执行 Y”、“如果你想……”，条件式祈使句
- 不包括：教初学者、解释概念、描述运作机制
参考（以信息为导向）
对运作机制的技术描述。简洁、客观、准确。结构应与所描述的对象相呼应。用户会查阅它，而非通读它。
- 形式：结构化描述、表格、规格
- 语言：“X 是……”、“选项包括……”，事实陈述
- 不包括：指导操作、解释原因、叙述、发表意见
解释（以理解为导向）
提供背景、背景信息并回答“为什么”的论述性说明。建立联系、承认观点，并从不同角度探讨主题。
- 形式：围绕主题展开的散文式讨论
- 语言：“X 的原因是……”、“这是因为……”、“试想……”
- 不包括：分步流程、技术规格、任务教学
核心工作流
分类
- 仔细阅读内容
- 应用指南：行动／认知 × 知识获取／实际应用
- 确定唯一所属象限
- 提供带有置信度和证据的判断
用于生成
- 确认目标象限（明确说明，或推断后与用户确认）
- 严格遵守象限约束
- 拒绝混合象限；如有需要，建议拆分
- 根据象限特征验证输出
用于审计
- 列出所有文档
- 对每份文档进行分类
- 找出缺口（缺失的象限）
- 标记违规（混合模式、象限错误）
- 报告失衡情况（例如，“参考资料过多，教程不足”）
用于重构
- 对现有内容进行分类
- 找出象限违规
- 提出拆分方案（每个象限一份文档）
- 在修改前提交方案，等待用户确认
输出要求
分类或标记违规时，务必提供：
- 象限：识别出的类型（教程、操作指南、参考、解释）
- 置信度：高 | 中 | 低
- 证据：具体短语、结构模式或信号
示例：
分类为操作指南（置信度高）。 证据：祈使动词（“配置”“设置”）、以目标为导向的标题、缺少概念性铺垫、假定读者具备相应能力。
违规检测
标记以下反模式：
- 带有解释的教程：冗长的“为什么”章节、概念性离题内容
- 具有教学意味的操作指南：面向初学者的表达、“让我们来学习”之类的措辞
- 带有叙述的参考资料：第一人称表达、过程性说明
- 包含操作流程的解释：编号步骤、祈使命令
- 混合模式文档：单份文档中出现多个象限信号
有关详细的检测模式和修正方法，请参阅 references/anti-patterns.md。
非目标
此技能不会：
- 制定文档策略或信息架构
- 决定产品架构或功能范围
- 将多个 Diátaxis 象限合并到同一份文档中
- 覆盖特定仓库的文档规则或风格指南
- 在未明确分类象限的情况下生成内容
其他资源
- 详细的象限特征：references/quadrants.md
- 分类决策树：references/compass.md
- 反模式与修正方法：references/anti-patterns.md
署名
Diátaxis 由 Daniele Procida 编写。此技能将 Diátaxis 框架编码，以供 AI Agent 使用。如需查看权威来源和完整文档，请访问 diataxis.fr。
许可协议为 CC-BY-SA 4.0。引用元数据可在 Diátaxis GitHub 仓库中查看。