agentleFS
yearzen1yearzen1/LocalSkillManager/.agents/skills/diataxis/SKILL.md

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

The file

Files
SKILL.md

Diátaxis 文档框架

Diátaxis 用两个轴把文档分成四类:行动 / 认知(读者是在做事还是在理解)与学习 / 工作(读者是在学还是在用)。每篇文档只服务一种需求,混装就拆。

何时使用

使用本技能:

  • 要写或改一篇文档,需要先确定它属于哪一类。
  • 现有 docs/、README、Wiki 结构混乱,需要分类、拆分、重组。
  • 要规划文档目录、导航、交叉链接。
  • 用户提到 Diátaxis、教程、操作指南、参考、解释性文档。

不适用:

  • 纯问答、单段文案、一次性说明。
  • 只需排版或格式转换(交给 md-to-docx 等技能)。

四象限速查

象限读者状态内容性质回答的问题成功标准典型标题
Tutorial 教程学习行动我该怎么开始?跟着做完能得到可运行结果入门教程、第一个 X、从零搭建
How-to 操作指南工作行动我该怎么完成 X?能解决一个具体任务如何配置 X、如何迁移到 Y
Reference 参考工作认知X 是什么?有哪些参数?查得到、准确、完整API 参考、配置项、命令手册
Explanation 解释学习认知为什么会这样?理解背景、原理与取舍架构说明、设计取舍、概念解析

判定口诀:

  • 教程是老师带着学生走一遍。
  • 指南是给有目标的人一份路线图。
  • 参考是字典,只陈述事实。
  • 解释是文章,讲来龙去脉。

三步定位

  1. 找真实需求:读者此刻想做什么、已经知道什么。不要按「我想写什么」分类。
  2. 两轴定位:先问「他在学习还是在工作」,再问「他要动手还是要理解」。
  3. 强制单一形态:一篇文档只能占一个象限。出现第二种需求时,拆成两篇并互相链接。

边界模糊时:选主要需求所在的象限,把次要内容压缩成一句链接指向另一篇。

写作规则

Tutorial 教程

  • 面向零基础,假设读者什么都不懂。
  • 一条主线、可复现、每步都有可见结果。
  • 先给终态,再带读者走到终态。
  • 语言:「我们将……」「你会看到……」。

骨架:目标与成品 → 前置条件 → 分步操作(每步含命令/代码与预期输出)→ 验证结果 → 下一步。

禁止:罗列全部参数、插入大段原理、给多个可选分支。

How-to 操作指南

  • 面向有基础、有明确目标的读者。
  • 直接给步骤,不教概念。
  • 标题写成任务句:「如何……」「……时怎么办」。
  • 语言:「如果你想 X,就做 Y」。

骨架:适用场景 → 前置条件 → 步骤(编号、可跳读)→ 验证 → 常见问题。

禁止:从零讲起、长篇背景、把教程步骤照搬。

Reference 参考

  • 面向正在工作、需要查证的读者。
  • 结构化、可扫描、与代码/配置一一对应。
  • 只陈述事实,不评价、不引导。
  • 语言:「X 是……」「参数 a 控制……」。

骨架:概述一句 → 签名/字段/参数表 → 返回值/错误 → 约束与默认值 → 示例(最小)。

禁止:教程式叙述、主观建议、缺省值缺失、与实现不一致。

Explanation 解释

  • 面向想理解「为什么」的读者。
  • 可以发散、给背景、对比方案、讲取舍。
  • 不承担操作步骤,必要时链接到教程或指南。
  • 语言:「之所以……是因为……」「另一种做法是……」。

骨架:问题背景 → 核心概念 → 原理/机制 → 取舍与替代方案 → 延伸阅读。

禁止:步骤清单、参数表、把参考内容抄一遍。

审计与重组流程

  1. 盘点:列出所有文档及其标题、首段、目录层级。
  2. 打标:逐篇标一个象限;标不出的,说明它没有明确读者需求。
  3. 找混装:一篇里出现两种语言特征(如教程里夹参数表)即为混装。
  4. 拆分:按象限切开,各自补齐骨架,保留原文链接避免断链。
  5. 重组目录:可按象限分目录(tutorials/、how-to/、reference/、explanation/),也可按主题分目录、象限做标签;小项目优先按读者路径组织。
  6. 补导航:入口页按「我想学 / 我想做 / 我想查 / 我想懂」四问分流。
  7. 回归检查:用 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

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.