With DocStar, every API you document gets a setup guide that AI agents read before they touch your API: the skill that ships with your collection's MCP server. A setup guide for AI agents is a short, ordered set of instructions an agent can follow on its own: what your product is for, which steps to run in which order, what to ask the human, what never to do, and how to confirm it worked. Human quickstarts explain; agent setup guides instruct.
This post shows what a good agent setup guide contains, and how to have your own coding agent write it, publish it and keep it current in DocStar, so you review the result instead of writing it from scratch.
Why AI agents need a different kind of setup guide
A human skims your quickstart and clicks around until something works. An agent takes your words literally, fetches several pages to fill gaps and guesses when the order of calls isn't written down. If a step needs a human (signing in, approving access), it may stall or try to work around it.
| Human quickstart | Setup guide for AI agents | |
|---|---|---|
| Goal | Explain the product and build confidence | Get a task done correctly, first time |
| Format | Narrative, screenshots, tips | Short ordered steps and rules |
| Decisions | "Choose what fits you" | Explicit branches: "if X, do Y" |
| Human steps | Implied | Named: "stop and ask the user to..." |
| Safety | Rarely stated | Which actions are safe, which need confirmation |
| Done check | "You should see..." | A call or check the agent can run itself |
| Reply to the user | Not covered | What to say, in two or three sentences |
In DocStar you don't maintain two sets of docs: the same collection serves your human docs, the agent setup guide, the tools and the Markdown agents read.
What a good agent setup guide contains
Whether you write it yourself or have an agent draft it, a setup guide agents can follow covers seven things:
What the API is for, in two or three sentences. Agents use this to decide whether your tools are the right ones for the user's request.
The usual order of calls. "List projects, then create a task in a project." "Call Create Customer before Create Invoice." This is the single most useful line you can write.
How ids relate. Where an
account_idcomes from, which call returns theproject_idthe next call needs.Rules and limits. Required fields, rate limits, formats, versions to use.
Safe vs. confirm-first actions. Reading is fine; deleting, sending or charging needs the user's yes.
What only a human can do. Signing in, approving OAuth consent, entering secrets. The agent should stop and ask, not improvise.
Common mistakes and how to check success. The errors agents hit most, and one call that proves the setup worked.
Keep it short: every line should change what the agent does.
How DocStar gives your API a setup guide agents read first
Every DocStar collection has its own hosted MCP server, and every MCP server ships with a skill: a short quickstart guide that assistants load before they use your API. That skill is your agent setup guide. Here's what DocStar gives you around it, as described in Build an MCP Server for Your App:
| DocStar feature | What it does for agents |
|---|---|
| Generated skill | DocStar writes the skill from your docs and keeps it following your docs and tools as they change. |
| Your own skill | Write it when you know things the docs don't say: call order, how ids relate, common mistakes. Reset it any time to go back to the generated one. |
| Additional instructions | Short rules assistants receive every time they connect, such as "Ask for the account id before creating an order". Keep them under 2,000 characters. |
| Endpoint tools | Up to 20 of your most important endpoints as named tools, with safety hints (read-only, destructive, idempotent, open-world) so assistants know when to ask first. |
| Sign-in for API calls | Users call your API with their own account; the assistant asks them to sign in the first time. |
| llms.txt and Markdown pages | DocStar generates llms.txt and a Markdown copy of every published page (add .md to the URL), so a setup page in your docs is easy for agents to fetch. |
We use the same pattern ourselves. When you ask an assistant to build an MCP server with DocStar, the prompt points it at https://docstar.io/mcp/quickstart.md, a single page written for agents to follow step by step.
Only published content reaches your MCP server; drafts never do.
Let your coding agent write the setup guide
DocStar is built to be run by AI agents. Your coding agent can read your code and your DocStar docs at the same time, which makes it better placed than anyone to write the setup guide. Here's the main path.
Step 1: Connect your agent to DocStar
Add DocStar to Claude Code, Cursor, Codex or another assistant. Use DocStar from your assistant's connector directory if it's listed; if not, add it as a custom remote MCP server:
https://mcp.docstar.io/mcp
The first time the agent needs your workspace, you sign in to DocStar in your browser. There's no API key to copy. Full steps: Connect Your AI Assistant.
Step 2: Give it one prompt
Open your API's repository in the agent and paste:
Use the DocStar MCP. First read https://docstar.io/mcp/quickstart.md and follow it. Then write the MCP skill for my API collection "YOUR COLLECTION NAME" as a setup guide for AI agents. Read my latest code, not old docs. Cover: what the API is for in 2-3 sentences, the usual order of calls, how ids flow between calls, required fields and limits, which endpoints are safe to call freely and which need the user's confirmation, what only the user can do (like signing in), the most common errors and one call that proves setup worked. Keep it short. Also suggest short additional instructions for rules that must always apply. Show me both before you save anything.
Step 3: Let the agent do the work
From that one prompt, the agent:
Reads your routes, handlers and validation to find the real order of calls and the ids each call needs.
Reads your DocStar collection to see which endpoints are documented and published.
Drafts the skill and a short set of additional instructions.
Suggests named tools and safety hints (for example,
delete_invoiceas destructive).Shows you everything and asks before it changes or publishes anything.
A skill it writes might start like this:
# Acme Billing API: setup guide for agents
Acme Billing creates customers, invoices and payments.
Order: create_customer -> create_invoice (needs customer_id) -> send_invoice.
Always list_customers first; never create a duplicate customer for the same email.
Safe: list_*, get_*. Confirm with the user first: send_invoice, delete_invoice, refund_payment.
The user must sign in the first time you call the API. If a call returns 401, ask them to sign in again.
Setup check: list_customers returns 200.
Step 4: You review and decide
Your role is judgment, not typing:
Accuracy. Is the call order right? Are the limits current?
Safety. Is every destructive action marked confirm-first?
What stays private. Internal endpoints and admin-only flows don't belong in a public setup guide.
The few human-only steps. If users should call your API with their own account, you enter your OAuth app's details in the collection's MCP tab yourself.
Then tell the agent to save, and publish the docs it drafted.
Publish a setup page agents can fetch directly
Some agents never connect to your MCP server: a developer pastes your docs link into a coding agent, or an assistant browses your site. Give them a setup page too.
Ask your agent:
Using the DocStar MCP, create a page called "Setup for AI agents" in my docs collection with the same steps as the skill, written for agents: numbered steps, explicit if/then branches, what to ask the user, and a final check. Save it as a draft.
Once you publish it, DocStar serves a Markdown copy at the page URL plus .md, and lists it in your generated llms.txt, which links to those Markdown versions. See SEO, Sitemap and llms.txt.
If your docs live in your repo, the agent can write the page in your docs/ folder instead, and GitHub Sync sends it to DocStar on push.
Keep it current
An outdated setup guide is worse than none: the agent follows it confidently and fails.
Let the generated skill do the work where it can. If you don't need custom guidance, keep DocStar's generated skill. It follows your docs and tools as they change. Endpoint tools with an empty description also follow the endpoint's docs.
Update docs in the same change as the code. With GitHub Sync, your OpenAPI files in api-docs/ live next to the code, so they change in the same commit and pull request, and spec changes show up in the PR diff. Add docstar.md and one line in AGENTS.md, and your coding agent updates the endpoint's spec whenever it changes the endpoint. On push, the GitHub Action publishes the change to your docs site, MCP tools and CLI. The agent still has to do it: if someone changes code without an agent, or the agent skips the rule, docs can drift. More on that in What Is AGENTS.md?
Refresh your custom skill when the flow changes. Once you write your own skill, it no longer follows doc changes, so add it to your release routine:
Using the DocStar MCP, compare my collection's MCP skill and the "Setup for AI agents" page with the current code and published docs. List anything that's wrong or missing, then propose updated text. Don't save until I approve.
Use the logs as feedback. In the MCP tab, Logs shows every call assistants made to your API through your MCP server, with the request, the response and a one-line reason when it failed. Repeated 404s mean agents are using wrong paths or ids; 400 or 422 means the body was wrong. Each pattern is a line your setup guide is missing. Calls are kept for two weeks.
Prefer to write it yourself?
Open your collection's settings, go to the MCP tab, and edit the skill and additional instructions there, using the seven-point checklist above. Good tool descriptions matter as much as the skill; see How to Write MCP Tool Descriptions That AI Agents Actually Understand.
Why teams choose DocStar
One source, every reader. The same collection powers your docs site, llms.txt, Markdown copies, your MCP server and its skill, and a CLI.
A setup guide by default. Every MCP server ships with a generated skill, so agents get guidance from day one.
Control where it matters. Custom skill, instructions, named tools with safety hints, and per-user sign-in.
Agent-first workflow. Your coding agent drafts it all through the DocStar MCP; you review and publish.
FAQ
What is a setup guide for AI agents? A short set of ordered instructions an agent follows on its own to set up or use your product: purpose, call order, rules, safe vs. confirm-first actions, human-only steps and a success check. In DocStar it's the skill your MCP server ships with.
Does DocStar write the skill for me? Yes. DocStar generates a skill from your docs, and it follows your docs and tools as they change. You can write your own at any time and reset to the generated one later.
What's the difference between the skill and additional instructions? The skill is longer guidance assistants load before using your API. Additional instructions are short rules, under 2,000 characters, assistants receive every time they connect.
Can agents that don't use my MCP server read the guide? Yes, if you publish it as a page. DocStar serves a Markdown copy of every published page and lists pages in your llms.txt.
Get started free
Give your API a setup guide AI agents can follow, written by your own coding agent and kept next to your docs. Get started free.
Originally published on the DocStar blog. Try DocStar free: https://docstar.io
Top comments (0)