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.

Do not ask the user to approve the plan or the tone. Pick sane defaults, state them in one line each, and keep going. The user can correct you after.

Find docs
  → read neighbors
  → Phase 1: readers + pages
  → state the readers + pages (one line each, no question)
  → state the tone (match neighbors, no question)   [when writing pages]
  → load simple-english + i-have-adhd   [when writing pages]
  → Phase 2: write

A doc-impact list in a feature plan still names the reader for each page. It does not pick a tone 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, the call-first opener, 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? Put the page in the README or the closest existing docs file, and say where you put it. Do not create a new docs 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 their tone. That is the tone you write in.
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):

<!-- ::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 permission to copy a neighbor's bad habits. Everything in 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 matching the violation.

Phase 1: plan the story

Do this before you write a word of content.

1. List who reads this and what each one wants. A person building on a React SPA, a person on a server-rendered app, someone who just wants a quick demo, someone extending the internals. Do not stop at the first reader.
2. Write one user story per reader: "As a X, I want to Y, so I can Z."
3. Turn stories into pages. One journey is one page. Different journeys are different pages. A feature with three real journeys is three pages plus maybe a short overview, not one giant page.
4. Check every reader has a path. A reader with no page is a hole in the plan. Add a page or a route for them.

The page split comes out of this step. Do not skip it.

State the readers

After step 4, put the readers and their pages in your message to the user, one line per reader: the user story and the page. Do not ask a question and do not wait. Continue to Phase 2 in the same turn.

The user reads the list and corrects you if a reader is wrong. A list that only lives in your thinking or a todo does not count. Skip the list only for a tiny copy edit (typo, broken link, code-fence language, factual fix).

Less is more: split, do not cram

Do not force thousands of words into one page. Long pages hide the answer.

When a topic has several angles, give each its own short page and link them. A reader lands on the overview, then clicks into the exact thing they need.

Example. A feature for tool interrupts:

Bad: one page
  interrupts.md   (overview + simple case + many interrupts + custom, all crammed in)

Good: a small set of linked pages
  interrupts/index.md            what it is, when to use it, links out
  interrupts/basic.md            one interrupt, start to finish
  interrupts/multiple.md         several interrupts in a flow
  interrupts/custom.md           build your own

Each page is short and does one thing. The overview stitches them into a story.

Pick the tone

Use the tone of the neighboring pages. State it in one line (how formal, how much setup, second person or not) and continue. Do not ask.

If the user already named a tone in this conversation, use theirs.

Phase 2: write like a human

Do not write page content until you have stated the readers and the tone, and simple-english plus i-have-adhd are loaded.

Legibility is the goal, above everything else.

• Keep it digestible. No walls of text, no huge paragraphs. Break ideas into small pieces. Give the smallest amount of info that does the job.
• Sentences follow simple-english (pragmatic mode). Do not inline a weaker substitute.
• Keep markdown light. Lists are fine. Bold headings on every line are not. Let the words carry the page.
• Prefer plain ASCII and normal keyboard characters over fancy glyphs. Write the way a person types.
• Second person, action first. Start with what the reader has now and what they will have at the end. No "In this guide we will explore..." openings. Just start.
• Shape the page with i-have-adhd: the first line is something the reader can do, multi-step work is numbered, a list longer than 5 is split, the page ends on a visible win.

Open with the call

The first one or two sentences name the call and what the reader gets from it. A reader who lands from search knows in one line whether this page has their answer.

Bad:
  Some tool calls shouldn't run without a human saying yes: moving money,
  deleting data. An interrupt pauses the run for that decision...

Good:
  Set `needsApproval: true` on a tool. The run pauses before the tool runs,
  and continues after a person approves it.

Good:
  `chat()` returns each token while the model writes the reply. `useChat`
  renders those tokens. Call `stop()` to cancel the run.

The opener is the page's only summary. The next line starts the steps or the code. Each idea in the opener is said once on the page, so the paragraph after it adds something new.

When the reader must know a limit to pick the right page, put it in the opener: "chat() with outputSchema returns one typed object. It does not stream or run tools."

The order for a guide is the call, then the steps and code. The code shows how it works, so the prose between snippets stays short.

Show, do not tell

Do not explain in four paragraphs what one sentence and a code block can show. Readers grasp a diff or a snippet faster than prose.

Bad:
  Three paragraphs describing how the config object accepts a
  middleware array, what each slot does, and how ordering works.

Good:
  Add your middleware to the `middleware` array. Order runs top to bottom:

  const app = createApp({
    middleware: [auth, logging],
  })

One good runnable example beats a page of description. Every code sample must run when copied, not need imagination to fill gaps.

List anything that is a list

The moment a sentence covers more than one item, option, store, flag, or step, it becomes a list. Do not chain them into a paragraph with commas and semicolons. A reader scanning a bulleted list finds their item in a second. In a paragraph they have to read the whole thing to learn it does not apply to them.

The tell is a sentence that names two or more things and says something about each. Cut it into one bullet per thing, one or two sentences each.

