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

diataxis

/diataxis

Klasyfikuje, pisze i audytuje dokumentację według Diátaxis (tutoriale, przewodniki how-to, referencja, wyjaśnienia), z kompasem jako procedurą decyzyjną, regułami każdej ćwiartki i wykonywalnym audytem trybów mieszanych.

Repozytorium
kolu ↗
Licencja
AGPL-3.0
Ostatnia zmiana repozytorium
23.10.2026

Ocena i bezpieczeństwo

100/ 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ść35 / 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
1
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

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

Licencja

AGPL-3.0, copyleft: przeróbki udostępniane innym muszą mieć tę samą licencję.

Co robi i kiedy

Klasyfikuje, pisze i audytuje dokumentację według Diátaxis (tutoriale, przewodniki how-to, referencja, wyjaśnienia), z kompasem jako procedurą decyzyjną, regułami każdej ćwiartki i wykonywalnym audytem trybów mieszanych.

Argumenty

/diataxis [classify <doc>|audit <path>|write <quadrant> <topic>]
Oryginalny opis (EN)

Classify, write, and audit documentation per Diátaxis (diataxis.fr) — the four-quadrant method (tutorials · how-to guides · reference · explanation). Encodes the compass as a decision procedure, each quadrant's contract as hard rules, and an executable mixed-mode audit. Project-agnostic; the per-repo doc-location mapping lives in a repo rule of the project's own (kolu: the Kolu overlay below). Use when writing any user-facing doc, structuring a docs site, or auditing existing docs for mixed modes.

