Author with AI

AI agents are first-class authors in Avodado — the intended flow is that your agent writes the docs and you review them. Instead of generating loose Markdown, agents write typed blocks against clear schemas, and avo check catches anything they invent. Three setups cover every tool (avo init runs the first one for you).

1. AI coding tools (Claude Code, Cursor, Copilot, Windsurf)

Run one command:

avo install claude       # or: cursor · copilot · windsurf

This writes the authoring guide to .avodado/skill/SKILL.md — the block grammar, the reference scheme, and worked examples for all 87 blocks — plus the file your tool reads automatically:

From then on, any agent working in your repo knows how to write valid Avodado docs. avo init offers the same setup interactively.

2. Other AI tools (ChatGPT, Gemini, custom GPTs)

For tools that don't read repo files, print the guide as a system prompt and paste it in:

avo skill                # print it (and copy to clipboard)
avo skill -o avodado.md  # save it to a file

3. The MCP server

The MCP server gives agents real tools instead of guesswork — they can look up a schema, validate a doc, and render it, all through the Model Context Protocol. No configuration or API key needed:

claude mcp add avodado -- npx -y @avodado/mcp

// Claude Desktop / Cursor config
{ "mcpServers": { "avodado": { "command": "npx", "args": ["-y", "@avodado/mcp"] } } }

avo mcp prints these snippets for every client.

The tools

A typical agent loop: read the guide → write the doc → check_document → fix → render_document.

How to prompt

Once the skill is installed, ordinary prompts work — the agent already knows the grammar. What helps is naming the file, the blocks you want, and asking it to run avo check:

Document our checkout flow in docs/checkout.md: a sequence diagram of the payment path, an ERD of the order tables, and a status table of the rollout. Run avo check and fix anything it reports.

Read src/api/routes/ and write docs/api.md — an endpoint block per route, plus a c4 container diagram of how the services connect.

Add a decision record to docs/adr.md for switching the queue to Kafka — the context, the options we considered, and the decision.

Turn docs/orders.md into a slide deck outline: tighten each section to one idea per heading, then run avo slides docs/orders.md.

You can go vaguer ("document this repo") — the agent will pick sensible blocks. And if it ever invents a field, avo check names the file, line, and problem, so "fix what avo check reports" is always a complete follow-up prompt.

Edits appear live

Agents edit the same .md files everything else reads, so there's no sync step. Keep avo studio open while an agent works and every saved edit appears on the open doc immediately — the intended setup is you in the studio, the agent in the terminal.

Related

• How blocks work — what the skill teaches, in human-readable form.
• Validation — the checks agents fix against.
• CLI · AI commands — install, skill, mcp, tour.