write-docusaurus-agent-guide

Write an agent guide

Done when

npm run build logs [MCP] Packaged N skill(s), including M agent guide(s) with no [MCP] Agent guide: warnings, and the compiled SKILL.md lists every step in order, each with its check.

Before you start

• The site builds with the plugin: npm run build writes build/mcp/bundle.json. If not, follow Getting started first.
• A procedure for one task, with an end someone can see: a command's output, a page that loads, a setting that shows as on.

How to use this guide

• Do the steps in order. Run them yourself, or walk the user through them one at a time if they'd rather do it themselves or you can't run them.
• After each step, run its check. Don't move on until it passes.
• If a check fails, look for the matching symptom under Troubleshooting. If none matches, stop and tell the user what you saw.
• A step marked Needs the user needs a person. Tell the user what to do and wait for them to confirm it's done.
• Ask the user before running a step marked Confirm first.
• Don't ask the user to paste passwords, tokens, or keys into the chat. When a step needs one, tell the user where to put it.

Steps

1. Wrap the procedure {#wrap}

Wrap the procedure in AgentGuide and say how to tell it worked with DoneWhen. The components need no import; the plugin adds them to your theme's MDX components:

<AgentGuide
  name="setup-widget"
  kind="setup"
  description="Install the widget CLI. Use when the user wants to install or set up the widget.">

<DoneWhen>

`widget --version` prints a version number.

</DoneWhen>

<Prerequisites>

- Node.js 22 or later. Check: `node --version`.

</Prerequisites>

...the steps...

</AgentGuide>

• name becomes the skill's name: up to 64 lowercase letters, digits, and single hyphens. It can't match another skill's name, including the built-in docs-research. Make it specific enough to stand out among the other skills an agent has installed.
• kind is setup for a procedure with steps, or troubleshooting for symptoms only, for problems that aren't tied to one setup.
• description is what an agent reads to decide whether to use the guide, up to 1024 characters. Say what it does, then "Use when…".
• title is optional: the compiled guide's title. Without it, the guide uses the page's h1.
• DoneWhen says how to tell the whole guide worked. Every guide has exactly one.
• Prerequisites is optional, and only for setup guides: what has to be true before step 1, each with how to check it.