Writing for Agents — A Writing Guide for Agent Documentation

Skill Overview

Writing for Agents is a documentation-writing methodology for AI agents. It is used to write skills, AGENTS.md files, CLAUDE.md files, and any documents read by agents through pointers. Its core premise is that an agent follows the same process each time it runs, rather than producing the same result, so the goal of writing is to make that process predictable: triggers should fire reliably where they should, and tasks that should be completed should actually be completed.

Applicable Scenarios

1. Writing or modifying a skill: When you need to write SKILL.md, design a description, or decide which content to keep inline and which to move into separate files, this methodology provides the criteria. The frontmatter, invocation-method choices, and routing skills for skill documentation are covered separately in SKILL-MECHANICS.md.

2. Maintaining persistent documents such as AGENTS.md / CLAUDE.md: Every line in these files consumes context in every round of conversation. When a document grows longer over time and starts accumulating outdated content, this skill provides methods for trimming and layering it.

3. Execution results are inconsistent and the problem needs to be fixed at the documentation level: Typical symptoms include skill instructions being written but rarely triggered, steps being abandoned before completion, or the same document taking completely different paths on two runs. These are wording problems in the documentation, not model problems.

Core Functions

1. Context pointer design: A pointer is a reference in the agent’s context that points to external material and encodes the conditions for when to retrieve it—a skill’s description and a line in AGENTS.md pointing to a document are the same kind of object. This skill explains how to make a pointer do two things at once: describe what the material is and list the branches that should trigger it. It also provides pruning rules for pointers: put core terms first, use one trigger term per branch, and remove identity information already carried by the body text. When essential material is paired with a weakly worded pointer, that is a variance defect: fix the wording first, and inline the material only if the wording cannot be fixed.

2. Information hierarchy and progressive disclosure: Documents consist of steps (actions the agent performs in sequence) and references (definitions, rules, and facts consulted as needed). This skill provides a ladder for placing them: steps inline in the file, references inline in the file, and external references disclosed through pointers. The criterion is branching: inline anything every branch needs; move behind a pointer anything only some branches will read. The accompanying co-location principle requires the definition, rules, and caveats for a concept to appear under the same heading, preventing the same meaning from being scattered across multiple places. Sprawl is the failure mode here: a document becomes simply too long even though every line remains valid.

3. Steps, completion criteria, and pruning: Every step ends with a completion criterion—the condition that determines whether the work is complete. It works through two properties: clarity (whether the agent can distinguish done from not done; vague boundaries invite premature completion) and requirement strength (“every changed model must be accounted for” demands more legwork than “produce a list of changes”). When a criterion is naturally ambiguous and corner-cutting has genuinely been observed, later steps can be split out—but splitting is effective only at a real context boundary. The pruning section provides actionable reduction criteria: maintain a single source of truth, treat the environment itself as a source of truth, and inspect each sentence for uselessness (instructions the model would follow by default; delete the entire sentence rather than trimming individual words).

Common Questions

What is a context pointer? How is it different from an ordinary reference?

A context pointer is a reference in the agent’s context that names material not present in the context and encodes the conditions for retrieving it. A skill’s description and a line in AGENTS.md pointing to a document are the same kind of object. The key difference is that the pointer’s wording, not the target it points to, determines when the agent reads the material and how reliably it does so. If the pointer is vague, even critically important material may not be read.

How do I decide whether to keep content inline or move it to a separate file?

Use branches as the dividing line: keep inline anything every branch must read; move behind a pointer anything only some branches will read. This is progressive disclosure. Its main purpose is not to save tokens, but to protect hierarchy—too much inline reference material can bury the steps and turn whether the agent notices them into a coin flip. The opposite risk matters too: pushing content out too aggressively can hide material the agent genuinely needs. This tension is the entire basis for the decision.

What are lead terms? Can they be used in Chinese documentation?

A lead term is a compact concept already present in the model’s pretraining (for example, “curriculum,” “fog of war,” or “tracer bullet”) that the agent uses to think while executing a document. It recurs as a token rather than as a sentence, thereby accumulating a distributed definition. It works in two places: anchoring execution behavior in the body text and helping with invocation in pointers. When the same term appears in your prompt, documentation, and codebase, the agent is more likely to associate the material with it. Coined terms can work too, but they cannot activate pretrained priors; you will spend tokens defining them that should have been free. Therefore, prefer existing terms.

Why should documentation use fewer “do not do X” statements?

Negation is a failure mode: using prohibitions as guidance brings the prohibited behavior into the context as well, making it more likely to come to mind. Negation is a weak modifier that can be overridden by a strongly activated concept, so a prohibition can read halfway like an instruction to perform the action. The correct approach is to state the positive goal (for example, write “write a single-line comment”), so the prohibited behavior is never mentioned. Keep a prohibition only when it cannot be expressed positively and serves as a hard guardrail—and even then, pair it with a positive goal so attention remains on what should be done.

When should a skill be split into two documents?

Split only when the split itself recovers its cost, because every split imposes one of two kinds of overhead. Split by sequence when the existence of later steps tempts the agent to rush through the current step; moving later steps out of view can force more legwork. Be careful in the opposite direction as well—merging two sequences exposes the subsequent steps of each step to the agent, which can instead invite premature completion. Splitting by invocation method is a skill-specific case; see SKILL-MECHANICS.md.

How do I decide which sentences should be deleted as useless?

Apply the same test sentence by sentence: compared with the model’s default behavior, what does this sentence change? If it changes nothing, it is useless. This test is relative to the model, not the reader—when two people disagree about whether a sentence is useless, they are actually disagreeing about the default behavior, which should be validated by running the document rather than debating it. When a sentence fails the test, delete the entire sentence instead of picking out a few words. The same test applies when evaluating the strength of lead terms: a term too weak to overcome default behavior (for example, writing “be thorough” when the agent is already reasonably thorough) is useless. The solution is to replace it with a stronger term, not to try a different technique.