Scribekit Docs

---
name: scribekit-docs
description: Write, rewrite, reorganize, or deep-verify documentation for the current project's docs site (MDX), sourced entirely from the project's own code so every documented fact, option, default, and code sample is true. Use when the user wants to create/write/draft/document a new docs/reference/guide page; rewrite/audit/fact-check/update an existing one against the current code; reorganize/restructure/reshuffle the docs as a whole - fix the sidebar, the nav, the tabs, the groups, the ordering, or the information architecture when the structure is a mess, pages sit in the wrong section, or the reading order makes no sense; or deep-verify the WHOLE corpus before a release - verify/validate that every page is still true and up to date against the code and that the docs are ready to ship/release/deploy, fanning out one subagent per page and reporting every issue for the user to pick from (add --scan to only report, without changing anything). Each page's on-brand hero is generated by the companion /scribekit-hero skill (docs-hero); the write flow calls it automatically. Portable - it learns and adapts to whatever project it runs in. Not for a marketing or blog article - that is /scribekit-blog.
user-invokable: true
argument-hint: "[write|rewrite|reorganize|deep-verify] [topic | slug-or-path] [--scan]"
---

# scribekit-docs

A portable skill - **one skill, four jobs**: write a documentation page, rewrite (or just audit) a page,
reorganize the corpus's structure, and deep-verify the whole corpus before a release, for the docs site of
whatever project it is dropped into.
**Nothing about any project is baked
in.** It **learns the current project first** (Step 0), then writes and rewrites to match it. The one
way it differs from the [/scribekit-blog](../scribekit-blog/SKILL.md) blog writer is decisive: **docs are
project-dedicated, so the primary source is this project's own code, not the open web** - every fact,
option, default, and code sample is traced to real source, never recalled from memory. Each page's
**hero image** is produced by the companion **[/scribekit-hero](../scribekit-hero/SKILL.md)** skill
(`docs-hero`) - the `write` flow calls it automatically. This file is the router.

## Step 0 - Learn this project (every mode starts here)

Before anything else, discover the project so voice, structure, and frontmatter are *this project's*,
not generic. Gather and keep as working notes for the run:

- **Identity, voice, routes** - read `CLAUDE.md` / `AGENTS.md` / `README`, skim the landing page, and
  open the 1-2 strongest existing docs pages: that voice and formatting is your calibration target.
  Note the project's own conventions (its `CLAUDE.md`): indentation, punctuation (some projects ban
  em-dashes - this one does), British vs US spelling.
- **Find the `Docs` wiring** - grep for `new Docs(` and pick the `_docs.ts` colocated with the route
  files (a project mirrors a `_blog.ts` = `export const docs = new Docs({...})`); **ignore matches in
  `dist/`, `node_modules/`, and tests**. From it read `contentDir`, `basePath` (default `/docs`),
  `extension` (default `.mdx`), `defaultLocale`, `prefixDefaultLocale`, `trailingSlash` (default
  `true`, which sets the internal-link form - see [docs-style.md](./docs-style.md)), `locales`, and
  the `tabs` / `groups` display config. Two resolution rules a naive read gets wrong:
  - **`contentDir` is resolved against the app root that runs `Docs`** (`process.cwd()` at runtime =
    the nearest `package.json` / Next project root), **not** the repo root and **not** the `_docs.ts`
    file's own directory - so a relative `./docs` in `app/.../_docs.ts` means `<app-root>/docs`. After
    resolving, **verify the directory exists and holds `<slug>/` folders** before concluding the corpus
    is empty; if not, re-resolve against the app's `package.json` dir.
  - **The docs site is multi-language iff `locales` is a non-empty array.** The scalar `locale`
    (BCP-47, only for date formatting) is **not** a language list - never derive translations from it,
    and never carry a sibling blog's `locales` onto the docs surface.
  **If no `Docs` instance exists**, docs are not set up in this project yet: **ask the user** for the
  intended content dir, `basePath`, and locales (or confirm the conventional `./docs` + `/docs` +
  single-language) before proceeding - do not guess. `Docs` is exported from the package root
  (`import { Docs } from "<the package name>"`).
