Przejdź do treści
Biblioteka skilli
Dokumenty i biuro · Pisanie

diataxis

/diataxis

Określa typ dokumentu według Diátaxis (tutorial, how-to, referencja, wyjaśnienie) i pomaga go napisać lub uporządkować.

Licencja
MIT
Ostatnia zmiana repozytorium
12.11.2026

Ocena i bezpieczeństwo

90/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść25 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
6
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

Brak sygnałów. Repozytorium zmienione 12.11.2026, bez odwołań do wycofanych modeli i API.

Licencja

MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.

Co robi i kiedy

Określa typ dokumentu według Diátaxis (tutorial, how-to, referencja, wyjaśnienie) i pomaga go napisać lub uporządkować.

Oryginalny opis (EN)

按 Diátaxis 框架判定文档类型并写作或重组文档:教程(tutorial)、操作指南(how-to)、参考(reference)、解释(explanation)。当用户要写文档、整理文档、规划 README 或 docs 目录、拆分混乱文档,或提到 Diátaxis、教程、操作指南、参考文档、解释性文档时使用。

Jak działa

  1. 何时使用
  2. 四象限速查
  3. 三步定位
  4. 写作规则
  5. 审计与重组流程
  6. 常见反模式
  7. 自检
  8. references 索引
Sekcje z nagłówków SKILL.md, w oryginale · 126 linii, 346 słów
Podgląd SKILL.md
---
name: diataxis
description: 按 Diátaxis 框架判定文档类型并写作或重组文档:教程(tutorial)、操作指南(how-to)、参考(reference)、解释(explanation)。当用户要写文档、整理文档、规划 README 或 docs 目录、拆分混乱文档,或提到 Diátaxis、教程、操作指南、参考文档、解释性文档时使用。
---

# 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`
Pliki w paczce (6)
  • SKILL.md 6 KB
  • references/audit-checklist.md 2 KB
  • references/explanation-template.md 2 KB
  • references/how-to-template.md 2 KB
  • references/reference-template.md 2 KB
  • references/tutorial-template.md 2 KB

Wersje

RepozytoriumWynikLicencja
Ta strona · yearzen1/LocalSkillManager90MIT
rlespinasse/agent-skills100MIT
shepherdjerred/monorepo100GPL-3.0
geekatron/jerry100Apache-2.0
juspay/kolu100AGPL-3.0
joshuadavidthomas/agent-skills100MIT
kamp-us/phoenix90MIT
pproenca/dot-skills90MIT
zircote-plugins/documentation-review87MIT

Migawka bazy z 13.11.2026 · wersja paczki 0520488b0a83 (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 100diataxis-docs
    Generuje pełny zestaw dokumentacji Diátaxis (tutoriale, how-to, referencja, wyjaśnienia) z bazy kodu, wyłącznie na jawne wywołanie /diataxis-docs.
  • 100diataxis-write-docs
    Pisze lub poprawia dokumentację projektu pod cel czytelnika według Diataxis: tutoriale, przewodniki how-to, referencję i wyjaśnienia.
  • 100documentation
    Tworzy, strukturyzuje i przegląda dokumentację techniczną według frameworka Diátaxis: tutoriale, przewodniki how-to, referencje i strony wyjaśniające.
  • 90dev-workflow
    Obsługuje standardowe operacje na GitHubie przez gh CLI i porządkuje dokumentację w układzie Diátaxis.
  • 100user-docs
    Pisze krótką dokumentację dla użytkowników i deweloperów, skanując ekrany i publiczne API, w standardzie Diátaxis: samouczki, instrukcje, opisy.
  • 100docs-author
    Pisze dokumentację w Markdown, dobierając właściwy typ Diátaxis (tutorial, how-to, reference, background), tytuł i streszczenie, oraz dopracowuje język dla globalnego angielskiego i usuwa ślady AI.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.