Jak działa

  1. The compass (two questions, one quadrant — a doubt-resolver, applicable to a whole doc OR
  2. The four contracts (hard rules, per quadrant)
  3. The audit (executable — run over an existing doc set)
  4. Project overlay
  5. Writing procedure (every new doc)
  6. Kolu Diátaxis overlay
Sekcje z nagłówków SKILL.md, w oryginale · 138 linii, 1 237 słów
Podgląd SKILL.md
---
name: diataxis
description: Classify, write, and audit documentation per Diátaxis (diataxis.fr) — the four-quadrant method (tutorials · how-to guides · reference · explanation). Encodes the compass as a decision procedure, each quadrant's contract as hard rules, and an executable mixed-mode audit. Project-agnostic; the per-repo doc-location mapping lives in a repo rule of the project's own (kolu: the Kolu overlay below). Use when writing any user-facing doc, structuring a docs site, or auditing existing docs for mixed modes.
argument-hint: "[classify <doc>|audit <path>|write <quadrant> <topic>]"
---

# Diátaxis — classify, write, audit

Diátaxis's claim: documentation fails when one page serves two masters. Every
doc serves exactly ONE of four needs, derived from two axes — is the reader
**acquiring** skill (study) or **applying** it (work)? do they need **action**
(practical steps) or **cognition** (knowledge)? One doc, one quadrant, always;
other modes are LINKS, never inlined sections.

**Provenance:** the compass and the four contracts quote/paraphrase diataxis.fr
(Procida); the SMELLS lists, the entry template, the audit, and the writing
procedure are THIS SKILL's operationalization — useful, but do not cite them as
Diátaxis. (Diátaxis is the needs-grounded, iterative successor of the older
Divio four-types system.) Foundation the method stands on: documentation serves
USER NEEDS, not the machinery — the four types enumerate practitioner needs:
tutorials answer "can you teach me to…?", how-tos "how do I…?", reference "what
is…?", explanation "why…?".

## The compass (two questions, one quadrant — a doubt-resolver, applicable to a whole doc OR a single sentence)

| | serves ACTION (practical) | serves COGNITION (theoretical) |
| --- | --- | --- |
| **ACQUISITION** (study — the reader is learning) | **Tutorial** | **Explanation** |
| **APPLICATION** (work — the reader is doing their job) | **How-to guide** | **Reference** |

The source's own use: reach for it "when you think you are doing one thing but
are troubled by doubt" — at document, section, or sentence level. If a doc can't
answer both questions, it has no single reader (splitting it is this skill's
procedure, not a source rule). Mixed modes blur toward map-NEIGHBOURS (tutorial↔
how-to, how-to↔reference, reference↔explanation, explanation↔tutorial) — the
sharpest mixed-mode predictor.

## The four contracts (hard rules, per quadrant)

### Tutorial — a lesson: the reader learns by DOING, and YOU own their success
- The reader is a beginner at THIS thing; you are the teacher and their success
  is your responsibility. One concrete path, start to visible result.
- RULES: deliver visible results early and often; concrete and particular, not
  general and abstract; "ignore options and alternatives" (source's words) — one
  path, no branches; minimum necessary explanation, link to Explanation instead;
  must work every time for every reader (our test method: run it cold);
  first-person plural ("we are in this together"); keep a narrative of
  expectations ("You will notice that…"); encourage and PERMIT repetition —
  "sometimes it's the only teacher".
- SMELLS: paragraphs of why; configuration choices offered; "you may want to";
  steps that assume prior setup the tutorial didn't do.

### How-to guide — a recipe: a COMPETENT user has a GOAL, get them to it
- The reader already has the skill; they have a real-world task NOW.
- RULES: name it "How to <achieve the goal>" (the goal, not the tool); a
  SEQUENCE of actions addressing the task, including its real-world variance
  (unlike a tutorial, forks for real conditions are fine); assume competence —
  no teaching, no concept-building; omit everything not needed for THIS task;
  completeness is measured by the task, not the machinery.
- SMELLS: defining terms; explaining internals; covering every option "for
  completeness"; starting from installation when the goal is elsewhere.

### Reference — a map: austere, complete FACTS about the machinery
- The reader is working and needs to LOOK SOMETHING UP; certainty and
  consistency are the product.
- RULES: describe, never instruct and never explain; structure mirrors the
  structure of the PRODUCT (code-mirroring is the auto-generated special case);
  consistent, standard patterns per entry (a uniform template like signature ·
  description · constraints · examples is OUR operationalization); examples are
  encouraged as illustration; "wholly authoritative — truth and certainty, firm
  platforms on which to stand"; austere, neutral; auto-generation from source is
  a powerful way to keep it faithful.
- SMELLS: "you should"; step sequences; design rationale; entries that exist
  only for some exports; prose that varies format entry to entry.

### Explanation — understanding: the WHY, read away from the keyboard
- The reader wants the bigger picture: design decisions, context, alternatives,
  connections, history. The only quadrant where opinion and discussion belong.
- RULES: admit perspective ("the reason this is shaped so…"); make connections
  (to other parts, to prior art, to rejected designs); no instructions, no
  obligation to be complete; the source's test — the only docs it might make
  sense to read IN THE BATH, away from the product. (Our house addition, not
  Diátaxis: end at a real decision or trade-off — teaching without a point is a
  tour.)
- SMELLS: step-by-steps; API tables; pretending neutrality about a choice the
  project deliberately made.

## The audit (executable — run over an existing doc set)

For each doc under the target path, as parallel checks (a Workflow fan-out for
large sets; direct reads for small ones):
1. **Classify:** which quadrant does its title/frontmatter CLAIM? Which does
   the compass actually assign? Mismatch = finding.
2. **Mixed-mode detection, by marker:** instruction verbs + numbered steps in
   Reference; rationale/"because"/design-history paragraphs in Tutorials and
   How-tos; API signatures/exhaustive tables in Explanation; options and
   branches in Tutorials. Each hit: quote the passage, name the quadrant it
   belongs to, propose the split (extract + cross-link — never delete the
   content).
3. **Coverage:** for each major component in scope, which quadrants EXIST vs
   are MISSING — grounded in the map's "cycle of interaction": users mature
   from study to work and back, so reference-only fails newcomers and
   tutorial-only fails practitioners. Report the grid; per the process rule
   above, the grid PRIORITIZES, it does not mandate filling every cell.
4. Disposition per Diátaxis's OWN process rule — the method "is not a plan":
   improve organically, in small responsive iterations; never create empty
   quadrant structures to fill later; every step in the right direction is
   worth publishing immediately. So: fix the worst blur first, one doc at a
   time; "recorded, next iteration" IS a valid disposition here (unlike code
   review) — but silent acceptance still isn't. Docs are "always complete,
   never finished".

## Project overlay

Read the project's own Diátaxis overlay if it has one — the rule that records
where each quadrant LIVES in that project (paths, site sections, frontmatter
conventions), plus any project rules. In kolu that rule is
the Kolu overlay below. Missing overlay → classify/audit
generically and SAY so.

## Writing procedure (every new doc)

1. Run the compass; state the quadrant (frontmatter or the doc's one-liner).
2. Write to that quadrant's contract; when another mode wants in, LINK to it.
3. Self-audit against the quadrant's SMELLS list before declaring done.

## Kolu Diátaxis overlay

Where each quadrant lives in this project, for anyone classifying or auditing
kolu's docs per Diátaxis.

| quadrant | home today | notes |
| --- | --- | --- |
| Tutorial | Product: `website/src/content/docs/from-a-mac.mdx` (Mac window, Linux computer), `first-five-minutes.mdx`. Framework: `website/src/content/surface/your-first-surface.mdx` | one path, no branches; first-session pages do not name padi / kaval / surface |
| How-to | Product: `website/src/content/docs/` pages in Use Kolu / Operate / Command Line (`quickstart`, `remote-access`, `remote-hosts`, `deployment`, …). Framework: remaining `/surface` guides | |
| Reference | Surface `ref-*.mdx`; product `keyboard-shortcuts.mdx` | package READMEs stay the package-level map |
| Explanation | Product: `philosophy.mdx`, `architecture.mdx`, `concepts.mdx` | Architecture and Surface are builder docs, linked from the footer, not the top nav |

Project rules: Product first-session pages (Start, Quickstart, From a Mac, First
Five Minutes) stay in Tutorial / How-to voice: a job, then steps, then a link
out. The `@kolu/surface` site at `kolu.dev/surface` is the four-quadrant home for
the framework.

Wersje

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

Migawka bazy z 13.11.2026 · wersja paczki 39c8a96c3d5a (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.
  • 100make-docs
    Tworzy, edytuje i waliduje dokumentację techniczną według frameworka Diataxis: tutoriale, przewodniki how-to, dokumentację referencyjną i wyjaśnienia, a także audytuje strukturę istniejących dokumentów.
  • 90writing-documentation-with-diataxis
    Tworzy lub ocenia dokumentację techniczną według Diataxis: samouczki, instrukcje, dokumentację referencyjną i wyjaśnienia.
  • 82docs-writing
    Pisze, restrukturyzuje i recenzuje dokumentację (tutoriale, przewodniki how-to, strony referencyjne, README, changelogi, noty wydania, troubleshooting) według Diátaxis oraz przewodników stylu Mintlify, Google i Microsoft.
  • 100docs-writing
    Pisze, restrukturyzuje i audytuje dokumentację według typów Diataxis oraz tworzy strony dokumentacji funkcji i źródła diagramów.

Uwagi i zgłoszenia

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