Skip to main content

The AI agent

The AI agent is the center column of the editor. Type a request, hit enter, and the agent does the rest.

How it works

The agent has tools for reading and writing every file in your project, scraping URLs you point it at, listing the current site structure, and managing the sidebar. It picks the right tools automatically based on what you ask.

A typical edit looks like:

  1. You: "Add a page on streaming responses under API Reference."
  2. Agent: reads existing API Reference pages to match the tone.
  3. Agent: writes a new file with proper frontmatter, sidebar position, content.
  4. Agent: updates the sidebar so the page appears in the right place.
  5. Live preview updates in seconds.

You see each tool call as the agent works.

Plan mode

For big changes — restructuring categories, rewriting half your docs, migrating content — the agent uses plan mode. Instead of editing immediately, it shows you a numbered plan first:

  1. Create a new "Authentication" category between Getting Started and API Reference.
  2. Move the existing "Auth" page into it as overview.md.
  3. Add three new pages: API keys, OAuth, JWT verification.
  4. Update internal links in 8 pages that referenced the old Auth page.

You approve, suggest changes, or reject. Approved plans run with progress shown step by step.

Plan mode triggers automatically when the agent estimates the change touches more than a few files.

Writing prompts that work

The agent is good at vague requests but great at specific ones. A few patterns:

  • Be concrete about scope. "Rewrite the Quickstart" works. "Rewrite the Quickstart so it's under 200 words and ends with a link to Custom Domains" works better.
  • Reference real things. "Make it more like the API Reference page" — the agent will read that page and match its style.
  • Ask for the diff first. "Show me what you'd change before changing anything" — the agent will lay out a plan without writing.
  • Iterate small. Big rewrites in one prompt are fine, but iterating in 2-3 messages usually produces tighter results.

What the agent can read

  • Every file in your project (markdown content, config, theme files)
  • Any URL you give it (via web scraping)
  • Files you upload directly into the chat
  • Other documentation sites (for inspiration: "look at how Stripe documents webhooks and write ours similarly")

What it won't do

  • Run your code or hit your APIs — the agent edits files, not your product.
  • Publish on its own — publishing is always your explicit click in the top-right.
  • Send emails or post to external services — read-only access to anything outside your project.
  • Bypass your plan limits — free accounts get 10 messages per month per project.

Free vs Pro

  • Free: 10 messages per project per month, resets the 1st of the month.
  • Pro: unlimited messages.

If you hit the free limit, the agent locks until the next reset. The editor still works for direct edits.

Tips from real usage

  • Onboarding edits are free. The first burst of messages during URL-mode generation doesn't count against your monthly limit.
  • Reset doesn't carry over. Unused free messages don't bank for next month.
  • Long prompts beat many short ones when describing complex changes — the agent has more context to plan against.
  • Pages and categories — manual file management when you want it.
  • Author MCP — the same agent capabilities, but driven by Claude Code or Cursor instead of the Docsio editor (Pro).