AI coding tools like Claude Code and Cursor can write your documentation — but only well if they know Doxbrix's real blocks and conventions. The combination of a...
AI coding tools like Claude Code and Cursor can write your documentation — but only well if they know Doxbrix's real blocks and conventions. The combination of a...
AI coding tools like Claude Code and Cursor can write your documentation — but only well if they know Doxbrix's real blocks and conventions. The combination of a skill (instructions teaching the agent the Doxbrix workflow) and the MCP server (live access to your block catalog and validation) makes AI-authored docs accurate and consistent.
The two pieces
| Piece | What it provides |
|---|---|
| **Skill** | Step-by-step instructions: confirm it's a Doxbrix project, learn the blocks, plan structure, write, validate, hand off. |
| **MCP server** | Live tools: the [block catalog](/cli/mcp/tools), `search_docs`, `get_page`, and `validate_mdx`. |
The skill tells the agent how to work; the MCP gives it the ground truth to work from. Together they prevent the two most common failure modes — invented component names and wrong props.
The skill
The Doxbrix authoring skill is a set of instructions an agent loads when working in a docs project. dxb init scaffolds it for you by default, into .claude/skills/doxbrix-authoring/ (use --no-claude-skill to skip).
Run dxb init (it adds the skill), or place the skill under your agent's skills directory.
The skill ships with a blocks cheat-sheet used when the MCP isn't connected.
Commit the skill so every contributor's agent uses the same conventions.
The skill encodes the authoring workflow: learn blocks → plan structure → write .mdx → validate → hand off for review. Critically, it instructs the agent never to publish unprompted — authoring means editing local files; publishing is a separate, human-initiated step.
Connect the MCP
Connect the MCP server so the agent has live access to your real components:
{
"mcpServers": {
"doxbrix": {
"command": "npx",
"args": ["-y", "@doxbrix/mcp"],
"env": {
"DOXBRIX_TOKEN": "<your-token>",
"DOXBRIX_PROJECT": "my-docs"
}
}
}
}With the MCP connected, the skill has the agent read doxbrix://components and call validate_mdx before writing — so output is correct by construction.
Skill with vs. without the MCP
The skill works either way, degrading gracefully:
| Col 1 | MCP connected (preferred) | MCP not connected |
|---|---|---|
| Block catalog | Live from `doxbrix://components` | From the bundled cheat-sheet |
| Validation | `validate_mdx` before writing | `dxb lint` after writing |
| Context | `search_docs` / `get_page` | Reads local files |
A good AI-authoring loop
Open the docs repo so the agent sees docs.json and .doxbrix/config.json.
The skill has it read the component catalog (via MCP) or the cheat-sheet.
"Write a guide on configuring webhooks." The agent drafts using real blocks.
The agent runs validate_mdx (or dxb lint) and fixes issues.
Preview with dxb dev, then publish yourself.
Supported tools
The skill + MCP approach works with any MCP-capable agent, including:
- Claude Code — skill in
.claude/skills/, MCP in the MCP config. - Cursor — MCP in its settings; the skill as project rules.
- Other MCP clients — connect
doxbrix-mcpand provide the authoring instructions.