---
name: writing-agent-facing-docs
description: Writes and maintains the instruction files agents read — AGENTS.md, CLAUDE.md, cursor rules, Copilot instructions and skills — so they trigger reliably, cost little, and do not rot. Use when creating or editing any agent instruction file, when setting up a repo for AI coding agents, when a skill is not triggering, when instruction files contradict each other, or when the user mentions AGENTS.md, CLAUDE.md, SKILL.md, agent context or AI onboarding. Applies before adding any new instruction file to a repository.
license: CC0-1.0
---

# Writing agent-facing docs

Most instruction files fail in one of three ways: they never trigger, they
cost more than they return, or they describe a system that has since changed.
Each has a different fix.

## Put the right thing in the right tier

Cost is driven by how often a file loads, not by how much it contains.

| Tier | Where | Cost |
|---|---|---|
| Always on | `AGENTS.md`, `CLAUDE.md`, always-apply rules | Billed on every turn, forever |
| On demand | `SKILL.md`, path-scoped rules, glob-attached rules | Only when relevant |
| Live | An MCP tool call | Bounded, and cannot go stale |
| Handed over | `llms.txt`, `DESIGN.md` | Nothing fetches these on its own |

If a rule only matters in one part of the repo, it is a path-scoped rule. If
it is reference material or a multi-step procedure, it is a skill. IBM Carbon
opens its own AGENTS.md with a note to itself — "This file should be as short
as possible. More tokens used." — and routes everything substantial elsewhere.

## Make the description do the work

For a skill, the description is the entire basis on which it is selected from
among a hundred others. Nothing else is in context at that moment.

- **Third person.** Not "I can help you audit tokens". Not "You can use this
  to audit tokens". Write "Audits design tokens…". Point of view
  inconsistency measurably hurts discovery.
- **What and when.** Both. A description that only says what it does will not
  fire.
- **Name the triggers.** Include the words a person would actually type, and
  the file types and tools involved.
- **Be slightly pushy.** Models under-trigger skills more often than they
  over-trigger them.
- **No angle brackets, anywhere in frontmatter.** They can inject unintended
  instructions into the system prompt. Use `{{BRACES}}` for placeholders.

## Rules that can be checked beat rules that sound right

"Follow our conventions" is unenforceable. "There is no `Box` component in
this system" is checkable by reading the diff, and a model can pattern-match
against it. Name the specific mistake.

Every rule should carry its reason. A rule an agent understands the reason for
generalises to cases you did not enumerate; a bare prohibition does not.

## Know how your files compose

`AGENTS.md` is nearest-file-wins: the closest one to the edited file
overrides. `CLAUDE.md` files are concatenated — all of them — and where two
contradict, the model may pick either. A monorepo built on package-level
overrides works under one and silently does not under the other. Renaming the
file does not bring the semantics along.

Claude Code does not read `AGENTS.md`. Bridge it with a bare `@AGENTS.md`
import on the first line of `CLAUDE.md` — a markdown link is inert text and
will not expand.

## Generate, do not maintain

Hand-written agent docs rot, and a rotted file is not neutral: it is an
instruction to use an API that no longer exists. The systems that solved this
generate their agent-facing docs from source.

The minimum viable version is a CI check asserting that every symbol named in
your agent files is actually exported by the package. Meta's Astryx shipped a
README naming an export the package did not have; the agents used it and
produced a build failure. That check would have caught it.

## Verification

1. Does the description state both what and when, in third person?
2. Is every rule checkable by reading the output?
3. Is anything in the always-on tier that could move down a tier?
4. Does every symbol named here still exist? Prove it in CI, not by reading.