docs

# docs

Write docs a real person wants to read. Short, plain, built around someone trying to do a real thing.

"Document feature X" is not the job. "Help someone do Y with X" is the job.

Work in two phases. First plan the story: who reads this, what they want, and how many pages it should be. Then write.

The plan is not private. The user must see the readers and must choose the tone before any page is written.

```text
Find docs
  → read neighbors
  → Phase 1: readers + pages
  → PERSONA GATE (show the list, then stop)
  → TONE GATE (ask, then stop)          [when writing pages]
  → load simple-english + i-have-adhd   [when writing pages]
  → Phase 2: write
```

A doc-impact list in a feature plan still runs the persona gate. It does not run the tone gate or load the writing skills until pages are actually written.

## When to run

Docs ship with the code. Run this skill at three moments, not only when asked.

- Someone asks for docs. Write them.
- Planning a feature or change in a repo. Before the plan is done, list which docs are new and which need updating. This doc-impact list is part of the plan, the same as the code changes. Name the reader for each page.
- Finishing an implementation. Write or update those docs before you call the work done. A change to how something behaves that ships no doc change is not finished.

## Required skills for the final pages

`simple-english` and `i-have-adhd` are prerequisites. They apply to the documentation pages, not to this planning chat.

Load both immediately before writing page content. Use the Skill tool if this harness has one. If it does not, Read:

- `.claude/skills/simple-english/SKILL.md`
- `.claude/skills/i-have-adhd/SKILL.md`

Copies also live at `.agents/skills/` (Codex) and `.grok/skills/` (Grok). Keep those three files identical.

If either file is missing, stop and tell the user. Do not write the pages without them.

How they compose:

- This skill owns who the page is for, the page split, problem-then-fix, show-don't-tell, no history leak, forbidden glyphs, and neighbor structure.
- `simple-english` owns the sentences. Use pragmatic mode. Run its self-check before you call a page done.
- `i-have-adhd` owns the shape of the page: next action first, numbered steps, lists capped at 5 (split must vs later, or split the page), no preamble, a visible win at the end.

When `i-have-adhd` is loaded from this skill, apply it to the pages only. Do not switch the rest of the session into ADHD mode. The persistence section of `i-have-adhd` does not apply here.

## Find the docs first

Before writing anything, find where docs live.

1. Look for a docs folder. Check `docs/` first, then `documentation/`, `content/docs/`, `site/`, `website/docs/`.
2. Found nothing? Ask the user where docs should go. Do not guess and do not create a folder on a hunch.
3. Open 2 or 3 existing pages near where the new content belongs. Read them for copy, structure, frontmatter fields, and components. Note the apparent tone as a *candidate* for the tone gate. Do not adopt it yet.
4. Note which components the site already uses (steps, tabs, callouts, cards, accordions, code groups, and so on). Different sites have different ones.
5. Reuse those components to tell the story. If the site has a steps component, use it for walkthroughs. If it has tabs, use them for framework variations. If the site has none, use plain markdown. Never invent a component the site does not have.

### Package manager tabs

Install commands use the site's package-manager tabs. Do not stack `npm` / `pnpm` / `yarn` in one fence.

Core chat install (every framework):

```md
<!-- ::start:tabs variant="package-manager" mode="install" -->

react: @tanstack/ai @tanstack/ai-react @tanstack/ai-openai
vue: @tanstack/ai @tanstack/ai-vue @tanstack/ai-openai
solid: @tanstack/ai @tanstack/ai-solid @tanstack/ai-openai
svelte: @tanstack/ai @tanstack/ai-svelte @tanstack/ai-openai
preact: @tanstack/ai @tanstack/ai-preact @tanstack/ai-openai
angular: @tanstack/ai @tanstack/ai-angular @tanstack/ai-openai
octane: @tanstack/ai @tanstack/ai-octane @tanstack/ai-openai octane
vanilla: @tanstack/ai @tanstack/ai-client @tanstack/ai-openai

<!-- ::end:tabs -->
```

Rules:

- A page that is already one framework lists only that framework's line.
- A package that does not change by framework repeats the same packages on every framework line (`react` through `vanilla` and `octane`).
- Octane's UI package is `@tanstack/ai-octane` plus the `octane` compiler package.
- `mode="install"` is the default add. `mode="dev-install"` is `-D`. `mode="local-install"` is `npx` / `pnpx` / `yarn dlx` / `bunx`. `mode="custom"` is any other command shape (`install -g ...`).
- Repeat a framework line to emit more than one command.
- Do not use this for env files, sandbox `setup:` arrays, or a fence that mixes install with other commands. Split the install out, then leave the rest as a fence.

If there is no page like the one you are about to write, read the closest one you can find and match it.

### What "match the neighbors" covers, and what it does not

Matching neighbors is about **copy, structure, frontmatter, and components**: whether headings are sentence case, how much setup a section gets, which components carry the walkthrough, how code samples are introduced, what the frontmatter fields are.

It is **not** a substitute for the tone gate. Neighbors can suggest a default. They cannot answer for the user.

It is **not** permission to copy a neighbor's bad habits. Everything in [Forbidden](#forbidden) and every rule in this skill still applies to the content you write, no matter what the surrounding pages do. An existing page full of em dashes does not license one more.

So: never reason "the other pages do it, so I will too" about a rule this skill states. If existing pages break a rule and you think the whole set should be brought in line, that is a separate cleanup to raise with the user, not something to settle by quietly matchi