We gave agents better instructions

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 instructions lists 10 topics and 10 subtopics, each with one line on when to use it.
• mint instructions <topic> prints the guidance for one task, for example mint 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

1. Run mint instructions in your Mintlify project. If that doesn't work, run npx 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`.
   

3. 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.