- **Map the `docs/` corpus** (how much depends on the mode: **write** reconstructs the *whole* corpus
  for its gap analysis - write.md 1b; **rewrite** needs only the target page and its tab/group
  **neighbours**; **reorganize** and **deep-verify** need the whole corpus **in every locale** - they are
  the modes that read every language file, because the nav is rebuilt per language and the languages can
  disagree, in slot (reorganize) and in content (deep-verify)).
  Read each `<contentDir>/<slug>/` page's YAML front-matter (`title`, `tab`, `group`,
  `order`, `icon`, `keywords`, `hidden`). **Assume you cannot call `getNavTree`/`getAllDocs`/`getDoc`** -
  `Docs` is `server-only` and the target may wire no instance; **reconstruct** what they would return
  by reproducing scribekit's `Docs` reader sort rules (the single source for these rules). Two escape
  hatches exist, and both are worth taking when they work, because a reconstruction is a simulation and
  these are ground truth:
  - the pure **nav builder** underneath the class (`buildNavTree`/`flattenNav`) is fs-free and callable if
    you import the module directly rather than the package barrel, so you can **check** your
    reconstruction against it: [reorganize.md](./reorganize.md) step 2;
  - **`server-only` only blocks the barrel under the default export condition.** Under the
    **`react-server`** condition - the one the users' framework actually resolves - the whole `Docs` class
    runs: `node --conditions=react-server`, construct it with the project's real config, and you get the
    real nav, prev/next, breadcrumb, TOC anchors, hreflang and sitemap.
    [deep-verify.md](./deep-verify.md) Phase 0 uses this.
  Whichever you end up with, **say which** - never present a reconstruction as executed truth. Bucket by
  `tab` (unset = one implicit `""` tab), then `group` (unset = ungrouped bucket); within a group sort
  by `order` ascending, unset last, then by **title** (`localeCompare`); tabs and groups themselves
  order by the `Docs` `tabs`/`groups` config first, then by their pages' minimum `order`, then
  first-seen; `hidden` pages are real routable folders but are excluded from the nav tree, breadcrumb,
  prev/next, and index.
- **The real product/source code is the source of truth** - **every documented fact, sample, option,
  and default traces to a real `file:line`**, never invented, never from memory. **write** enumerates
  the *whole* public surface for its gap analysis (write.md 1a); **rewrite** reads on-demand only the
  symbols the target page actually cites; **deep-verify** needs **both** - the whole surface (to find what
  no page documents) *and* every symbol every page cites (to find what no longer exists), which is why it
  computes the surface once up front and hands it to its agents. Where a symbol's **JSDoc disagrees with
  its executed behaviour, the behaviour wins** - comments drift, and a page that trusted a stale comment
  is wrong. Know the shape: package exports and their source barrels,
  exported class **methods and public `readonly` fields**, `*Config` options + their constructor
  defaults, routes, components, CLI flags (only if `package.json` has a `bin`).

If the project genuinely has none of this (a near-empty repo), **ask the user** for the essentials
rather than guessing.

## Pick the mode

Two questions settle it - **one page or the whole corpus**, and **the content or the structure**:

| | one page | the whole corpus |
| --- | --- | --- |
| **content** (the bodies) | **rewrite** | **deep-verify** |
| **structure** (front-matter, the nav) | **rewrite** (its slot check) | **reorganize** |

...and **write** is the one that adds a page that does not exist yet.

- **write** - a new page, or the argument is a topic/idea, or the verb is create / write / draft /
  document. -> **[write.md](./write.md)** (writes the page **and**, by default, its hero image; on a
  multi-language docs site, also its translation for **every** configured locale).
- **rewrite** - audit an existing page **against the current code** and apply the fixes (rewrite /
  overhaul / redo / audit / fact-check / update / correct), or the argument resolves to an existing
  page file/slug. Add **`--scan`** to only audit and report, changing nothing.
  -> **[rewrite.md](./rewrite.md)**.
