Write Reed docs with AI coding assistants

Project instructions that let Claude Code, Cursor and Codex write valid Reed MDX, with reed check as the loop.

Claude Code, Cursor and Codex can draft pages, review a whole content directory for consistency, and update every example when an API changes. Left to their defaults, they will also write MDX for some other documentation platform: components Reed does not have, frontmatter fields it ignores, links without your base prefix.

The fix is a project instructions file, committed to your docs repository, that tells the assistant what a valid Reed page is — and a command it can run to find out whether it got there. Reed makes the second part unusually cheap: reed check is offline, fast, and fails loudly on the mistakes assistants make most.

What Reed gives an assistant to work with

Reed has no MCP server for authoring docs, no hosted agent and no web editor. What it has is a strict, checkable contract, which is what an assistant needs most:

docs.schema.json — a self-contained JSON Schema for docs.json, written next to it by reed init. An assistant that reads it knows every valid field, and that an unknown key is an error rather than a silent no-op.
A fixed catalog of 37 components that need no import. Anything not in the catalog and not locally imported is DS-S06. A local import is the one escape hatch — tell the assistant not to use it, so an invented component fails the check instead of slipping through. See Using components.
reed check — schema validation, page references, component contracts and accessibility rules, with no network and no build. Every failure has a DS-* code the assistant can look up in Diagnostics.
Plain-text docs about Reed itself. This site is built with Reed, so it has an llms.txt and a .md mirror of every page. An assistant with web access can read the component reference as markdown instead of scraping HTML.

reed mcp generate and reed skill generate are something else: they produce an MCP server and an Agent Skill for your API, for your users’ agents. They do not help an assistant write your docs. See MCP server generation.

Where each assistant reads its instructions

Assistant	File	Scope
Claude Code	`CLAUDE.md` at the repo root	Read at session start; nested `CLAUDE.md` files apply to their directories
Cursor	`.cursor/rules/*.mdc`	Project rules, shared through the repo; user rules stay on your machine
Codex	`AGENTS.md` at the repo root	Merged with `~/.codex/AGENTS.md` and any `AGENTS.md` in subdirectories, root first

Keep the substance in one file. The template below is written as AGENTS.md; Claude Code can pull it in with a one-line CLAUDE.md, and a short Cursor rule can point at it. One source of truth means the three tools cannot drift apart.

Set up

Install the assistant
Claude Code and Codex are command-line tools installed from npm. Cursor is a desktop editor. Each needs its own account — a Claude plan or API access, an OpenAI account with Codex, or a Cursor subscription.
Add the instructions file
Save the template as AGENTS.md at the root of your docs repository, adjust it, and commit it so every contributor gets the same behavior.
Start a session in the repo
Run the assistant from the directory that holds docs.json, so reed check works without flags.
Confirm it read the file
Ask it to list the Reed components it may use. The answer should match the catalog in your instructions, not a list from another platform.

1
npm install -g @anthropic-ai/claude-code
2
npm install -g @openai/codex

Template: `AGENTS.md`

Replace /docs with your own base — or drop the prefix rule if your site has no base — and replace the style section with your own guide.

1
# Documentation project (Reed)
2

3
This repository is a Reed documentation site. Reed compiles `docs.json` plus MDX in
4
`content/` into a static site. Treat the rules below as hard constraints: violating
5
most of them fails `reed check`.
6

7
## Project layout
8

9
- `docs.json` is the only config file. Validate every edit against `docs.schema.json`
10
  in the same directory. Unknown keys are errors; never copy field names from another
11
  docs platform.
12
- A page's id is its path under `content/` without `.mdx`:
13
  `content/guides/seo.mdx` is `guides/seo`. A nested `index.mdx` collapses to its
14
  directory.
15
- Every page must be listed in `navigation` in `docs.json`. There are no hidden pages: a
16
  file left out of navigation fails `reed check` with `content-page-not-in-navigation`.
17
  When you add a page, add it to navigation in the same change.
18
- Never edit `.reed/` (build cache) or the build output directory.
19

20
## Frontmatter
21

