--- title: Write Reed docs with AI coding assistants description: 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`](/docs/reference/cli/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`](/docs/reference/cli/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](/docs/authoring/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](/docs/reference/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](/docs/derived/mcp). ## 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 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. 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. Run the assistant from the directory that holds `docs.json`, so `reed check` works without flags. 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. ```sh npm install -g @anthropic-ai/claude-code 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. ````mdx # Documentation project (Reed) This repository is a Reed documentation site. Reed compiles `docs.json` plus MDX in `content/` into a static site. Treat the rules below as hard constraints: violating most of them fails `reed check`. ## Project layout - `docs.json` is the only config file. Validate every edit against `docs.schema.json` in the same directory. Unknown keys are errors; never copy field names from another docs platform. - A page's id is its path under `content/` without `.mdx`: `content/guides/seo.mdx` is `guides/seo`. A nested `index.mdx` collapses to its directory. - Every page must be listed in `navigation` in `docs.json`. There are no hidden pages: a file left out of navigation fails `reed check` with `content-page-not-in-navigation`. When you add a page, add it to navigation in the same change. - Never edit `.reed/` (build cache) or the build output directory. ## Frontmatter - Every page has exactly `title` and `description`. Nothing else unless asked. - `title` renders as the page H1. Never write a `#` heading in the body. - `description` is one sentence saying what the page helps the reader do. It becomes the meta description, the structured-data description (when `site` is set) and the page's line in llms.txt, so never leave it out. ## Headings - Body headings start at `##` and never skip a level (`##` to `####` is an error). ## Components Use only these 37 components. They need no import. Never add an `import` line. Note, Tip, Info, Warning, Danger, Check, Success, Error, Launch, Callout, Card, CardGroup, Columns, Tiles, Frame, Panel, Aside, Banner, Accordion, AccordionGroup, Steps, Step, Tabs, Tab, CodeBlock, CodeGroup, ParamField, ResponseField, Badge, Table, Files, Folder, File, Expandable, Icon, Tooltip, Update - Any other name is error DS-S06. If a component you want is not listed, use plain markdown instead. - `CardGroup` contains only `Card`. `AccordionGroup` contains only `Accordion`. `Steps` needs at least two `Step`; `Tabs` needs at least two `Tab`. - `Accordion` requires `title`. `Card` takes `title` and `href`. - Put fenced code blocks at the top level, after the component, not inside `Step`, `Tab`, `Card` or `Accordion`. If a fence must go inside one, the opening tag, the fence and the closing tag each need their own lines with blank lines between; a tag on the same line as the fence or as prose fails with unparseable-mdx. - Prefer plain markdown. Most pages need no components at all. ## Code blocks - Every fence has a language tag: sh, json, mdx, txt, ts, python... - Same example in several languages: wrap the fences in `CodeGroup`, one fence per language, each with a `title` naming its language. Put ``, `` and each fence on their own lines, with blank lines between. See /docs/authoring/formatting/code. - Prefer a plain fence to `CodeBlock`. Use `CodeBlock` only for `focus` or `maxLines`, and pass code containing `{` through its `code` prop or a fenced child, never as loose text. - An mdx example that itself contains a fence uses a four-backtick outer fence. - Never put real secrets in examples. ## Links - This site has `base: "/docs"`. Reed does NOT rewrite links in MDX. Every internal link in prose and in component `href` attributes starts with `/docs/`, for example [Quickstart](/docs/quickstart). - A link without the prefix builds fine and 404s in production. - Links inside `docs.json` (footer, redirects, head.link) are the opposite: write them without the base. Reed adds it. - Use descriptive link text, never "click here". ## Images and accessibility - Every image has meaningful alt text (missing alt is DS-A01). - An icon-only link or button needs a `label` (DS-A03). ## Style - Second person, present tense, active voice. Short declarative sentences. - Lead each section with the answer. No "In this guide we will". - One name per concept. No marketing words. - Never invent product behavior. If you are unsure, ask. ## Verify before you finish 1. Run `reed check`. Fix every error. Treat DS-D07 and DS-D08 warnings as real. 2. Check that every internal link starts with `/docs/` and points at a page that exists. 3. If you changed navigation or descriptions, run `reed build --out dist` and read `dist/llms.txt`. 4. Report what you ran and its actual output. Never claim a check passed without 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: ```txt @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`: ```mdx --- description: Rules for writing Reed documentation pages globs: ["content/**/*.mdx", "docs.json"] alwaysApply: false --- This is a Reed documentation project. Before editing any page or docs.json, read AGENTS.md at the repository root and follow it exactly. The three rules broken most often: - Only components from the 37-name catalog in AGENTS.md; no imports. - Internal links start with the site's base prefix, e.g. /docs/quickstart. - No fenced code blocks inside JSX components. 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. ```sh 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](/docs/ship/ci-offline). ## Sample prompts These work in any of the three tools once the instructions file is in place. **Turn notes into a page:** ```txt Turn these notes into a new page at content/guides/webhooks.mdx, add it to the Guides group in docs.json after guides/linking, and run reed check: [paste notes] ``` **Review for consistency:** ```txt Review every page under content/guides/ against AGENTS.md. List violations by file. Do not change anything yet. ``` **Update after a product change:** ```txt Our API now requires a version query parameter. Add version=2026-09 to every request example under content/api/, then run reed check and show me the output. ``` **Port a page from another platform:** ```txt This page was written for a different docs platform. Rewrite it using only the Reed 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](/docs/guides/git-workflows) for branching and review, and [Style and tone](/docs/guides/style-and-tone) for what belongs in the style section. ## Frequently asked questions 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. 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. 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. 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.