Diataxis Docs skill for Codex
One page, one reader need. Codex inventories every docs page, labels its primary type with the acting-or-understanding and learning-or-working test, and lists what else is mixed in. It proposes navigation where each section holds one type, then restructures one section at a time with redirects and link checks, so the docs improve in shippable increments instead of a stalled rewrite.
curl -fsSL codexskills.dev/install.sh \ | sh -s -- diataxis-docsInstalls to ~/.agents/skills/diataxis-docs/ for every project on this machine.
curl -fsSL codexskills.dev/cli.mjs -o codex-skills.mjsnode codex-skills.mjs install diataxis-docsThe CLI also searches, updates and removes skills. Run it with no arguments to pick from a list. Needs Node 20.12+.
curl -fsSL codexskills.dev/install.sh \ | sh -s -- --project diataxis-docsInstalls to .agents/skills/diataxis-docs/ in the current repository. Commit it and everyone who runs Codex there gets it.
curl -fsSLO codexskills.dev/downloads/diataxis-docs.zipunzip -o diataxis-docs.zip -d ~/.agents/skills/The archive holds the skill folder with its generated agents/openai.yaml. Unzip into .agents/skills/ to scope it to a repo.
& ([scriptblock]::Create((irm codexskills.dev/install.ps1))) diataxis-docsPowerShell 5.1 or 7. Installs to %USERPROFILE%\.agents\skills\. Add -Project for the current repo.
104-line POSIX script. No sudo, no telemetry. Read install.sh
Use it in Codex
Start a prompt with $diataxis-docs, or pick it from /skills.
You can also just describe the task: Codex reads the description below and loads the playbook when your request matches.
What Codex reads before loading it
Organizes documentation with the Diataxis framework - classifies every page as tutorial, how-to guide, reference or explanation, splits pages that mix them, fixes navigation and writes new pages to the rules of their type. Produces a page inventory with a type per page and a restructuring plan done in small, shippable steps. Use when docs feel disorganised, users cannot find answers, a docs site is being restructured, pages mix step-by-step instructions with theory and API tables, or someone asks where a new page should go.
Use it when
- Users cannot find answers even though the content exists
- Pages mix step-by-step instructions, theory and option tables
- A docs site is being reorganised or a new section is being planned
Use something else when
- You need the docs site tooling, CI or versioning set up: use docs-as-code
- You want a scored audit of staleness and findability across the docs: use documentation-audit
- You are writing a single tutorial and need the craft of it: use tutorial-writing
How to check the result
Every inventoried page has one primary type, each navigation section holds only that type, moved URLs have redirects, and the build and link check pass.
The mistake it prevents
Renaming folders to the four types and declaring victory while the pages inside still mix lessons, procedures and reference tables.
Docs are organised well when every page serves one user need, a reader can tell from the navigation which kind of page they are about to open, and no page makes a learner wade through reference tables or makes an expert sit through a lesson.
The four types
Two questions classify any page: is the reader acting or understanding, and are they learning or working?
| Learning (acquiring skill) | Working (applying skill) | |
|---|---|---|
| Acting (practical steps) | Tutorial | How-to guide |
| Understanding (knowledge) | Explanation | Reference |
| Type | Reader’s state | Promise | Shape |
|---|---|---|---|
| Tutorial | New, wants to learn by doing | “Follow this and you will succeed” | One path, every step works, visible result each step |
| How-to guide | Competent, has a goal | “Here is how to accomplish X” | Goal in title, numbered steps, assumes knowledge, handles real-world variants |
| Reference | Working, needs a fact | “Here is exactly what exists” | Mirrors the structure of the product; consistent, complete, terse |
| Explanation | Stepping back, wants to understand | “Here is why it is this way” | Discursive, context, trade-offs, alternatives, history |
Quick test for a page: write the question it answers. “How do I…?” is a how-to. “What is the value of / what are the options for…?” is reference. “Why…?” or “What is the idea behind…?” is explanation. “Teach me…” is a tutorial.
Inspect first
cat AGENTS.md 2>/dev/null | head -60
find docs -name '*.md' -o -name '*.mdx' | sort | head -200 # page inventory
ls sidebars.* astro.config.* docs.json mkdocs.yml 2>/dev/null # current navigationRead the navigation config and the top 10 most-visited pages if analytics or search logs are available (ask the user). High-traffic pages are where mixing hurts most.
Workflow
- [ ] 1. Inventory every page: path, title, primary type, secondary types mixed in
- [ ] 2. Flag pages with more than one type, and gaps (a type missing for a key feature)
- [ ] 3. Propose a target navigation with the four types visible
- [ ] 4. Confirm the plan with the user (URLs will change)
- [ ] 5. Restructure one section at a time: split, move, add redirects, fix links
- [ ] 6. Fill the highest-value gaps (usually a missing tutorial or missing reference)
- [ ] 7. Rebuild, check links, and update the inventoryDo not big-bang a restructure. Diataxis is applied iteratively: pick one page, improve its fit to its type, ship, repeat. A half-finished global reorganisation is worse than the original.
Inventory format
| Page | Primary type | Also contains | Action |
|---|---|---|---|
| docs/getting-started.md | Tutorial | Reference (all config flags), Explanation (architecture) | Move flags table to reference/config.md; link explanation |
| docs/webhooks.md | How-to | Explanation (delivery semantics) | Split: how-to/receive-webhooks.md + explanation/webhook-delivery.md |
| docs/cli.md | Reference | none | Keep; generate from --help |
| (missing) | Tutorial for SDK | n/a | Write: tutorials/first-integration.md |Target navigation
Docs
├── Tutorials # 1-3 pages; a learner's first hour
├── How-to guides # grouped by task area, titles start with a verb
├── Reference # API, CLI, config, error codes; mirrors product structure
└── Explanation # concepts, architecture, design decisionsVariants that still respect the types: product areas as top level with the four types beneath each, or “Get started” (tutorial) plus “Guides” plus “Reference” plus “Concepts”. Labels may differ; what matters is that each section holds one type.
Rules per type
Tutorial
- One path; no options or “alternatively”. Pick the choices for the learner.
- Every step produces a visible result; show expected output.
- Minimal explanation: link to explanation pages instead of explaining inline.
- Must work every time on a clean setup. Test it end to end. Hand off the writing craft
to
$tutorial-writing.
How-to guide
- Title states the goal: “Rotate API keys without downtime”, not “API keys”.
- Assumes the reader knows the basics; start at the first real step.
- Cover real-world conditions (permissions, large data, production) with short conditional branches.
- No teaching asides. Link to explanation or reference.
Reference
- Structure mirrors the thing described (endpoints, commands, config keys in file order).
- Consistent entry format: name, type, default, description, example.
- Austere: no opinions, no tutorials. Warnings about dangerous values are allowed.
- Generate from source where possible (OpenAPI,
--help, schema) so it cannot drift.
Explanation
- Answers why: design rationale, trade-offs, alternatives considered, history, limits.
- May hold opinions and compare approaches.
- Title is a topic or question: “How sync conflicts are resolved”, “Why events are at-least-once”.
- No step-by-step instructions; link to the how-to.
Splitting a mixed page
- Identify the page’s dominant type from its title and the question users arrive with.
- Cut paragraphs of other types into new pages in the right section.
- Leave a one-line link where each cut paragraph was: “For why retries are capped at three, see Retry design.”
- Keep the original URL for the dominant-type page; add redirects for any moved URL.
- Rebuild and run the link check.
Signals of mixing
| Symptom | Mix | Fix |
|---|---|---|
| Getting-started page lists every config option | Tutorial + reference | Move options to reference; tutorial uses defaults |
| How-to opens with three paragraphs of history | How-to + explanation | Move history to explanation; start with step 1 |
| API reference entries contain “first, install the SDK…” | Reference + tutorial | Remove; link the quickstart |
| Concept page ends with a 15-step procedure | Explanation + how-to | Move steps to a how-to; link both ways |
| Page title is a single noun (“Authentication”) and covers everything | All four | Split into one page per type |
Gotchas
- Treating Diataxis as four folders and stopping there. The value is in each page obeying its type, not in the directory names.
- Renaming every URL to fit the new structure. Redirect all moved pages; check search console or analytics for inbound links before moving popular pages.
- Duplicating content across types. Write once in the right type and link.
- Tutorials that branch for every platform. Pick one; offer others as separate tutorials or as how-to guides.
- Forcing small projects into four sections with one page each. A README plus a reference page can be enough; apply the types at page level first.
Verification
- Every page in the inventory has exactly one primary type, and no page has unaddressed “also contains” entries in the restructured sections.
- Each nav section contains only its type; spot-check three pages per section.
- Build passes and link check is clean; redirects exist for every moved URL.
- Ask the user (or reread cold): for three common user questions, can you reach the answer from the navigation in two clicks?
Report
**Pages inventoried:** 64 (tutorial 2, how-to 21, reference 18, explanation 9, mixed 14)
**Changed this pass:** Webhooks section: 3 mixed pages split into 2 how-to + 2 explanation; 4 redirects added
**Gaps:** no tutorial for the Python SDK; no reference for error codes (both proposed)
**Next section:** Authentication (5 mixed pages)
**Links:** build and link check cleanWhat the zip contains
SKILL.md plus the interface file below. Nothing runs on install.
agents/openai.yaml
Gives the Codex app a display name, a one-line description and a starter prompt for this skill.
interface:
display_name: "Diataxis Docs"
short_description: "One page, one reader need"
default_prompt: "$diataxis-docs Our docs are a mess; classify every page with Diataxis and propose a new structure"About this skill
Written and maintained by the Codex Skills editors to the same editorial standard as every skill here: a selective description, a real workflow, known pitfalls and a way to verify the work. First published , last updated . MIT licensed. Something wrong or out of date? Tell us.