22
- Every page has exactly `title` and `description`. Nothing else unless asked.
23
- `title` renders as the page H1. Never write a `#` heading in the body.
24
- `description` is one sentence saying what the page helps the reader do. It becomes
25
  the meta description, the structured-data description (when `site` is set) and the
26
  page's line in llms.txt, so never leave it out.
27

28
## Headings
29

30
- Body headings start at `##` and never skip a level (`##` to `####` is an error).
31

32
## Components
33

34
Use only these 37 components. They need no import. Never add an `import` line.
35

36
Note, Tip, Info, Warning, Danger, Check, Success, Error, Launch, Callout,
37
Card, CardGroup, Columns, Tiles, Frame, Panel, Aside, Banner,
38
Accordion, AccordionGroup, Steps, Step, Tabs, Tab, CodeBlock, CodeGroup,
39
ParamField, ResponseField, Badge, Table, Files, Folder, File,
40
Expandable, Icon, Tooltip, Update
41

42
- Any other name is error DS-S06. If a component you want is not listed, use plain
43
  markdown instead.
44
- `CardGroup` contains only `Card`. `AccordionGroup` contains only `Accordion`.
45
  `Steps` needs at least two `Step`; `Tabs` needs at least two `Tab`.
46
- `Accordion` requires `title`. `Card` takes `title` and `href`.
47
- Put fenced code blocks at the top level, after the component, not inside `Step`,
48
  `Tab`, `Card` or `Accordion`. If a fence must go inside one, the opening tag, the fence
49
  and the closing tag each need their own lines with blank lines between; a tag on the
50
  same line as the fence or as prose fails with unparseable-mdx.
51
- Prefer plain markdown. Most pages need no components at all.
52

53
## Code blocks
54

55
- Every fence has a language tag: sh, json, mdx, txt, ts, python...
56
- Same example in several languages: wrap the fences in `CodeGroup`, one fence per
57
  language, each with a `title` naming its language. Put `<CodeGroup>`, `</CodeGroup>`
58
  and each fence on their own lines, with blank lines between. See
59
  /docs/authoring/formatting/code.
60
- Prefer a plain fence to `CodeBlock`. Use `CodeBlock` only for `focus` or `maxLines`,
61
  and pass code containing `{` through its `code` prop or a fenced child, never as loose
62
  text.
63
- An mdx example that itself contains a fence uses a four-backtick outer fence.
64
- Never put real secrets in examples.
65

66
## Links
67

68
- This site has `base: "/docs"`. Reed does NOT rewrite links in MDX. Every internal
69
  link in prose and in component `href` attributes starts with `/docs/`, for example
70
  [Quickstart](/docs/quickstart).
71
- A link without the prefix builds fine and 404s in production.
72
- Links inside `docs.json` (footer, redirects, head.link) are the opposite: write them
73
  without the base. Reed adds it.
74
- Use descriptive link text, never "click here".
75

76
## Images and accessibility
77

78
- Every image has meaningful alt text (missing alt is DS-A01).
79
- An icon-only link or button needs a `label` (DS-A03).
80

81
## Style
82

83
- Second person, present tense, active voice. Short declarative sentences.
84
- Lead each section with the answer. No "In this guide we will".
85
- One name per concept. No marketing words.
86
- Never invent product behavior. If you are unsure, ask.
87

88
## Verify before you finish
89

90
1. Run `reed check`. Fix every error. Treat DS-D07 and DS-D08 warnings as real.
91
2. Check that every internal link starts with `/docs/` and points at a page that exists.
92
3. If you changed navigation or descriptions, run `reed build --out dist` and read
93
   `dist/llms.txt`.
94
4. Report what you ran and its actual output. Never claim a check passed without
95
   running it.

The rules are specific on purpose. “Use Reed components” teaches an assistant nothing; the literal list, the nesting constraints and the fence rule are what stop the three failures you would otherwise fix by hand on every page.

Claude Code

A one-line CLAUDE.md imports the shared file:

1
@AGENTS.md

