[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M75MSTQ54EY0K29PKBF212K1":3,"skill-same:01M75MSTQ54EY0K29PKBF212K1":47},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":24,"commitSha":25,"skillDirectory":26,"forksCount":27,"repositoryHtmlUrl":28,"repositoryHomepageUrl":29,"ownerHtmlUrl":30,"ownerBlogUrl":6,"ownerDescription":31,"updatedAt":32,"install":33,"resources":46},"01M75MSTQ54EY0K29PKBF212K1","writing-docs",null,"Use when writing, restructuring, or reviewing any prose documentation — a tutorial, how-to guide, reference page, or explanation\u002Fconceptual doc — for a public docs site (e.g. Mintlify MDX, docs\u002F, README material), a getting-started guide, an API\u002FCLI reference page, or a \"why we built it this way\" conceptual page. Applies the Diátaxis framework (see https:\u002F\u002Fdiataxis.fr\u002F) — every document belongs to exactly one of the four quadrants (tutorial \u002F how-to guide \u002F reference \u002F explanation), and mixing quadrants inside one document is the single most common documentation failure. Covers the four-quadrant compass for picking the right form, per-quadrant structure templates, an anti-pattern list for quadrant drift, and generic voice\u002Fcraft rules — repo-specific voice and target output format (e.g. Mintlify MDX) are resolved from the repo's docs-manifest (falling back to project-context), never hardcoded here.","whimzyLive\u002Fnightshift-ai","whimzyLive","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F22066605?v=4","01M75MMH22XX6R3NTAFHD7HEN7","Rushi Patel","01M75MMH32DHVVC61XRSHWVEV2",3,"MIT","https:\u002F\u002Fgithub.com\u002FwhimzyLive\u002Fnightshift-ai\u002Fblob\u002Fmain\u002Fplugins\u002Fsdlc\u002Fskills\u002Fwriting-docs\u002FSKILL.md",[],[],"2026-11-12 13:55:43",false,"---\nname: writing-docs\ndescription: Use when writing, restructuring, or reviewing any prose documentation — a tutorial, how-to guide, reference page, or explanation\u002Fconceptual doc — for a public docs site (e.g. Mintlify MDX, docs\u002F, README material), a getting-started guide, an API\u002FCLI reference page, or a \"why we built it this way\" conceptual page. Applies the Diátaxis framework (see https:\u002F\u002Fdiataxis.fr\u002F) — every document belongs to exactly one of the four quadrants (tutorial \u002F how-to guide \u002F reference \u002F explanation), and mixing quadrants inside one document is the single most common documentation failure. Covers the four-quadrant compass for picking the right form, per-quadrant structure templates, an anti-pattern list for quadrant drift, and generic voice\u002Fcraft rules — repo-specific voice and target output format (e.g. Mintlify MDX) are resolved from the repo's docs-manifest (falling back to project-context), never hardcoded here.\n---\n\n# writing-docs — Diátaxis documentation authoring\n\n**Core principle:** a documentation page serves exactly ONE of four distinct reader needs —\nlearning, doing, looking something up, or understanding — and trying to serve two at once makes\nit worse at both. If you find a document explaining theory in the middle of a set of steps, or a\nreference page arguing for why a default was chosen, that's not richness, that's quadrant drift,\nand the fix is to split it, not to smooth it over.\n\n**Announce at start:** \"I'm using the writing-docs skill to author\u002Freview this doc.\"\n\n## Canonical source\n\nThis skill distills [Diátaxis](https:\u002F\u002Fdiataxis.fr\u002F) (Daniele Procida) — read the live site for\nthe full treatment; the four-quadrant model, the compass, and the per-quadrant principles below\nare drawn from it directly, not invented here. When in doubt about an edge case this skill\ndoesn't cover, the canonical source is the tiebreaker.\n\n## When to Use\n\n- Whenever you're about to write or substantially restructure a prose documentation page —\n  a tutorial, a how-to guide, a reference page, or an explanation\u002Fconceptual page — for a public\n  docs site or any repo documentation meant to be read (not a code comment, not an ADR — ADRs\n  have their own `writing-adrs` skill and their own format for a different purpose: a permanent\n  decision log, not reader-facing product\u002Fproject documentation).\n- When the sdlc docs pipeline (`\u002Fsdlc:docs` command + `knowledge-engineer` agent) generates or\n  updates a doc page — in a repo where that pipeline is adopted.\n- When reviewing an existing doc and something feels \"off\" — the compass below is exactly the\n  tool for diagnosing which quadrant a page has drifted out of.\n\n## Why Diátaxis\n\nDiátaxis starts from an observation: documentation readers don't have one kind of need, they have\nfour, and each is genuinely different in what it demands of the writing:\n\n- Someone **learning** a system wants a safe, guided experience with visible results at every\n  step — they need a **tutorial**.\n- Someone already competent, trying to **get something done**, wants directions to a specific\n  goal — they need a **how-to guide**.\n- Someone **working** who needs a fact — a parameter's type, a flag's behaviour, a field's\n  default — wants to look it up fast and trust it completely — they need **reference**.\n- Someone trying to **understand** why something is the way it is wants context, discussion, and\n  connections drawn — they need **explanation**.\n\nThese four needs pull writing in different, often incompatible, directions — a page that's trying\nto teach AND to be quickly-scannable AND to argue for a design choice is failing all three\npurposes at once, because good tutorial prose is _slow and narrated_, good reference prose is\n_austere and fact-only_, and good explanation prose is _discursive and opinionated_ — you cannot\nwrite in all three registers on the same page and have any of them land well. **One document, one\nquadrant, one register.** This is the one-doc-one-quadrant discipline: every page you write should\nbe identifiable, from its first paragraph, as belonging to exactly one of the four.\n\n## The Four Quadrants\n\n| Quadrant | Serves | Oriented toward | Reader is… |\n| --- | --- | --- | --- |\n| **Tutorial** | Learning (study) | Action + skill acquisition | A student, guided step by step |\n| **How-to guide** | Doing (work) | Action + skill application | A competent practitioner with a goal |\n| **Reference** | Looking up | Cognition + skill application | Someone who needs a fact, fast |\n| **Explanation** | Understanding | Cognition + skill acquisition | Someone reflecting, away from the task |\n\n### Tutorial\n\nA lesson, not a demo. The author takes full responsibility for the reader's success: every step\nmust produce a visible, meaningful result, in a fixed, reliable order, with no branching and no\noptional choices — a tutorial is not the place to offer options. Ruthlessly minimize explanation\ninline (link out to it instead); explanation offered mid-lesson breaks the reader's flow and\nteaches the wrong lesson about how to learn. Aim for total reliability: a tutorial that fails\npartway destroys the confidence it exists to build.\n\n### How-to guide\n\nA recipe for someone who already knows the basics and wants a specific, real result. Written from\nthe user's goal, never from the tool's operations (\"how to configure X for zero-downtime\ndeploys,\" not \"how to click the deploy button\"). Action only — no teaching, no theory, no\ncompleteness-for-its-own-sake. It's fine, even expected, for a how-to guide to branch, to skip\nsteps a competent reader doesn't need, and to link out to reference for the full option list\nrather than enumerating every flag inline.\n\n### Reference\n\nDescription, and only description, of the machinery: an API, a CLI, a config schema, a set of\nfields. Austere, neutral, structured to mirror the actual structure of the thing it describes (one\nentry per symbol\u002Fcommand\u002Ffield, consistent shape throughout) — a reader consults it, doesn't read\nit front to back. No narrative, no opinion, no \"you should,\" no \"we chose this because\" — those\nbelong in explanation or a how-to guide; link to them instead of importing them.\n\n### Explanation\n\nDiscussion, at a distance from the task at hand — the only quadrant where opinion, alternatives,\nand \"why\" belong. Explanation is understanding-oriented: it draws connections, gives context and\nhistory, and is honestly allowed to argue a position (\"X is better than Y here because …\") in a\nway none of the other three quadrants may. Where a documented architectural decision already\nexists as an ADR, an explanation page should **link to the source ADR(s)** under `docs\u002Fadr\u002F`\nrather than re-deriving or duplicating the reasoning — the ADR is the durable, single source of\ntruth for _why_; the explanation page's job is to make that reasoning accessible and readable in\ncontext, not to fork it into a second copy that can drift.\n\n## The Compass — choosing the right quadrant\n\nWhen it's unclear which quadrant a piece of content belongs to, ask two questions rather than\ntrusting a first instinct (per Diátaxis's own compass — a genuine decision tool, not a mnemonic):\n\n1. Does this content inform **action** (doing\u002Fpractical steps) or **cognition** (thinking\u002Ffacts)?\n2. Does it serve **acquisition** (the reader is studying, building a skill) or **application** (the\n   reader already has the skill and is using it)?\n\n| Informs… | Serves… | → Quadrant |\n| --- | --- | --- |\n| Action | Acquisition | Tutorial |\n| Action | Application | How-to guide |\n| Cognition | Application | Reference |\n| Cognition | Acquisition | Explanation |\n\nApply the compass at the level of a whole page when deciding where new content belongs, and at\nthe level of a paragraph or sentence when a page feels like it's drifting — a single sentence of\nexplanation dropped into the middle of a how-to guide's steps is exactly the kind of drift the\ncompass catches that a first read-through can miss.\n\n## Anti-Patterns\n\nEvery one of these is the same underlying failure — a document doing the job of a different\nquadrant — expressed four different ways. Catch these before publishing:\n\n| Anti-pattern | Why it fails | Fix |\n| --- | --- | --- |\n| **Tutorial drifting into reference** — the lesson pauses to enumerate every option, flag, or edge case at the step where one is first used | Breaks the guided-lesson flow; the learner didn't ask for completeness, they asked to be shown one path | Use the one path the tutorial needs; link to the reference page for the full option list |\n| **How-to guide explaining theory** — steps are interrupted by \"this works because…\" or a design-rationale digression | Distracts from the action the competent reader came to perform; if they wanted why, they'd be reading explanation | State the action plainly; link out to an explanation page for the \"why,\" don't inline it |\n| **Reference containing narrative or opinion** — a field's doc says \"you should probably set this to…\" or defends why a default was chosen | Undermines the neutrality reference exists to provide — a reader consulting reference wants facts, not a case being made | Strip to neutral fact (\"Default: `false`.\"); move any judgement or rationale to a how-to guide or explanation |\n| **Explanation giving step-by-step instructions** — a conceptual\u002Fbackground page turns into a numbered procedure partway through | Conflates two registers a reader can't hold at once — reflective reading and procedural following require different modes | Keep explanation discursive; link to the how-to guide or tutorial that has the actual steps |\n\n## Per-Quadrant Structure Templates\n\nUse the quadrant's template as a starting skeleton, not a rigid form — omit a section that\ngenuinely doesn't apply, but don't add sections that belong to a different quadrant.\n\n### Tutorial template\n\n```markdown\n---\ntitle: TODO(fill) learning-oriented title, matching the H1 below\ndescription: TODO(fill) one line, used verbatim as the llms.txt description\n# related-adrs: repo-root-relative docs\u002Fadr\u002FNNNN-*.md paths this page depends on; audit's\n# ADR-drift flag reads it. Leave [] unless the page genuinely references an accepted ADR.\nrelated-adrs: []\n---\n\n# [Learning-oriented title, e.g. \"Getting started with X\"]\n\n[One or two sentences: what the reader will build\u002Fachieve, stated plainly — not \"in this\ntutorial you will learn,\" just what they'll do. Sets expectations before the first step.]\n\n## Prerequisites\n\n[Concrete, minimal — what must already be true\u002Finstalled before starting.]\n\n## Step 1: [Concrete first action]\n\n[Instruction in the imperative. Show the exact command\u002Faction.]\n\n[The expected, visible result — \"You should see…\" — so the reader can confirm they're on track.]\n\n## Step 2: [Next concrete action]\n\n...\n\n## What you built\n\n[Brief recap of the end state, so the learner sees what they accomplished. Link onward: to a\nhow-to guide for the next real task, or to reference\u002Fexplanation for anything glossed over\nalong the way.]\n```\n\n### How-to guide template\n\n```markdown\n---\ntitle: TODO(fill) specific, real-world goal, matching the H1 below\ndescription: TODO(fill) one line, used verbatim as the llms.txt description\n# source: repo-root-relative globs; changes to these files make \u002Fsdlc:docs sync draft a refresh of this page. Omit to opt out.\nsource:\n  - TODO(fill) repo-root-relative glob, e.g. plugins\u002Fsdlc\u002Fcommands\u002Floop.md\n# related-adrs: repo-root-relative docs\u002Fadr\u002FNNNN-*.md paths this page depends on; audit's\n# ADR-drift flag reads it. Leave [] unless the page genuinely references an accepted ADR.\nrelated-adrs: []\n---\n\n# How to [specific, real-world goal]\n\n[One sentence naming the problem\u002Fgoal this guide solves — not what tool it uses.]\n\n## Prerequisites\n\n[What the reader needs already in place\u002Fknown — assume competence, don't re-teach basics.]\n\n## Steps\n\n1. [Action, in the imperative, addressed to the goal — branch or note alternatives inline only\n   where the real-world problem itself branches.]\n2. [Next action.]\n   ...\n\n[Optional: a troubleshooting\u002Fverification note if the real-world task commonly needs one.]\n\nSee [reference page] for the full list of options — this guide only covers what's needed to\nreach this specific goal.\n```\n\n### Reference template\n\n````markdown\n---\ntitle: TODO(fill) exact name of the API\u002FCLI\u002Fconfig surface, matching the H1 below\ndescription: TODO(fill) one line, used verbatim as the llms.txt description\n# related-adrs: repo-root-relative docs\u002Fadr\u002FNNNN-*.md paths this page depends on; audit's\n# ADR-drift flag reads it. Leave [] unless the page genuinely references an accepted ADR.\nrelated-adrs: []\n---\n\n# [Exact name of the API\u002FCLI\u002Fconfig surface being described]\n\n[One neutral sentence: what this is, no more.]\n\n## [Symbol\u002Fcommand\u002Ffield name]\n\n**Type\u002FSignature:** [...]\n**Default:** [...] (if applicable)\n\n[Neutral, factual description — what it does, not why you'd want it or when you should use it.]\n\n**Example:**\n\n```[language]\n[minimal illustrative usage — illustration only, not a tutorial]\n```\n\n## [Next symbol\u002Fcommand\u002Ffield name]\n\n...\n````\n\nKeep entries structurally identical to each other (same fields, same order) — consistency is what\nmakes reference material fast to scan; a reader shouldn't have to re-learn the shape of each\nentry.\n\n### Explanation template\n\n```markdown\n---\ntitle: TODO(fill) topic, matching the H1 below, e.g. About X or X design\ndescription: TODO(fill) one line, used verbatim as the llms.txt description\n# related-adrs: the docs\u002Fadr\u002FNNNN-*.md paths this page discusses; audit's ADR-drift flag reads it.\n# List the same ADRs the \"Related decisions\" section links, so the machine key and the prose agree.\nrelated-adrs: []\n---\n\n# About [topic] \u003C!-- or: \"[Topic] design\", \"Understanding [topic]\" -->\n\n[Open with the \"why\" question this page answers — explanation exists to answer a real or implied\n\"can you tell me about…?\"]\n\n[Discursive body: context, history, the forces and trade-offs at play, alternatives considered,\nand — unlike every other quadrant — reasoned opinion where it's warranted (\"X is preferable here\nbecause…\"). Draw connections to other parts of the system; this is the one quadrant where doing\nso is the whole point.]\n\n## Related decisions\n\n[Where a documented architectural decision underlies this topic, link the source ADR(s) — e.g.\n`docs\u002Fadr\u002F0007-use-postgresql-as-primary-datastore.md` — rather than restating the ADR's Context\u002F\nAlternatives\u002FConsequences here. If no ADR exists for a decision this page discusses, that's fine —\nnot every explained decision needs a formal ADR — but check `docs\u002Fadr\u002Findex.md` first if the repo\nhas one, before writing \"why\" content that a kept-current ADR might already own. Skip this check\nentirely in a repo with no `docs\u002Fadr\u002F` directory at all.]\n```\n\n## Voice, Craft, and Output Format (parameterized — never hardcode)\n\nThis skill is deliberately generic: it says nothing here about what THIS repo's docs should sound\nlike or what markup they should be written in, because that varies per repo and per doc-site\nplatform. Resolve those two things at the START of any drafting or review task, from these sources\nin order:\n\n1. **`.claude\u002Fproject\u002Fdocs-manifest.md`** (if it exists) — the sdlc `\u002Fsdlc:docs` pipeline's\n   per-repo manifest of voice guidance and target output format (e.g. Mintlify MDX vs. plain\n   Markdown vs. another doc-site's flavor, front-matter schema, any repo-specific terminology or\n   tone rules). This is the primary source once a repo has adopted the docs pipeline.\n2. **`.claude\u002Fproject\u002Fproject-context.md`** — fall back here for anything the docs-manifest\n   doesn't state (or when no docs-manifest exists yet): detected stack\u002Fframework, any existing\n   voice conventions documented for other content (e.g. a marketing\u002Fbrand voice guide the repo\n   already maintains), and the base branch \u002F PR conventions for where a doc change should land.\n3. **Neither exists or is silent on a point** — default to plain, precise Markdown with no\n   platform-specific extensions, and a neutral, direct technical voice (no unexplained jargon,\n   no marketing language, active voice, second person for reader-facing instructional prose).\n   Don't invent a house style; state plainly what you defaulted to so a human reviewer can correct\n   it.\n\nRegardless of which source resolves voice and format, these craft rules apply universally, because\nthey follow from the quadrant model itself rather than from any one repo's taste:\n\n- **Match register to quadrant** — tutorial prose is warm, narrated, first-person-plural\n  (\"we'll…\"); how-to prose is terse and imperative; reference prose is austere and impersonal;\n  explanation prose may be reflective and first-person (\"I\" or \"we\" reasoning through a topic) —\n  don't let one page's register bleed into another's.\n- **Title says what the page is** — a reader (and a search engine) should know which quadrant a\n  page belongs to from its title alone: \"Getting started with X\" reads as a tutorial, \"How to\n  configure X\" as a how-to guide, \"X reference\" as reference, \"About X\" \u002F \"X design\" as\n  explanation. A vague title (\"X\") tells the reader nothing about what kind of page they're\n  opening.\n- **Link across quadrants instead of importing content across them** — every quadrant will\n  legitimately want to point at another (a how-to guide linking to reference for the full flag\n  list, a tutorial linking to explanation for the \"why,\" an explanation page linking to the how-to\n  guide with the actual steps) — that's healthy Diátaxis practice, not drift. Drift is when the\n  _content itself_ (not just a link) crosses the boundary.\n- **No TBDs in published docs** — an unfinished doc is worse than no doc; if a fact is genuinely\n  unknown, say what's known and flag the gap explicitly rather than leaving a placeholder.\n- **No em-dash inside `title:` or `description:` frontmatter** — `\u002Fsdlc:docs`'s `llms.txt` regen\n  (`docs-pipeline-core.md` §8) parses each generated entry positionally as\n  `title — one-line description — relative link`, splitting on a space, an em-dash, and a space. An\n  em-dash inside either field's own value collides with that delimiter and breaks the split. Use a\n  comma, colon, or plain hyphen instead when the title\u002Fdescription itself needs a pause.\n\n## Self-Review Checklist (run before publishing\u002Fcommitting)\n\n- [ ] The page is identifiable as exactly one quadrant from its title and opening paragraph\n- [ ] The page carries `title` + `description` frontmatter (both filled — no unfilled\n      `TODO(fill)` sentinel left), and `related-adrs:` (empty `[]` unless the page genuinely\n      references an accepted ADR); if this is a how-to\u002Fintegration-guide page with `source:`\n      present, its glob(s) are real paths, not the scaffold's `TODO(fill)` example\n- [ ] Neither `title:` nor `description:` contains an em-dash — it collides with the `llms.txt`\n      regen's field delimiter\n- [ ] No anti-pattern from the table above is present anywhere in the page\n- [ ] The page follows its quadrant's structure template (sections present, none borrowed from\n      another quadrant)\n- [ ] Cross-quadrant references are links, not inlined\u002Fduplicated content\n- [ ] If this is an explanation page discussing a decision with an existing ADR, it links to that\n      ADR rather than re-deriving its reasoning\n- [ ] Voice and output format were resolved from docs-manifest → project-context → stated default,\n      in that order — not assumed or hardcoded\n- [ ] No TBDs — any genuine open gap is stated plainly, not left as a placeholder\n\n## Applied to a familiar analogy\n\nDiátaxis's own comparison (cooking) transfers cleanly and is worth keeping in mind when a quadrant\ncall feels ambiguous: a cooking **lesson** teaches you to cook (tutorial); a **recipe** gets you a\nspecific dish without teaching you anything (how-to guide); the **nutrition label** states facts\nwith zero narrative (reference); a **book about the history and science of cooking** helps you\nunderstand cooking more deeply without directly helping you cook tonight's dinner (explanation).\nNone of the four substitutes for another, and mixing them — a recipe that stops to teach knife\nskills, or a nutrition label with marketing copy — makes the result worse at its actual job.\n","# writing-docs — Diátaxis documentation authoring\n\n**Core principle:** a documentation page serves exactly ONE of four distinct reader needs —\nlearning, doing, looking something up, or understanding — and trying to serve two at once makes\nit worse at both. If you find a document explaining theory in the middle of a set of steps, or a\nreference page arguing for why a default was chosen, that's not richness, that's quadrant drift,\nand the fix is to split it, not to smooth it over.\n\n**Announce at start:** \"I'm using the writing-docs skill to author\u002Freview this doc.\"\n\n## Canonical source\n\nThis skill distills [Diátaxis](https:\u002F\u002Fdiataxis.fr\u002F) (Daniele Procida) — read the live site for\nthe full treatment; the four-quadrant model, the compass, and the per-quadrant principles below\nare drawn from it directly, not invented here. When in doubt about an edge case this skill\ndoesn't cover, the canonical source is the tiebreaker.\n\n## When to Use\n\n- Whenever you're about to write or substantially restructure a prose documentation page —\n  a tutorial, a how-to guide, a reference page, or an explanation\u002Fconceptual page — for a public\n  docs site or any repo documentation meant to be read (not a code comment, not an ADR — ADRs\n  have their own `writing-adrs` skill and their own format for a different purpose: a permanent\n  decision log, not reader-facing product\u002Fproject documentation).\n- When the sdlc docs pipeline (`\u002Fsdlc:docs` command + `knowledge-engineer` agent) generates or\n  updates a doc page — in a repo where that pipeline is adopted.\n- When reviewing an existing doc and something feels \"off\" — the compass below is exactly the\n  tool for diagnosing which quadrant a page has drifted out of.\n\n## Why Diátaxis\n\nDiátaxis starts from an observation: documentation readers don't have one kind of need, they have\nfour, and each is genuinely different in what it demands of the writing:\n\n- Someone **learning** a system wants a safe, guided experience with visible results at every\n  step — they need a **tutorial**.\n- Someone already competent, trying to **get something done**, wants directions to a specific\n  goal — they need a **how-to guide**.\n- Someone **working** who needs a fact — a parameter's type, a flag's behaviour, a field's\n  default — wants to look it up fast and trust it completely — they need **reference**.\n- Someone trying to **understand** why something is the way it is wants context, discussion, and\n  connections drawn — they need **explanation**.\n\nThese four needs pull writing in different, often incompatible, directions — a page that's trying\nto teach AND to be quickly-scannable AND to argue for a design choice is failing all three\npurposes at once, because good tutorial prose is _slow and narrated_, good reference prose is\n_austere and fact-only_, and good explanation prose is _discursive and opinionated_ — you cannot\nwrite in all three registers on the same page and have any of them land well. **One document, one\nquadrant, one register.** This is the one-doc-one-quadrant discipline: every page you write should\nbe identifiable, from its first paragraph, as belonging to exactly one of the four.\n\n## The Four Quadrants\n\n| Quadrant | Serves | Oriented toward | Reader is… |\n| --- | --- | --- | --- |\n| **Tutorial** | Learning (study) | Action + skill acquisition | A student, guided step by step |\n| **How-to guide** | Doing (work) | Action + skill application | A competent practitioner with a goal |\n| **Reference** | Looking up | Cognition + skill application | Someone who needs a fact, fast |\n| **Explanation** | Understanding | Cognition + skill acquisition | Someone reflecting, away from the task |\n\n### Tutorial\n\nA lesson, not a demo. The author takes full responsibility for the reader's success: every step\nmust produce a visible, meaningful result, in a fixed, reliable order, with no branching and no\noptional choices — a tutorial is not the place to offer options. Ruthlessly minimize explanation\ninline (link out to it instead); explanation offered mid-lesson breaks the reader's flow and\nteaches the wrong lesson about how to learn. Aim for total reliability: a tutorial that fails\npartway destroys the confidence it exists to build.\n\n### How-to guide\n\nA recipe for someone who already knows the basics and wants a specific, real result. Written from\nthe user's goal, never from the tool's operations (\"how to configure X for zero-downtime\ndeploys,\" not \"how to click the deploy button\"). Action only — no teaching, no theory, no\ncompleteness-for-its-own-sake. It's fine, even expected, for a how-to guide to branch, to skip\nsteps a competent reader doesn't need, and to link out to reference for the full option list\nrather than enumerating every flag inline.\n\n### Reference\n\nDescription, and only description, of the machinery: an API, a CLI, a config schema, a set of\nfields. Austere, neutral, structured to mirror the actual structure of the thing it describes (one\nentry per symbol\u002Fcommand\u002Ffield, consistent shape throughout) — a reader consults it, doesn't read\nit front to back. No narrative, no opinion, no \"you should,\" no \"we chose this because\" — those\nbelong in explanation or a how-to guide; link to them instead of importing them.\n\n### Explanation\n\nDiscussion, at a distance from the task at hand — the only quadrant where opinion, alternatives,\nand \"why\" belong. Explanation is understanding-oriented: it draws connections, gives context and\nhistory, and is honestly allowed to argue a position (\"X is better than Y here because …\") in a\nway none of the other three quadrants may. Where a documented architectural decision already\nexists as an ADR, an explanation page should **link to the source ADR(s)** under `docs\u002Fadr\u002F`\nrather than re-deriving or duplicating the reasoning — the ADR is the durable, single source of\ntruth for _why_; the explanation page's job is to make that reasoning accessible and readable in\ncontext, not to fork it into a second copy that can drift.\n\n## The Compass — choosing the right quadrant\n\nWhen it's unclear which quadrant a piece of content belongs to, ask two questions rather than\ntrusting a first instinct (per Diátaxis's own compass — a genuine decision tool, not a mnemonic):\n\n1. Does this content inform **action** (doing\u002Fpractical steps) or **cognition** (thinking\u002Ffacts)?\n2. Does it serve **acquisition** (the reader is studying, building a skill) or **application** (the\n   reader already has the skill and is using it)?\n\n| Informs… | Serves… | → Quadrant |\n| --- | --- | --- |\n| Action | Acquisition | Tutorial |\n| Action | Application | How-to guide |\n| Cognition | Application | Reference |\n| Cognition | Acquisition | Explanation |\n\nApply the compass at the level of a whole page when deciding where new content belongs, and at\nthe level of a paragraph or sentence when a page feels like it's drifting — a single sentence of\nexplanation dropped into the middle of a how-to guide's steps is exactly the kind of drift the\ncompass catches that a first read-through can miss.\n\n## Anti-Patterns\n\nEvery one of these is the same underlying failure — a document doing the job of a different\nquadrant — expressed four different ways. Catch these before publishing:\n\n| Anti-pattern | Why it fails | Fix |\n| --- | --- | --- |\n| **Tutorial drifting into reference** — the lesson pauses to enumerate every option, flag, or edge case at the step where one is first used | Breaks the guided-lesson flow; the learner didn't ask for completeness, they asked to be shown one path | Use the one path the tutorial needs; link to the reference page for the full option list |\n| **How-to guide explaining theory** — steps are interrupted by \"this works because…\" or a design-rationale digression | Distracts from the action the competent reader came to perform; if they wanted why, they'd be reading explanation | State the action plainly; link out to an explanation page for the \"why,\" don't inline it |\n| **Reference containing narrative or opinion** — a field's doc says \"you should probably set this to…\" or defends why a default was chosen | Undermines the neutrality reference exists to provide — a reader consulting reference wants facts, not a case being made | Strip to neutral fact (\"Default: `false`.\"); move any judgement or rationale to a how-to guide or explanation |\n| **Explanation giving step-by-step instructions** — a conceptual\u002Fbackground page turns into a numbered procedure partway through | Conflates two registers a reader can't hold at once — reflective reading and procedural following require different modes | Keep explanation discursive; link to the how-to guide or tutorial that has the actual steps |\n\n## Per-Quadrant Structure Templates\n\nUse the quadrant's template as a starting skeleton, not a rigid form — omit a section that\ngenuinely doesn't apply, but don't add sections that belong to a different quadrant.\n\n### Tutorial template\n\n```markdown\n---\ntitle: TODO(fill) learning-oriented title, matching the H1 below\ndescription: TODO(fill) one line, used verbatim as the llms.txt description\n# related-adrs: repo-root-relative docs\u002Fadr\u002FNNNN-*.md paths this page depends on; audit's\n# ADR-drift flag reads it. Leave [] unless the page genuinely references an accepted ADR.\nrelated-adrs: []\n---\n\n# [Learning-oriented title, e.g. \"Getting started with X\"]\n\n[One or two sentences: what the reader will build\u002Fachieve, stated plainly — not \"in this\ntutorial you will learn,\" just what they'll do. Sets expectations before the first step.]\n\n## Prerequisites\n\n[Concrete, minimal — what must already be true\u002Finstalled before starting.]\n\n## Step 1: [Concrete first action]\n\n[Instruction in the imperative. Show the exact command\u002Faction.]\n\n[The expected, visible result — \"You should see…\" — so the reader can confirm they're on track.]\n\n## Step 2: [Next concrete action]\n\n...\n\n## What you built\n\n[Brief recap of the end state, so the learner sees what they accomplished. Link onward: to a\nhow-to guide for the next real task, or to reference\u002Fexplanation for anything glossed over\nalong the way.]\n```\n\n### How-to guide template\n\n```markdown\n---\ntitle: TODO(fill) specific, real-world goal, matching the H1 below\ndescription: TODO(fill) one line, used verbatim as the llms.txt description\n# source: repo-root-relative globs; changes to these files make \u002Fsdlc:docs sync draft a refresh of this page. Omit to opt out.\nsource:\n  - TODO(fill) repo-root-relative glob, e.g. plugins\u002Fsdlc\u002Fcommands\u002Floop.md\n# related-adrs: repo-root-relative docs\u002Fadr\u002FNNNN-*.md paths this page depends on; audit's\n# ADR-drift flag reads it. Leave [] unless the page genuinely references an accepted ADR.\nrelated-adrs: []\n---\n\n# How to [specific, real-world goal]\n\n[One sentence naming the problem\u002Fgoal this guide solves — not what tool it uses.]\n\n## Prerequisites\n\n[What the reader needs already in place\u002Fknown — assume competence, don't re-teach basics.]\n\n## Steps\n\n1. [Action, in the imperative, addressed to the goal — branch or note alternatives inline only\n   where the real-world problem itself branches.]\n2. [Next action.]\n   ...\n\n[Optional: a troubleshooting\u002Fverification note if the real-world task commonly needs one.]\n\nSee [reference page] for the full list of options — this guide only covers what's needed to\nreach this specific goal.\n```\n\n### Reference template\n\n````markdown\n---\ntitle: TODO(fill) exact name of the API\u002FCLI\u002Fconfig surface, matching the H1 below\ndescription: TODO(fill) one line, used verbatim as the llms.txt description\n# related-adrs: repo-root-relative docs\u002Fadr\u002FNNNN-*.md paths this page depends on; audit's\n# ADR-drift flag reads it. Leave [] unless the page genuinely references an accepted ADR.\nrelated-adrs: []\n---\n\n# [Exact name of the API\u002FCLI\u002Fconfig surface being described]\n\n[One neutral sentence: what this is, no more.]\n\n## [Symbol\u002Fcommand\u002Ffield name]\n\n**Type\u002FSignature:** [...]\n**Default:** [...] (if applicable)\n\n[Neutral, factual description — what it does, not why you'd want it or when you should use it.]\n\n**Example:**\n\n```[language]\n[minimal illustrative usage — illustration only, not a tutorial]\n```\n\n## [Next symbol\u002Fcommand\u002Ffield name]\n\n...\n````\n\nKeep entries structurally identical to each other (same fields, same order) — consistency is what\nmakes reference material fast to scan; a reader shouldn't have to re-learn the shape of each\nentry.\n\n### Explanation template\n\n```markdown\n---\ntitle: TODO(fill) topic, matching the H1 below, e.g. About X or X design\ndescription: TODO(fill) one line, used verbatim as the llms.txt description\n# related-adrs: the docs\u002Fadr\u002FNNNN-*.md paths this page discusses; audit's ADR-drift flag reads it.\n# List the same ADRs the \"Related decisions\" section links, so the machine key and the prose agree.\nrelated-adrs: []\n---\n\n# About [topic] \u003C!-- or: \"[Topic] design\", \"Understanding [topic]\" -->\n\n[Open with the \"why\" question this page answers — explanation exists to answer a real or implied\n\"can you tell me about…?\"]\n\n[Discursive body: context, history, the forces and trade-offs at play, alternatives considered,\nand — unlike every other quadrant — reasoned opinion where it's warranted (\"X is preferable here\nbecause…\"). Draw connections to other parts of the system; this is the one quadrant where doing\nso is the whole point.]\n\n## Related decisions\n\n[Where a documented architectural decision underlies this topic, link the source ADR(s) — e.g.\n`docs\u002Fadr\u002F0007-use-postgresql-as-primary-datastore.md` — rather than restating the ADR's Context\u002F\nAlternatives\u002FConsequences here. If no ADR exists for a decision this page discusses, that's fine —\nnot every explained decision needs a formal ADR — but check `docs\u002Fadr\u002Findex.md` first if the repo\nhas one, before writing \"why\" content that a kept-current ADR might already own. Skip this check\nentirely in a repo with no `docs\u002Fadr\u002F` directory at all.]\n```\n\n## Voice, Craft, and Output Format (parameterized — never hardcode)\n\nThis skill is deliberately generic: it says nothing here about what THIS repo's docs should sound\nlike or what markup they should be written in, because that varies per repo and per doc-site\nplatform. Resolve those two things at the START of any drafting or review task, from these sources\nin order:\n\n1. **`.claude\u002Fproject\u002Fdocs-manifest.md`** (if it exists) — the sdlc `\u002Fsdlc:docs` pipeline's\n   per-repo manifest of voice guidance and target output format (e.g. Mintlify MDX vs. plain\n   Markdown vs. another doc-site's flavor, front-matter schema, any repo-specific terminology or\n   tone rules). This is the primary source once a repo has adopted the docs pipeline.\n2. **`.claude\u002Fproject\u002Fproject-context.md`** — fall back here for anything the docs-manifest\n   doesn't state (or when no docs-manifest exists yet): detected stack\u002Fframework, any existing\n   voice conventions documented for other content (e.g. a marketing\u002Fbrand voice guide the repo\n   already maintains), and the base branch \u002F PR conventions for where a doc change should land.\n3. **Neither exists or is silent on a point** — default to plain, precise Markdown with no\n   platform-specific extensions, and a neutral, direct technical voice (no unexplained jargon,\n   no marketing language, active voice, second person for reader-facing instructional prose).\n   Don't invent a house style; state plainly what you defaulted to so a human reviewer can correct\n   it.\n\nRegardless of which source resolves voice and format, these craft rules apply universally, because\nthey follow from the quadrant model itself rather than from any one repo's taste:\n\n- **Match register to quadrant** — tutorial prose is warm, narrated, first-person-plural\n  (\"we'll…\"); how-to prose is terse and imperative; reference prose is austere and impersonal;\n  explanation prose may be reflective and first-person (\"I\" or \"we\" reasoning through a topic) —\n  don't let one page's register bleed into another's.\n- **Title says what the page is** — a reader (and a search engine) should know which quadrant a\n  page belongs to from its title alone: \"Getting started with X\" reads as a tutorial, \"How to\n  configure X\" as a how-to guide, \"X reference\" as reference, \"About X\" \u002F \"X design\" as\n  explanation. A vague title (\"X\") tells the reader nothing about what kind of page they're\n  opening.\n- **Link across quadrants instead of importing content across them** — every quadrant will\n  legitimately want to point at another (a how-to guide linking to reference for the full flag\n  list, a tutorial linking to explanation for the \"why,\" an explanation page linking to the how-to\n  guide with the actual steps) — that's healthy Diátaxis practice, not drift. Drift is when the\n  _content itself_ (not just a link) crosses the boundary.\n- **No TBDs in published docs** — an unfinished doc is worse than no doc; if a fact is genuinely\n  unknown, say what's known and flag the gap explicitly rather than leaving a placeholder.\n- **No em-dash inside `title:` or `description:` frontmatter** — `\u002Fsdlc:docs`'s `llms.txt` regen\n  (`docs-pipeline-core.md` §8) parses each generated entry positionally as\n  `title — one-line description — relative link`, splitting on a space, an em-dash, and a space. An\n  em-dash inside either field's own value collides with that delimiter and breaks the split. Use a\n  comma, colon, or plain hyphen instead when the title\u002Fdescription itself needs a pause.\n\n## Self-Review Checklist (run before publishing\u002Fcommitting)\n\n- [ ] The page is identifiable as exactly one quadrant from its title and opening paragraph\n- [ ] The page carries `title` + `description` frontmatter (both filled — no unfilled\n      `TODO(fill)` sentinel left), and `related-adrs:` (empty `[]` unless the page genuinely\n      references an accepted ADR); if this is a how-to\u002Fintegration-guide page with `source:`\n      present, its glob(s) are real paths, not the scaffold's `TODO(fill)` example\n- [ ] Neither `title:` nor `description:` contains an em-dash — it collides with the `llms.txt`\n      regen's field delimiter\n- [ ] No anti-pattern from the table above is present anywhere in the page\n- [ ] The page follows its quadrant's structure template (sections present, none borrowed from\n      another quadrant)\n- [ ] Cross-quadrant references are links, not inlined\u002Fduplicated content\n- [ ] If this is an explanation page discussing a decision with an existing ADR, it links to that\n      ADR rather than re-deriving its reasoning\n- [ ] Voice and output format were resolved from docs-manifest → project-context → stated default,\n      in that order — not assumed or hardcoded\n- [ ] No TBDs — any genuine open gap is stated plainly, not left as a placeholder\n\n## Applied to a familiar analogy\n\nDiátaxis's own comparison (cooking) transfers cleanly and is worth keeping in mind when a quadrant\ncall feels ambiguous: a cooking **lesson** teaches you to cook (tutorial); a **recipe** gets you a\nspecific dish without teaching you anything (how-to guide); the **nutrition label** states facts\nwith zero narrative (reference); a **book about the history and science of cooking** helps you\nunderstand cooking more deeply without directly helping you cook tonight's dinner (explanation).\nNone of the four substitutes for another, and mixing them — a recipe that stops to teach knife\nskills, or a nutrition label with marketing copy — makes the result worse at its actual job.\n",{"name":5,"description":7},"main","7d4ebd573a4218d5e92eced411b259f34e9203fe","plugins\u002Fsdlc\u002Fskills\u002Fwriting-docs",0,"https:\u002F\u002Fgithub.com\u002FwhimzyLive\u002Fnightshift-ai","https:\u002F\u002Fwithnightshift.com\u002F","https:\u002F\u002Fgithub.com\u002FwhimzyLive","Creator of @typedorm","2026-11-14 22:45:42",{"source":8,"skillName":5,"commands":34,"prompt":44,"zipAvailable":45},[35,38,41],{"tool":36,"command":37},"npx","npx skills add whimzyLive\u002Fnightshift-ai --skill writing-docs",{"tool":39,"command":40},"bunx","bunx skills add whimzyLive\u002Fnightshift-ai --skill writing-docs",{"tool":42,"command":43},"pnpm","pnpm dlx skills add whimzyLive\u002Fnightshift-ai --skill writing-docs","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002FwhimzyLive\u002Fnightshift-ai\u002Fblob\u002Fmain\u002Fplugins\u002Fsdlc\u002Fskills\u002Fwriting-docs\u002FSKILL.md",true,[],[48,56,63,70,77,84],{"skillNo":49,"name":50,"nameZh":6,"description":51,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":52,"categories":53,"keywords":54,"publishedAt":55},"01M7BCEWYHDS1FWAJ6G4CD9P54","designing-in-patterns","Use when designing, planning or auditing UI against a component library — naming surfaces with the repo's pattern vocabulary, deciding reuse versus extend versus new, exploring compositions, or writing the reuse table (component-plan.md, a spec's `## Reuse`, a UI audit). Carries the design method; the repo's own vocabulary, bundle and board rules come from project-context and the designer override.","https:\u002F\u002Fgithub.com\u002FwhimzyLive\u002Fnightshift-ai\u002Fblob\u002Fmain\u002Fplugins\u002Fsdlc\u002Fskills\u002Fdesigning-in-patterns\u002FSKILL.md",[],[],"2026-11-15 14:19:17",{"skillNo":57,"name":58,"nameZh":6,"description":59,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":60,"categories":61,"keywords":62,"publishedAt":19},"01M75MVN6GACAC87SV9RBPBMKH","typeorm","Use when defining TypeORM entities, writing migrations, or building repository\u002Fquery-builder code in TypeScript. Covers entity and relation decorators, the Data Mapper pattern, migrations, the query builder, transactions, and multi-database configuration.","https:\u002F\u002Fgithub.com\u002FwhimzyLive\u002Fnightshift-ai\u002Fblob\u002Fmain\u002Fskills\u002Ftypeorm\u002FSKILL.md",[],[],{"skillNo":64,"name":65,"nameZh":6,"description":66,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":67,"categories":68,"keywords":69,"publishedAt":19},"01M75MTEZV8SAZNS20YDSB7KG2","hono-api","Use when building or extending REST APIs with Hono + @hono\u002Fzod-openapi. Covers schema-first route declaration with createRoute, feature-grouped composable routers, a class-based service layer behind interfaces, the strategy pattern for multi-event webhooks, typed request validation, and auto-generated OpenAPI docs.","https:\u002F\u002Fgithub.com\u002FwhimzyLive\u002Fnightshift-ai\u002Fblob\u002Fmain\u002Fskills\u002Fhono-api\u002FSKILL.md",[],[],{"skillNo":71,"name":72,"nameZh":6,"description":73,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":74,"categories":75,"keywords":76,"publishedAt":19},"01M75MTB91SB6HPB3ZRT20F950","electrodb","Use when defining DynamoDB entities, modeling indexes, or writing queries\u002Fmutations with the ElectroDB ORM. Covers entity schema, access patterns, CRUD operations, update expressions, and single-table design patterns.","https:\u002F\u002Fgithub.com\u002FwhimzyLive\u002Fnightshift-ai\u002Fblob\u002Fmain\u002Fskills\u002Felectrodb\u002FSKILL.md",[],[],{"skillNo":78,"name":79,"nameZh":6,"description":80,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":81,"categories":82,"keywords":83,"publishedAt":19},"01M75MT7KT9A3XYX38TX5MY6MA","atomic-design","Use when structuring or decomposing any frontend UI into reusable components, regardless of framework. Applies Brad Frost's atomic design methodology — atoms, molecules, organisms, templates, and pages — to guide consistent component hierarchy, naming, and composition decisions.","https:\u002F\u002Fgithub.com\u002FwhimzyLive\u002Fnightshift-ai\u002Fblob\u002Fmain\u002Fskills\u002Fatomic-design\u002FSKILL.md",[],[],{"skillNo":85,"name":86,"nameZh":6,"description":87,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":88,"categories":89,"keywords":90,"publishedAt":19},"01M75MSM0Z0AHA6YS4Q5E6R65T","writing-adrs","Use when authoring an Architecture Decision Record (ADR) — a short document that captures one significant, hard-to-reverse technical or architectural decision, its context, and its consequences. Triggered by the sdlc ADR pipeline (the knowledge-engineer agent behind \u002Fsdlc:docs seed adr and \u002Fsdlc:docs distill) when generating an ADR from a story, and by anyone hand-authoring an ADR under docs\u002Fadr\u002F today. Covers why ADRs are kept short and inverted-pyramid, the required sections (Title, Status, Decision, Context, Alternatives Considered, Consequences), the proposed→accepted→superseded (or →rejected) status lifecycle and the never-edit-only-supersede immutability rule, the NNNN-decision-slug.md filename convention, and the ADR frontmatter fields (status, agents, source-stories) the pipeline reads to route a generated ADR into docs\u002Fadr\u002Findex.md.","https:\u002F\u002Fgithub.com\u002FwhimzyLive\u002Fnightshift-ai\u002Fblob\u002Fmain\u002Fplugins\u002Fsdlc\u002Fskills\u002Fwriting-adrs\u002FSKILL.md",[],[]]