kavo: Skill for Claude Code

Writing Kavo docs

Overview

Kavo's docs are dense and code-first, not tutorial-shaped. A page states the behavior, shows it in one runnable snippet, and links out for depth instead of restating it. REQUIRED SUB-SKILL: run humanizer:humanizer (file mode) on the finished prose before landing it — the voice rules below stop AI tells from being written; humanizer catches what slips through.

When to use

• Adding a new page under docs/ (feature, guide, reference, or an docs/internals/architecture/* note).
• Editing prose in an existing docs/**.md file.
• Not for ADRs themselves — use add-adr for those; this skill is for the docs that describe behavior, not the decision record that justified it.

Voice, in one paragraph

Second person is rare; most pages describe the system ("Kavo stops actually deleting rows"), not the reader. Sentences run long and packed rather than choppy — subordinate clauses over "rule of three" bullet lists. Headers are sentence case, minimal, and often skipped entirely for a short page (soft-delete.md has zero ## headers). No "Overview" or "Introduction" throat-clearing paragraph — the first sentence is the first fact. No promotional adjectives (rich, powerful, seamless, robust) and no "-ing" tacked-on justification clauses. A page can end mid-fact, on a config note or a See [X](path) link — never on an upbeat summary.

Structural conventions

• One code block does the explaining. Show the entity/config/request once, real and copy-pasteable (an actual entity name like Book, not Entity/Foo), then describe what it produces in prose. Don't add a second example that says the same thing a different way.
• Tables for enumerations, not bullet lists: generated routes, config keys, operator mappings. See the routes table in docs/getting-started/quick-start.md.
• Cross-references are inline sentences that name what's on the other end, not "see also" appendices: See [Soft delete, restore & purge](/internals/architecture/11-soft-delete) for the full behavior: unique-index caveats, cascades, and what's deliberately not built. The link text is the page title; the clause after the colon previews what the reader gets there, so they can decide whether to follow it.
• Config-key references point at the anchor, not just the page: `/guides/configuration/settings#softdelete`, matching the heading ## delete would produce.
• Links are root-relative and extensionless (/features/soft-delete, not ./soft-delete.md), matching VitePress cleanUrls.
• A page lives under the section its sidebar entry already has in docs/.vitepress/config.mts — check the sidebar array before inventing a new section for one page.
• Write the MDX dialect, not VitePress's. Docs7 compiles every page as MDX from the same docs/ folder, and docs/.vitepress/docs7-compat.ts rewrites it for VitePress. Use <CodeGroup> with ```bash pnpm tab labels, not ::: code-group; <Danger>/<Warning>/<Tip>/<Note>, with an optional bold first line as the title, not ::: danger; wrap <script setup> and Vue components in a {/* vitepress … */} block. Never start a wrapped prose line with { or <. tests/docs-mdx.spec.ts compiles every page and fails otherwise.