Add anything Claude-specific below the import. Claude Code also supports custom slash commands in .claude/commands/ — a /new-page command that scaffolds frontmatter and adds the navigation entry is a good first one.

Cursor

Create .cursor/rules/reed.mdc. Keep it short and let it defer to AGENTS.md:

1
---
2
description: Rules for writing Reed documentation pages
3
globs: ["content/**/*.mdx", "docs.json"]
4
alwaysApply: false
5
---
6

7
This is a Reed documentation project. Before editing any page or docs.json,
8
read AGENTS.md at the repository root and follow it exactly.
9

10
The three rules broken most often:
11
- Only components from the 37-name catalog in AGENTS.md; no imports.
12
- Internal links start with the site's base prefix, e.g. /docs/quickstart.
13
- No fenced code blocks inside JSX components.
14

15
After editing, run `reed check` in the terminal and fix every error.

Codex

Codex reads AGENTS.md directly, so there is nothing more to add. If you keep personal preferences in ~/.codex/AGENTS.md, remember that the project file is applied after it and wins on conflicts.

Make `reed check` the loop

An assistant that can run a check and read its output corrects itself. One that cannot will tell you the page is done.

1
reed check

check needs no network and no prior reed prefetch, so it works in any sandbox the assistant runs in. Two gaps are worth knowing about:

Prose links are not checked. reed check validates docs.json, page references and components — not links written in MDX. Give the assistant a mechanical link check, even a short script that finds every root-relative link and confirms it starts with your base and names a real page. This site runs one on every change.
Build-only outputs. llms.txt, robots.txt, the sitemap and _headers exist only after reed build; reed dev writes none of them. The .md mirrors are the exception: reed dev serves those too.

Run the same checks in CI so a page the assistant got wrong cannot merge. See Offline builds in CI.

Sample prompts

These work in any of the three tools once the instructions file is in place.

Turn notes into a page:

1
Turn these notes into a new page at content/guides/webhooks.mdx, add it to the Guides
2
group in docs.json after guides/linking, and run reed check: [paste notes]

Review for consistency:

1
Review every page under content/guides/ against AGENTS.md. List violations by file.
2
Do not change anything yet.

Update after a product change:

1
Our API now requires a version query parameter. Add version=2026-09 to every request
2
example under content/api/, then run reed check and show me the output.

Port a page from another platform:

1
This page was written for a different docs platform. Rewrite it using only the Reed
2
components listed in AGENTS.md, fix the links for our /docs base, and run reed check.

Working patterns that help

Separate writing from reviewing. Draft in one session and review in a fresh one with no memory of the draft. The reviewer catches what the writer rationalized.
Review diffs, not claims. An assistant saying it fixed every link is not the same as the link check passing. Ask for the command output.
Treat drafts as drafts. Assistants are good at generating docs from source code, OpenAPI specs and tickets. They are not a source of truth about what your product does; a person who knows the product signs off.
Refine the instructions file. Every time you correct the same mistake twice, add a line to AGENTS.md. The file is shared, so the fix reaches everyone.

See Git workflows for branching and review, and Style and tone for what belongs in the style section.

Frequently asked questions

Do I need an instructions file at all?

No, but without one the assistant falls back on what it knows about MDX in general, which mostly means other platforms’ components and conventions. The file saves you repeating the same corrections in every prompt, and reed check catches what it still gets wrong.

Is there a Reed MCP server my assistant can connect to?

No. Reed has no hosted service, so there is no endpoint to connect to and no agent that edits your docs remotely. The assistant works on files in your repository and verifies them with the reed CLI. The MCP generator produces a server for your own API, not for authoring docs.

Which tool should I use?

Command-line agents like Claude Code and Codex suit repository-wide work: auditing every page for missing alt text, renaming a parameter in every example, reviewing a whole section. Cursor suits editing one page at a time with inline suggestions. All three read project instructions and can run reed check, so the choice is about how you like to work.

How do I share the configuration with my team?

Commit AGENTS.md, CLAUDE.md and the .cursor/rules directory. Anyone who clones the repository and starts an assistant there gets the same rules without setting anything up.