diataxis
Skill2 starsChanged 5 days agoMITView on GitHub
按 Diátaxis 框架判定文档类型并写作或重组文档:教程(tutorial)、操作指南(how-to)、参考(reference)、解释(explanation)。当用户要写文档、整理文档、规划 README 或 docs 目录、拆分混乱文档,或提到 Diátaxis、教程、操作指南、参考文档、解释性文档时使用。
12 other projects use a version of this.
Adopted by
Most recently taken up by
- rlespinasse/agent-skillstheir own version, first seen Nov 15, 2026
- pfeff/claude-skillstheir own version, first seen Nov 1, 2026
- geekatron/jerrytheir own version, first seen Nov 1, 2026
- ericmasiello/skillstheir own version, first seen Oct 20, 2026
- nstarman/skillstheir own version, first seen Oct 20, 2026
- inngest/websitetheir own version, first seen Oct 9, 2026
Other versions12 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 12
- event-driven-io/emmett★ 562same name
- WebMCP-org/npm-packages★ 104same name
- inngest/website★ 51same name
- joshuadavidthomas/agent-skills★ 49same name
- geekatron/jerry★ 37same name
- keithpatton/diataxis-agent-skill★ 18same name
- rlespinasse/agent-skills★ 13same name
- pfeff/claude-skills★ 4same name
- BlakeHastings/claude-code-artifacts★ 1same name
- nstarman/skills★ 1same name
2 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository5 other files it gives its agents.
- AGENTS.mdAGENTS.md
- conventional-commitSkill
- grillSkill
- release-notesSkill
- tddSkill
The file
Files
Diátaxis 文档框架
Diátaxis 用两个轴把文档分成四类:行动 / 认知(读者是在做事还是在理解)与学习 / 工作(读者是在学还是在用)。每篇文档只服务一种需求,混装就拆。
何时使用
使用本技能:
- 要写或改一篇文档,需要先确定它属于哪一类。
- 现有
docs/、README、Wiki 结构混乱,需要分类、拆分、重组。 - 要规划文档目录、导航、交叉链接。
- 用户提到 Diátaxis、教程、操作指南、参考、解释性文档。
不适用:
- 纯问答、单段文案、一次性说明。
- 只需排版或格式转换(交给
md-to-docx等技能)。
四象限速查
| 象限 | 读者状态 | 内容性质 | 回答的问题 | 成功标准 | 典型标题 |
| Tutorial 教程 | 学习 | 行动 | 我该怎么开始? | 跟着做完能得到可运行结果 | 入门教程、第一个 X、从零搭建 |
| How-to 操作指南 | 工作 | 行动 | 我该怎么完成 X? | 能解决一个具体任务 | 如何配置 X、如何迁移到 Y |
| Reference 参考 | 工作 | 认知 | X 是什么?有哪些参数? | 查得到、准确、完整 | API 参考、配置项、命令手册 |
| Explanation 解释 | 学习 | 认知 | 为什么会这样? | 理解背景、原理与取舍 | 架构说明、设计取舍、概念解析 |
判定口诀:
- 教程是老师带着学生走一遍。
- 指南是给有目标的人一份路线图。
- 参考是字典,只陈述事实。
- 解释是文章,讲来龙去脉。
三步定位
- 找真实需求:读者此刻想做什么、已经知道什么。不要按「我想写什么」分类。
- 两轴定位:先问「他在学习还是在工作」,再问「他要动手还是要理解」。
- 强制单一形态:一篇文档只能占一个象限。出现第二种需求时,拆成两篇并互相链接。
边界模糊时:选主要需求所在的象限,把次要内容压缩成一句链接指向另一篇。
写作规则
Tutorial 教程
- 面向零基础,假设读者什么都不懂。
- 一条主线、可复现、每步都有可见结果。
- 先给终态,再带读者走到终态。
- 语言:「我们将……」「你会看到……」。
骨架:目标与成品 → 前置条件 → 分步操作(每步含命令/代码与预期输出)→ 验证结果 → 下一步。
禁止:罗列全部参数、插入大段原理、给多个可选分支。
How-to 操作指南
- 面向有基础、有明确目标的读者。
- 直接给步骤,不教概念。
- 标题写成任务句:「如何……」「……时怎么办」。
- 语言:「如果你想 X,就做 Y」。
骨架:适用场景 → 前置条件 → 步骤(编号、可跳读)→ 验证 → 常见问题。
禁止:从零讲起、长篇背景、把教程步骤照搬。
Reference 参考
- 面向正在工作、需要查证的读者。
- 结构化、可扫描、与代码/配置一一对应。
- 只陈述事实,不评价、不引导。
- 语言:「X 是……」「参数
a控制……」。
骨架:概述一句 → 签名/字段/参数表 → 返回值/错误 → 约束与默认值 → 示例(最小)。
禁止:教程式叙述、主观建议、缺省值缺失、与实现不一致。
Explanation 解释
- 面向想理解「为什么」的读者。
- 可以发散、给背景、对比方案、讲取舍。
- 不承担操作步骤,必要时链接到教程或指南。
- 语言:「之所以……是因为……」「另一种做法是……」。
骨架:问题背景 → 核心概念 → 原理/机制 → 取舍与替代方案 → 延伸阅读。
禁止:步骤清单、参数表、把参考内容抄一遍。
审计与重组流程
- 盘点:列出所有文档及其标题、首段、目录层级。
- 打标:逐篇标一个象限;标不出的,说明它没有明确读者需求。
- 找混装:一篇里出现两种语言特征(如教程里夹参数表)即为混装。
- 拆分:按象限切开,各自补齐骨架,保留原文链接避免断链。
- 重组目录:可按象限分目录(
tutorials/、how-to/、reference/、explanation/),也可按主题分目录、象限做标签;小项目优先按读者路径组织。 - 补导航:入口页按「我想学 / 我想做 / 我想查 / 我想懂」四问分流。
- 回归检查:用
references/audit-checklist.md逐项过一遍。
常见反模式
| 反模式 | 症状 | 修正 |
| 教程变手册 | 步骤中插入完整参数表 | 参数移到参考,教程只留用到的值 |
| 指南塞原理 | 开头三段讲历史 | 原理移到解释,指南开头一句链接 |
| 参考夹观点 | 「推荐使用 X,因为……」 | 事实留参考,建议移到解释或指南 |
| 解释写步骤 | 「第一步、第二步……」 | 步骤移到指南,解释只讲为什么 |
| 一篇通吃 | 标题是「X 文档」 | 按四象限拆成多篇 |
| 假教程 | 只有概念没有可运行结果 | 补一条能跑通的主线 |
自检
- 每篇只占一个象限。
- 标题能看出读者需求。
- 教程可复现,指南可跳读,参考可扫描,解释有观点。
- 跨篇引用用链接,不复制内容。
- 术语、命令、参数与实现一致。
references 索引
- 写教程:
references/tutorial-template.md - 写操作指南:
references/how-to-template.md - 写参考:
references/reference-template.md - 写解释:
references/explanation-template.md - 审计现有文档:
references/audit-checklist.md
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

