We gave agents better instructions

Mintlify's new `mint instructions` CLI command raised Claude Sonnet's pass rate on Mintlify coding tasks from 20% to 100% after the company added a single pointer to the repository's root `AGENTS.md`, according to a benchmark published by Mintlify growth team member Harkirat Chahal. Without the `AGENTS.md` pointer, Sonnet passed 16% of runs with the command available versus 20% without it, because agents never ran the command; with the pointer, agents ran `mint instructions` before the first edit in 30 of 30 tests. The command prints task-specific guidance across 10 topics and 10 subtopics, and with it agents made 0.02 false claims about Mintlify per run, down from 0.69 without it.

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 the-command-failed-because-agents-never-ran-it People rarely reinstall plugins, so skills https://www.mintlify.com/docs/customize/agent-skill 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 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 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 https://www.mintlify.com/docs/ai/markdown-export , and indexed in llms.txt https://www.mintlify.com/docs/ai/llmstxt , which our earlier benchmark https://www.mintlify.com/blog/llms-txt-agent-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 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 https://github.com/mintlify/starter 's root AGENTS.md now includes the pointer too. Try it in your repo 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 https://www.mintlify.com/docs/cli/commands mint-instructions . New to Mintlify? Sign up https://app.mintlify.com/signup and let your agent take it from there. More blog posts to read EngineeringDF https://www.mintlify.com/blog/setup-md 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 AnnouncementsSB https://www.mintlify.com/blog/mint-migrate 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