{"slug": "we-gave-agents-better-instructions", "title": "We gave agents better instructions", "summary": "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.", "body_md": "Harkirat Chahal\n\nGrowth\n\n#### Share this article\n\nHarkirat Chahal\n\nGrowth\n\n#### Share this article\n\nWe built `mint instructions` to give coding agents current, task-specific guidance for Mintlify. Then we tested it.\n\nIn 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.\n\nAfter 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%.\n\n## [The command failed because agents never ran it](#the-command-failed-because-agents-never-ran-it)\n\nPeople 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?\n\nOur 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.\n\nSonnet got everything right in 16% of runs with the command and 20% without it. That's noise.\n\n## [One line in AGENTS.md changed the result](#one-line-in-agents-md-changed-the-result)\n\nAgents read `AGENTS.md` before they start work. With one pointer there, they ran `mint instructions` before the first edit in 30 of 30 tests.\n\nThe 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.\n\nNaming 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%.\n\n## [Task-specific guidance beat a link to the docs](#task-specific-guidance-beat-a-link-to-the-docs)\n\nThe 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:\n\n| Model | No guidance | Pointer to the docs | Pointer to `mint instructions` | \n|---|---|---|---|\n| Claude Sonnet | 20% | 57% | **100%** | \n| Claude Opus | 28% | 72% | **94%** | \n| Claude Haiku | 6% | 28% | **89%** | \n| Codex | 36% | 81% | **89%** | \n\nThe 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.\n\nA topic like `mint instructions access` gives the agent steps for one job in one place, so it doesn't have to stitch pages together.\n\nAgents 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.\n\n## [What shipped](#what-shipped)\n\n`mint instructions` is a new command in the Mintlify CLI. It prints step-by-step guidance for common tasks, by topic.\n\n- `mint instructions` lists 10 topics and 10 subtopics, each with one line on when to use it.\n- `mint instructions <topic>` prints the guidance for one task, for example`mint instructions publish domain` .\n- 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.\n\nWith the command, agents made 0.02 false claims about Mintlify per run, down from 0.69 without it.\n\nAgents 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.\n\n## [Try it in your repo](#try-it-in-your-repo)\n\n1. \nRun `mint instructions` in your Mintlify project. If that doesn't work, run`npx mint@latest instructions` .\n2. \nCopy this into the top of your repo's root `AGENTS.md` . It tells agents when to check the guidance:\n\n```\nBefore any Mintlify task, run `mint instructions` to get current guidance. Always check it before you:\n- build automations, CI, or scripts for these docs (Mintlify has built-in automations, Autopilot, and CI checks)\n- change who can read the docs, publishing, custom domains, or AI features (MCP, llms.txt, skill.md, assistant)\nIf `mint` isn't installed, run `npx mint@latest instructions`.\n```\n\n3. \nGive your agent a task. It checks the guidance and opens the topic it needs.\n\nEvery topic is listed in the [CLI command reference](https://www.mintlify.com/docs/cli/commands#mint-instructions).\n\nNew to Mintlify? [Sign up](https://app.mintlify.com/signup) and let your agent take it from there.\n\n#### More blog posts to read\n\n[EngineeringDF](https://www.mintlify.com/blog/setup-md)\n\n### We built one page to help AI agents set up Mintlify\n\nWe 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.\n\nNovember 10, 2026\nDenzell Ford\n\nEngineering\n\n[AnnouncementsSB](https://www.mintlify.com/blog/mint-migrate)\n\n### Migrate to Mintlify with your agent\n\nWe 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.\n\nNovember 3, 2026\nSophia Barnes\n\nSolutions Engineering", "url": "https://wpnews.pro/news/we-gave-agents-better-instructions", "canonical_source": "https://www.mintlify.com/blog/mint-instructions", "published_at": "2026-11-10 00:00:00+00:00", "updated_at": "2026-11-10 17:50:41.054135+00:00", "lang": "en", "topics": ["ai-agents", "ai-tools", "agent-protocols", "developer-tools", "ai-search"], "entities": ["Mintlify", "Harkirat Chahal", "Claude Sonnet", "Claude Opus", "Claude Haiku", "Codex", "mint instructions"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/we-gave-agents-better-instructions", "markdown": "https://wpnews.pro/news/we-gave-agents-better-instructions.md", "text": "https://wpnews.pro/news/we-gave-agents-better-instructions.txt", "jsonld": "https://wpnews.pro/news/we-gave-agents-better-instructions.jsonld"}}