The pattern
If you sell or share something that other people build on, such as a SaaS product with an API, a website template, a theme, a starter repo or a plugin, a growing share of your users now hand the build work to a coding agent like Claude Code, Cursor or Codex. That agent has never read your docs. It opens the repo, guesses from what it sees, and starts editing. When it guesses wrong, your customer blames your product.
Mintlify, which sells documentation sites, ran into this and wrote up what fixed it on its engineering blog on 10 Nov 2026. The pattern has two parts. First, a command (theirs is mint instructions) that prints current, step-by-step guidance for one task at a time. Second, a short pointer at the top of the repo's AGENTS.md, the plain Markdown file that many coding agents read before they work in a project. The pointer tells the agent to run the command before it touches anything, and names the kinds of task that should trigger it.
The command on its own did nothing. Mintlify listed it in the CLI's help text and Claude Sonnet passed 16% of test runs with it available versus 20% without, a gap Mintlify calls noise. Agents simply never asked for help. Once a single pointer went into AGENTS.md, agents ran the command before their first edit in 30 of 30 tests.
When to use it and when not
Use it when people build on your work with agents and the right way to do a task is not obvious from the code. Good signs: your product has settings that live outside the repo (a dashboard, a hosted service, DNS), there are two plausible ways to do a job and only one works with your product, or your support inbox keeps getting the same "the AI did it wrong" tickets. It also helps on your own projects you return to every few months.
Skip it when the guidance would fit in five lines of AGENTS.md anyway, or when nobody uses agents on your product yet. A stale command is worse than none, because the agent will trust it.
How it works
Input: a user asks their agent to do something in a repo built on your product, for example "add a custom domain".
Steps: the agent reads AGENTS.md, where the pointer says to run the instructions command before any domain, publishing, access or automation task. It runs the command, sees a list of topics with a note on when each applies, then prints the one it needs: steps, traps and how to verify. Then it edits.
Output: a change made against your current guidance, rather than against whatever the model remembers about your product from training.
One detail makes the guidance easy to keep fresh. In Mintlify's version, each topic maps to a live docs page, so when the docs change, agents get the new version without anyone reinstalling or upgrading the CLI.
Components
The pointer. Two to five lines at the very top of AGENTS.md. It names the command and lists the task types that should trigger it, in the words a user would type.
The index. Every topic with one sentence on when to use it. Mintlify's lists 10 topics and 10 subtopics.
The topics. One page per task. Each page opens with the mistakes agents actually make, then the steps, then how to check the work.
A "start here" topic. The facts agents most often miss, put first. When Mintlify moved commonly missed facts into its first topic, Claude Haiku's pass rate went from 39% to 89%.
The wording of the pointer turned out to matter as much as its existence. With a generic line, Mintlify's pass rate was 66%. Naming the specific task areas lifted it to 83%. Revising the guidance around the mistakes agents were observed making took it to 100%. One mistake shaped the wording: agents read "set up an automation" as "write a GitHub Actions job", decided it had nothing to do with Mintlify, and never checked the guidance. So the pointer now names automations and CI explicitly.
The gain held across models. Comparing no guidance, a pointer to the docs website, and a pointer to the instructions command, Mintlify reports pass rates of 6%, 28% and 89% for Claude Haiku, and 28%, 72% and 94% for Claude Opus. The cheapest model went from almost always failing to almost always passing, which matters if your users run cheap models. False claims about Mintlify's product per run, such as describing a feature that does not exist, fell from 0.69 to 0.02. These are Mintlify's own tests on its own tasks, and the post does not say how many runs sit behind each percentage, so treat them as a strong signal rather than a guarantee for your product.
Minimal implementation
Here is a version you can adapt in an afternoon. Replace "acme" with your product name.
1. The AGENTS.md pointer (top of the file in your template or starter repo):
# Agent guidance
Before any Acme task, run `npx acme instructions` and read the topic that matches.
Run it for: custom domains, publishing or deploys, login and access,
webhooks and automations (including CI jobs), billing or plan limits.
If the command is unavailable, read https://docs.acme.dev/agent/index.md
Claude Code is the exception to watch. Its documentation says plainly that Claude Code reads CLAUDE.md, not AGENTS.md. Add a CLAUDE.md containing the single line @AGENTS.md, which imports the file at session start, so both groups of agents see the same pointer.
2. A tiny instructions script. It fetches Markdown pages from your docs site, so you update guidance by editing docs:
#!/usr/bin/env sh
# instructions: print agent guidance for one task
BASE="https://docs.acme.dev/agent"
if [ -z "$1" ]; then
curl -fsSL "$BASE/index.md"
exit 0
fi
curl -fsSL "$BASE/$1.md" || {
echo "Unknown topic: $1. Available topics:"
curl -fsSL "$BASE/index.md"
exit 1
}
Add it as a subcommand of your CLI or ship it as scripts/instructions. With no CLI, the fallback URL does the same job.
3. A topic written around agent mistakes. Lead with what goes wrong, because that is what the agent needs before it acts:
# Topic: custom-domain
Use when: the user mentions a domain, DNS, SSL or "go live on my URL".
Common mistakes (read first)
- Do not edit vercel.json or netlify.toml. Domains are set in the Acme dashboard.
- Do not invent a CNAME target. Get it from `acme domains show`.
- SSL can take up to 30 minutes. Do not retry or delete the record before then.
Steps
1. Run `acme domains add example.org`.
2. Show the user the DNS record it prints and ask them to add it.
3. Run `acme domains verify` and report the result word for word.
Done when: `acme domains verify` prints "verified".
Write each topic from your support tickets. Every "the agent did X" complaint becomes a line under common mistakes.
Failure modes and evals
Four failures are likely: the pointer's wording does not match how users phrase the task, so the agent never runs the command; topic descriptions overlap, so it picks the wrong one; guidance goes stale; or the pointer is buried under 200 lines of other AGENTS.md content.
You can test for all of these with 10 agent runs per task. Pick three real tasks your users ask for, each with a clear pass check (the site builds, the domain record is correct, no files outside the expected folder changed). For each task, run your agent five times on a fresh copy of the repo without the pointer and five times with it. Log three things per run: did it run the command before its first edit, did it pass, and did it say anything false about your product. If the "ran the command" column is not close to 10 out of 10 with the pointer, fix the wording before you touch the guidance. If it ran the command but still failed, read the transcript, find the mistake, and add it to that topic's list. We covered how to keep that loop honest with a held-out task set in tune prompts with a held-out test set. Five runs per arm is a small sample, so look for large gaps, the kind Mintlify saw, rather than a few points either way.
The pointer asks the agent to follow a step. It cannot force it. For steps that must never be skipped, such as running a migration check before deploy, put the check in code, as in order in code, judgment in prompt.
Build it this weekend
Open your last 20 support messages and list every task where an agent or a confused user went wrong. Group them into five to eight topics.
Write one Markdown page per topic: "use when", "common mistakes", "steps", "done when". Publish them under a single docs folder, plus an index page.
Add the instructions script, or just the fallback URL, and the four-line pointer to AGENTS.md in your template or starter repo. Add a CLAUDE.md that imports it.
Run the 10-run test on your three most common tasks and write down the before and after pass rates.
Ship the updated template and say in your changelog that it now works better with coding agents.
Your decision rule: if the pointer lifts the pass rate on any task by more than two runs out of five, keep it and extend it to more topics. If it does not, rewrite the pointer using your users' own words before you write any more guidance.