- **reorganize** - redesign the **whole corpus's structure**: which tab/group each page belongs to, the
  order pages read in, and how the sections themselves are ordered and labelled (reorganize /
  restructure / reshuffle / "fix the sidebar" / "the nav is a mess" / "these pages are in the wrong
  section"). It is **gated** (plan -> approval -> apply) and **never
  renames a slug** (no URL changes; badly-named slugs are reported at the end). Add **`--scan`** to only
  plan and report. -> **[reorganize.md](./reorganize.md)**.
- **deep-verify** - prove the **whole corpus's content** is still true against the code and **ready to
  deploy** (verify / validate / "are the docs still up to date?" / "is this ready to ship / release?" /
  a pre-release docs check). Fans out **one subagent per page** to re-verify every page against source in
  parallel, then computes the defects **no single page can reveal**: undocumented API surface, pages that
  contradict each other, broken links and anchors, translations drifted from their original, samples that
  no longer compile, and docs that are true against `src/` but **wrong against the published package**.
  Report-first: it lists every finding, numbered, and **applies only the ones you pick** (you can attach a
  note to each). Add **`--scan`** to report and stop without offering the gate. **The expensive one** -
  it spawns an agent per page. -> **[deep-verify.md](./deep-verify.md)**.

**Hero images** are a separate skill: **[/scribekit-hero](../scribekit-hero/SKILL.md)** (`docs-hero` to
create/update a page's hero, `regenerate-docs-heroes`, `tune-gradients docs`). `write` calls it for
you; invoke it directly for standalone hero work.

Edge cases:
- **`rewrite` with no target** -> list the pages in the content dir and ask which.
- **"rewrite / overhaul / redo / update" an existing page** -> **rewrite** (it audits, then applies the
  fixes, up to a substantial rewrite) - not **write**, which only creates new pages.
- **One page vs the whole structure.** "This page is in the wrong group" -> **rewrite** that page. "The
  docs are a mess / the sidebar makes no sense / reorganize the docs" -> **reorganize**, which is about
  the corpus, not any one page. If a `reorganize` request names a single slug, it is a `rewrite`.
- **One page vs the whole corpus's content.** "Is this page still correct?" -> **rewrite --scan**. "Are the
  docs still true / still up to date / ready to ship?" -> **deep-verify**, which is about the corpus. Same
  rule as above: **if the request names a single slug, it is a `rewrite`**, however deep the verb sounds.
- **`deep-verify` vs `reorganize --scan`.** Both read the whole corpus, and they do not overlap:
  `reorganize` reads the **front-matter** and judges the **nav**; `deep-verify` reads the **bodies** and
  judges the **content**. "The sidebar is a mess" -> reorganize. "The content is out of date" -> deep-verify.
  (deep-verify reports nav defects it happens to see, but never fixes them - it hands them to reorganize.)
- **Ambiguous** (a bare slug that matches a page but the verb suggests a fresh one) -> ask one
  clarifying question first. **Never** run two modes in one invocation.

## Read the shared standards first (all modes)

These are the spec every mode enforces - read them after Step 0, not as background:

- **[../scribekit-blog/house-style.md](../scribekit-blog/house-style.md)** - the universal voice craft, MDX
  formatting, and banned-AI-slop lists. **Reuse its voice-craft, anti-slop vocabulary, and MDX rules;
  OVERRIDE its blog-specific frontmatter contract, pull-quote, and one-CTA/sales-close rules** - the
  docs deltas are in `docs-style.md` below.
- **[../scribekit-blog/research-protocol.md](../scribekit-blog/research-protocol.md)** - how to research and cite.
  **INVERTED for docs**: the primary source is **this project's source code, read directly**; use
  `WebSearch`/`WebFetch` only for a genuinely external fact (a published standard or spec) and cite it.
  Ignore its SERP / keyword / GEO instructions - docs have no search-intent axis.
- **[docs-style.md](./docs-style.md)** - the docs craft: pick the Diátaxis type (one type per page),
  the per-type page shapes, the deltas from house-style, heading + code-sample discipline, the
  **`DocMeta` frontmatter contract and its load-bearing YAML types**, and the light metadata check that
  replaces the blog's 100-point rubric.

**Locating the shared `scribekit-blog` files.** `house-style.md` and `research-protocol.md` live in the
sibling **`scribekit-blog`** skill, not here. Resolve them at the first path that exists:
`<this-skill-dir>/../scribekit-blog/<file>`; `.claude/skills/scribekit-blog/<file>` (from the project root or
`$HOME`); `node_modules/<package-name>/skills/scribekit-blog/<file>`. **If none exists, STOP** and tell the
user to install the `scribekit-blog` skill alongside `scribekit-docs` - do not proceed without the shared
standards.

## Non-negotiables (all modes)

- **Never fabricate an API detail.** Every documented export, option name, default value, method
  signature, route, and the **package import string** is read from source at authoring time and carries
  a `file:line` trace - never from memory, never from this skill's examples. The import name is
  `package.json`'s `name` field (read it). `DocMeta` has **no** `author`/`categories`/`tags` fields;
  never add them. The SEO methods (`docMetadata`/`docJsonLd`/...) auto-emit schema and throw without
  `siteUrl`+`brandName` - never hand-write JSON-LD. Any genuinely-external cited fact still obeys the
  research protocol (no invented stat, quote, or date).
- **Never start a dev server** (ask the user to run it). **Never create git branches.** Keep changes
  scoped to the page + its hero asset - **plus**, only when you introduce a brand-new `tab`/`group`,
  the `tabs`/`groups` array in the project's `_docs.ts` (so the new section is ordered/labelled, not
  sorted last under its raw id). Two exceptions, both **gated on approval**: **`reorganize`** edits the
  front-matter of *every* page (all locales) and the `_docs.ts` `tabs`/`groups` arrays - but nothing else;
  **`deep-verify`** edits the **bodies** of the pages whose findings the user approved - and nothing the
  user did not pick.
- **Never rename a `<slug>/` folder.** The slug is the page's public URL; renaming it breaks every
  inbound link. `reorganize` reports badly-named slugs instead of touching them; a deliberate rename is
  the user's call and needs a `redirects` entry ([reorganize.md](./reorganize.md) step 7).
- **Today's real date** comes from `date +%F`, never a guess. Set `updated:`; add `date:` only if
  sibling pages use it (many docs corpora set `updated` only - match the corpus).
- **Match the project, don't impose a house look.** Voice, structure, routes, and frontmatter all come
  from Step 0 - this skill carries craft, not content (heroes match the project too - see
  /scribekit-hero).