Author with AI
The authoring skill, four editor adapters, a copy-paste system prompt, and an MCP server — same files, many editors.
Avodado treats AI agents as first-class authors. The grammar they need ships three ways — a repo skill, a system prompt, and an MCP server — and because the files on disk are the only source of truth, an agent's edits show up live in every other editor.
The skill + editor adapters
avo init (or avo install <tool>) writes the authoring skill to
.avodado/skill/SKILL.md — the block grammar, the doc#id scheme, YAML
pitfalls, and worked examples for all 77 blocks — plus an adapter file that
points your AI tool at it:
| Tool | Adapter file |
|---|---|
| Claude Code | CLAUDE.md |
| Cursor | .cursor/rules/avodado.mdc |
| GitHub Copilot | .github/copilot-instructions.md |
| Windsurf | .windsurfrules |
avo install claude # install/update the skill + the Claude Code adapter
avo install cursor # …same for cursor | copilot | windsurfAny agent already in your repo picks it up automatically and can author
valid Avodado docs immediately — and avo check keeps it honest.
No repo convention? avo skill
Using an AI tool without a repo-file convention — Microsoft 365 Copilot,
a custom GPT, ChatGPT, Gemini? Run avo skill to print the whole authoring
grammar as a copy-paste system prompt (it also lands on your clipboard);
paste it into the tool's system / custom-instructions box.
avo skill # print + clipboard
avo skill -o avodado.md # save to a file · avo skill --raw for the bare skillThe MCP server
@avodado/mcp exposes the doc
tooling over the Model Context Protocol — transport is stdio, no
configuration or API key required:
claude mcp add avodado -- npx -y @avodado/mcp// Claude Desktop / Cursor
{ "mcpServers": { "avodado": { "command": "npx", "args": ["-y", "@avodado/mcp"] } } }avo mcp prints these snippets (and more) in the terminal; avo mcp --stdio
starts the server directly.
Tools
| Tool | What it does |
|---|---|
get_authoring_guide | The full Avodado authoring grammar — read first before authoring. |
list_block_types | Every supported block type. |
get_block_schema(type) | JSON Schema (fields, enums) for one block type. |
check_document(markdown, slug?) | Parse + validate; returns diagnostics (empty = valid). |
render_document(markdown, slug?, theme?) | Render to standalone styled HTML. |
resolve_refs(documents[]) | Cross-check doc#id references (dangling refs, duplicate ids). |
sync_openapi(spec, slug?) | Generate an Avodado doc from an OpenAPI (JSON) spec. |
It also serves one resource: avodado://skill — the authoring guide.
The typical agent loop
get_authoring_guide→ learn the block grammar.- Write Avodado Markdown.
check_document→ fix any diagnostics.render_document→ styled HTML.
AI edits appear live
Because agents edit the same .md files everything else reads, there's no
sync step: keep avo studio open while an agent
works, and every saved edit repaints live in Edit and Site mode alike (the
studio listens for file changes over SSE). Human in the studio, agent in the
terminal — same files, no conflicts by construction.
Related
- The block grammar — what the skill teaches, in human-readable form.
- Validation — the diagnostic codes agents fix against.
- CLI · AI commands —
install,skill,mcp,tour.