Bad:
  Each store is independent. Provide only the ones you need. For chat:
  `messages` for the transcript, `runs` for run lifecycle, `interrupts` for
  durable approvals (needs `runs`), `metadata` for namespaced key/value state.
  For generation: `generationRuns` for the run lifecycle, plus `artifacts` and
  `blobs` to keep generated bytes.

Good:
  Each store is independent, so provide only the ones you need.

  For chat:

  - `messages`: the transcript.
  - `runs`: run lifecycle.
  - `interrupts`: durable approvals. Needs `runs`.
  - `metadata`: namespaced key/value state.

  For generation:

  - `generationRuns`: run lifecycle for a generation.
  - `artifacts` + `blobs`: keep the generated bytes.

Which form to reach for:

• Bullets for a set where order does not matter: options, stores, fields, reasons, gotchas.
• Numbered steps for a sequence the reader performs in order.
• A table when every item has the same two or three attributes to compare (name, meaning, when to use).
• A paragraph only for a single idea that genuinely flows as prose. One thought, two or three sentences, no embedded set.

Keep bullets short and parallel: the same grammatical shape, the item in code or bold at the front, the explanation after it. A bullet that grows past two sentences wants to be its own subsection.

If a list grows past five items, split it. Put "do now" first. Put the rest on a later page, or under "later". That is the i-have-adhd cap, not a style preference.

Page shape for a guide

Call, steps, done.

• Open with the call and what the reader gets from it, in one or two sentences.
• Walk through steps they can follow and test as they go, with the code doing the explaining.
• End when they reach the goal. Show what now works. Do not close with a vague "next steps" dump.

Reference pages (props, types, signatures) stay scannable and link back to the guide that shows them in use.

Write for the reader, not the history

Docs describe what exists now. The reader never saw the old design, the earlier name, the draft PR, or the API you replaced along the way. Do not make them read about it.

Never justify the current API by comparing it to a version that did not ship. A line like "instead of useAssistant, this uses usePlugin, which makes more sense because..." is noise to someone who never knew useAssistant existed. Cut it and just describe usePlugin.

Bad:
  We renamed useAssistant to usePlugin and moved the tools onto it,
  so instead of calling assistant.addTool you now use plugin.tools.

Good:
  Register tools on the plugin with plugin.tools:

  const plugin = usePlugin({ tools: [search] })

Ban this framing from the output: "instead of X", "we renamed", "previously called", "this replaces the old", "unlike the earlier", and any transitional name that never reached a release.

The one exception is a real migration. If users had X in a shipped, public release and you are moving them to Y, a short "Migrating from X" note is worth writing, because those readers actually used X. A name that only lived in a branch or a draft is not that. When unsure whether an old name shipped, leave it out.

Don't leak the build process

The doc is read by someone who just arrived. They never saw the pull request, the refactor, or the conversation where the design was decided (including a conversation with an agent while writing the code and the docs). Write as if the current design was always the design. Anything that only makes sense to someone who watched it change is noise to the reader.

Cut rejected alternatives. If a discussion weighed option A against option B and picked B, the doc documents B. It never names A, never says B is "better than" A, never says A "is no longer needed." The reader is not choosing between them; they use what shipped.

Bad:
  We use a plain JSON Schema here instead of zod, since it is lighter
  and zod is no longer a dependency.

Good:
  Pass the tool's input shape as a JSON Schema:

  [code]

Do not explain what something is not, when the reader never thought it was. If a piece moved out of a module during a refactor, the doc for its new home does not warn against the old arrangement. A reader who never knew locks lived inside persistence is only confused by a paragraph insisting locks are not a persistence store and must not be passed in as one. State what the thing is now, in its own terms.

Bad (in the locks doc):
  Locks are not a persistence store. Do not pass a lock into the stores
  map. That used to be possible but is wrong now.

Good (in the locks doc):
  A lock coordinates work across instances. Wire it with withLocks:

  [code]

The test: read the sentence as a brand-new user. If it answers a question they would never ask ("wait, was this somewhere else before?") or defends a choice they never knew existed, delete it. The doc has no memory of how it got here.

Forbidden

Never use these. Ever. This list has no exceptions: not "the neighboring pages use them", not "the repo's house style uses them", not "it reads better here".

• Em dashes and en dashes: the long — and the shorter –. Rewrite the sentence with a comma, colon, period, or parentheses instead.
• Separator glyphs like × or ·.
• The pattern "It's not X: it's Y." and the "Not just X, but Y" three-part build-up.
• The phrases "key insight", "gap", and variations of them.

If you catch yourself reaching for one of these, stop and rewrite the sentence in plain words.

Before you call a page done, search your own added text for —, –, ×, and ·. If a hit survived, you rationalized it. Fix it. Flagging it in your summary is not a substitute for fixing it.

Then run the simple-english self-check on the same added text.

Cross-linking and placement

• Put new pages where they fit the reader's path, grouped by what the reader is doing ("Building with React"), not by code layer ("Frontend Package API"). Update the site's nav or index so the page is reachable. An orphan page does not ship.
• Link related pages at the moment they help, inline in the flow, not as a "Related" dump at the bottom.
• Cross-linking goes both ways. When you add a page, update the older pages that should point into it.
• Do not over-link. One well-placed "need X? see Y" beats a list of maybes.

Red flags