Harkirat Chahal
Growth
Share this article
Harkirat Chahal
Growth
Share this article
We built mint instructions to give coding agents current, task-specific guidance for Mintlify. Then we tested it.
In our first benchmark, Claude Sonnet passed 16% of runs with the command available, compared with 20% without it. The guidance was not the problem. Agents never ran the command.
After we added one pointer to the repository's root AGENTS.md and revised the guidance around the mistakes agents made, Sonnet's pass rate reached 100%.
The command failed because agents never ran it #
People rarely reinstall plugins, so skills drift fast. So where should current guidance live so agents read it when they need it?
Our first version listed mint instructions in mint --help. We assumed agents would check the help on an unfamiliar task. They didn't. They read the task, looked around the repo, and started editing.
Sonnet got everything right in 16% of runs with the command and 20% without it. That's noise.
One line in AGENTS.md changed the result #
Agents read AGENTS.md before they start work. With one pointer there, they ran mint instructions before the first edit in 30 of 30 tests.
The wording of the pointer mattered too. A generic "run mint instructions before Mintlify tasks" produced a 66% pass rate. Agents treated "set up an automation" as a GitHub Actions job, so they never checked.
Naming the relevant tasks (automations and CI, access and publishing, AI features) raised the pass rate to 83%. Revising the guidance around what agents missed raised it to 100%.
Task-specific guidance beat a link to the docs #
The obvious alternative to a new command is to point agents at the docs. Ours are thorough, available as Markdown, and indexed in llms.txt, which our earlier benchmark found eliminates most agent 404s. So we tested the two head to head, with the same AGENTS.md wording pointing to each:
| Model | No guidance | Pointer to the docs | Pointer to mint instructions |
|---|---|---|---|
| Claude Sonnet | 20% | 57% | 100% |
| Claude Opus | 28% | 72% | 94% |
| Claude Haiku | 6% | 28% | 89% |
| Codex | 36% | 81% | 89% |
The docs pointer helped. The CLI pointer helped more on every model, by the widest margins on Haiku and Sonnet. On Codex, the 8-point gap is small enough to be noise.
A topic like mint instructions access gives the agent steps for one job in one place, so it doesn't have to stitch pages together.
Agents also skim for the next action, so we put the facts they most often missed in overview, the first topic in the list, marked "Start here". Haiku went from 39% to 89% after that rewrite.
What shipped #
mint instructions is a new command in the Mintlify CLI. It prints step-by-step guidance for common tasks, by topic.
mint instructionslists 10 topics and 10 subtopics, each with one line on when to use it.mint instructions <topic>prints the guidance for one task, for examplemint instructions publish domain.- Each topic is a page in our docs. When we update a page, every agent that runs the command gets the new version. No CLI release, no reinstall.
With the command, agents made 0.02 false claims about Mintlify per run, down from 0.69 without it.
Agents can find it from every docs page's Markdown, llms.txt, skill.md, and mint --help. The starter repo's root AGENTS.md now includes the pointer too.
Try it in your repo #
Run mint instructions in your Mintlify project. If that doesn't work, runnpx mint@latest instructions .
2.
Copy this into the top of your repo's root AGENTS.md . It tells agents when to check the guidance:
Before any Mintlify task, run `mint instructions` to get current guidance. Always check it before you:
- build automations, CI, or scripts for these docs (Mintlify has built-in automations, Autopilot, and CI checks)
- change who can read the docs, publishing, custom domains, or AI features (MCP, llms.txt, skill.md, assistant)
If `mint` isn't installed, run `npx mint@latest instructions`.
Give your agent a task. It checks the guidance and opens the topic it needs.
Every topic is listed in the CLI command reference.
New to Mintlify? Sign up and let your agent take it from there.
More blog posts to read
We built one page to help AI agents set up Mintlify
We watched agents struggle through Mintlify setup, fetching multiple pages, trying wrong commands, and sending long instructions. So we built setup.md, one starting point for getting connected.
November 10, 2026 Denzell Ford
Engineering
Migrate to Mintlify with your agent
We turned what we learned from hundreds of migrations into mint migrate, so your agent can move your docs from 21 platforms, prove nothing went missing, and tell you what didn't carry over.
November 3, 2026 Sophia Barnes
Solutions Engineering