Skip to main content
The previous lesson covered agents that read your published docs on a user’s behalf. This lesson covers agents that help your team write them. Mintlify’s agent, the editor’s agent, and coding tools like Claude Code and Cursor can all draft and edit pages. Without guidance, they write for a generic reader, pick whichever term they saw last, and mix content types. An instruction file gives them the context your pages don’t contain: who you write for and how your team works.

​
What to include

A useful instruction file for a documentation project covers four things. Audience. Who your readers are and what they already know, so the tool pitches content at the right level. The Understand your readers first lesson covers how to write a reader definition. Terminology. The canonical name for each concept, and the variants to avoid. This is the most effective way to stop terminology drift. Content types. What each kind of page should and shouldn’t do, so a how-to guide doesn’t turn into an essay. What not to do. The mistakes your team keeps correcting, like “don’t add introductory paragraphs that restate the title.”
.mintlify/AGENTS.md
Keep instructions short and specific. Tools follow them on every request, so vague or contradictory rules make results worse, not better.

​
Put instructions where each tool looks

Each tool reads its own file, and none of them read each other’s. Write the instructions once, then copy them to each place your team needs.
Mintlify publishes Markdown files in your project, so a root AGENTS.md is readable by anyone at /agents.md. Keep Mintlify’s copy in .mintlify/AGENTS.md, which is never published. If your coding tools need a root AGENTS.md, add it to your .mintignore file so it stays private.

​
Keep instructions current

Instruction files go stale like any other content. When your team renames a feature, add the new term and the old one to avoid. When you notice yourself correcting the same mistake in several drafts, add a rule for it. Review the files when you review your style guide, and remove rules that no longer apply. Next up: Test whether agents can use your content—build a repeatable question set and catch regressions.