When the document is a Claude Code skill, read SKILL-MECHANICS.md. It covers frontmatter, the invocation choice, the skill listing, and router skills. For another harness, check its own skill documentation before applying invocation fields or context budgets.
A pointer does two jobs. It states what the material is, and it lists the branches that should trigger reaching it. A branch is a distinct case the document handles, so different runs take different paths through it. Every word of an always-loaded pointer costs on every turn, so prune it even harder than the body.
- Front-load the leading word, because the pointer is where it does its triggering work.
- Write one trigger per branch. Synonyms that rename one branch are that branch written twice. Collapse them and keep only distinct branches.
- Keep what the material does and when to reach it, and cut everything else, because the body carries the rest.
Material reached only through a pointer stays out of context until the pointer fires, at the price of the pointer's own line. Material with no pointer at all rides entirely on cognitive load.
Push too little down and the top bloats. Push too much and you hide material the agent needs. That tension is the whole decision.
The strongest criteria are both checkable and exhaustive.
A leading word anchors twice. In the body it anchors execution. The agent reaches for the same behavior every time the word appears. Inside flat reference, the word focuses attention on a class of thing to look for. In a pointer it anchors invocation. The same word may live in your prompts, docs, and codebase. The agent then links that shared language to the material and reaches it more reliably.
Hunt for chances to refactor with leading words. Typical candidates are a triad spelled out at three sites, or a pointer that spends a sentence on one idea. Each such passage can collapse into a single token, as these two examples show.
- "Fast, deterministic, low-overhead" becomes "tight", as in a tight loop.
- "A loop you believe in" becomes "red". That turns a fuzzy gate into a binary observable state. The loop either goes red on the bug or it does not.
You win twice, with fewer tokens and a sharper hook for the agent's thinking. Assume every document carries restatements that leading words could retire, and go find them.
1---2name: agentdocs3description: Guides the writing and audit of documents that agents read. Use when creating, editing, or reviewing a skill, its description, or its reference files, and when writing or modifying AGENTS.md, CLAUDE.md, a rule file, or a doc that an agent reaches through a pointer.4metadata:5 source: https://skillmd.com/skills/dayfinggg/agentdocs6---78<overview>9This skill is a reference for writing any document an agent consumes. That covers a skill, an `AGENTS.md` or `CLAUDE.md`, and a doc reached by a pointer. The packaging differs, but the writing does not. The same levers make each one predictable. The agent then takes the same process every run, though its output may differ.1011When the document is a Claude Code skill, read [SKILL-MECHANICS.md](references/SKILL-MECHANICS.md). It covers frontmatter, the invocation choice, the skill listing, and router skills. For another harness, check its own skill documentation before applying invocation fields or context budgets.12</overview>1314<context_pointers>15A context pointer is a reference in the agent's context that names out-of-context material. It also encodes the condition for reaching it. A skill's description is one. A line in `AGENTS.md` that names a doc is the same object. The pointer's wording, not its target, decides when and how reliably the agent reaches the material. A must-have target behind a weakly worded pointer is a variance bug. Sharpen the wording first, and inline the material only if sharpening fails.1617A pointer does two jobs. It states what the material is, and it lists the branches that should trigger reaching it. A branch is a distinct case the document handles, so different runs take different paths through it. Every word of an always-loaded pointer costs on every turn, so prune it even harder than the body.18- Front-load the leading word, because the pointer is where it does its triggering work.19- Write one trigger per branch. Synonyms that rename one branch are that branch written twice. Collapse them and keep only distinct branches.20- Keep what the material does and when to reach it, and cut everything else, because the body carries the rest.21</context_pointers>2223<the_two_loads>24Every document and pointer you add spends one of two budgets.25- Context load is the cost of always-loaded material on the agent's window. It covers an `AGENTS.md` line, a skill description, and anything else in context every turn. It spends tokens and attention whether or not it fires.26- Cognitive load is the cost on the human, who must know which documents exist and when to reach for each. The human is the index. This cost is the price of human agency, not a cost to minimize. Spend it where human judgment matters, and remove it where it does not.2728Material reached only through a pointer stays out of context until the pointer fires, at the price of the pointer's own line. Material with no pointer at all rides entirely on cognitive load.29</the_two_loads>3031<information_hierarchy>32A document holds two content types. Steps are the ordered actions the agent performs. Reference is the definitions, rules, and facts consulted on demand. The two mix freely. A recipe is all steps, the rules of a review are all reference, and many documents hold both. Write steps only where their order matters, and state outcomes for the rest. The core decision is where each piece sits on the information hierarchy. This ladder ranks material by how soon the agent needs it.331. An in-file step is the primary tier, meaning what the agent does, in order.342. In-file reference is consulted on demand. It is often a flat peer set, such as every rule of a review on one rung. That arrangement is fine, not a smell.353. Disclosed reference sits in a separate file, behind a context pointer, and loads only when the pointer fires. It ranges from a sibling file in the same folder to external reference that any document can point at.3637Push too little down and the top bloats. Push too much and you hide material the agent needs. That tension is the whole decision.3839<progressive_disclosure>40Progressive disclosure moves material down the ladder, out of the main file and behind a pointer. The top then stays legible. It is mainly how the hierarchy stays protected, and only secondarily a token saving. Branching is the cleanest test. Inline what every branch needs, and put behind a pointer what only some branches reach. In a document with steps, reference that should be disclosed buries the steps. Attending to them then becomes a coin flip, so disclosure is a variance lever, not only a legibility one.41</progressive_disclosure>4243<co_location>44Co-location is the companion rule within a file. The ladder decides how far down a piece sits, and co-location decides what sits beside it. Keep a concept's definition, rules, and caveats together in one section. Reading one part then brings its neighbors along. The document should read like documentation written for the agent. Grouped material reads that way, and scattered material does not. Co-location differs from duplication. Duplication repeats one meaning in two places, while scattering splits one meaning across many.45</co_location>4647<sprawl>48Sprawl is the failure mode here. The document is simply too long, even when every line is live and unique. Attention thins across the excess, and every extra line is one more to keep relevant. The cure is the ladder. Disclose reference behind pointers, and split by branch or sequence so each path carries only what it needs.49</sprawl>50</information_hierarchy>5152<completion_criteria>53Every step ends on a completion criterion, the condition that tells the agent the step is done. Two properties make it a lever.5455<clarity>56Clarity asks whether the agent can tell done from not done. A vague bound such as "understanding reached" invites premature completion. The agent ends the step early, because its attention slips to being done. The visible steps still ahead, the post-completion steps, supply that pull, and a clear criterion resists it. Defend in order. Sharpen the bound first, because that is local and cheap. Hide the later steps by splitting the sequence only if the bound stays fuzzy and you observe the rush. Hiding works only across a real context boundary. Examples are a handoff, a subagent dispatch, or a skill with `context: fork`. An inline skill call leaves the later steps in context and clears nothing.57</clarity>5859<demand>60Demand is how much the criterion requires. "Every modified model accounted for" forces thorough work, where "produce a change list" does not. Demand drives legwork, the digging the agent does within the work. Legwork lives in the wording, not in a step of its own. Demand is not bound to steps either. "Every rule applied" binds a body of flat reference just as "every step done" binds a sequence. That is how an all-reference document still carries a bar for exhaustiveness.61</demand>6263The strongest criteria are both checkable and exhaustive.64</completion_criteria>6566<when_to_split>67Splitting one document into two spends one of the two loads, so split only when the cut earns it.68- Split by sequence where the post-completion steps tempt the agent to rush the current one. Keeping them out of view drives more legwork on the current task. The reverse also holds. Merging sequences exposes each step to the steps after it and invites premature completion.69- Split by invocation, which applies only to skills and is described in [SKILL-MECHANICS.md](references/SKILL-MECHANICS.md).70</when_to_split>7172<leading_words>73A leading word is a compact concept from the model's pretraining. The agent thinks with it while it runs the document. Examples are "lesson", "fog of war", and "tracer bullets". Repeat it as a token, never as a sentence. It then gathers a distributed definition and anchors a whole region of behavior in few tokens. It works because it recruits priors the model already holds. Coining your own word works if you define it clearly. A made-up word recruits no priors, though, so you pay in definition tokens what a pretrained word gives free. Reach for an existing word first.7475A leading word anchors twice. In the body it anchors execution. The agent reaches for the same behavior every time the word appears. Inside flat reference, the word focuses attention on a class of thing to look for. In a pointer it anchors invocation. The same word may live in your prompts, docs, and codebase. The agent then links that shared language to the material and reaches it more reliably.7677Hunt for chances to refactor with leading words. Typical candidates are a triad spelled out at three sites, or a pointer that spends a sentence on one idea. Each such passage can collapse into a single token, as these two examples show.78- "Fast, deterministic, low-overhead" becomes "tight", as in a tight loop.79- "A loop you believe in" becomes "red". That turns a fuzzy gate into a binary observable state. The loop either goes red on the bug or it does not.8081You win twice, with fewer tokens and a sharper hook for the agent's thinking. Assume every document carries restatements that leading words could retire, and go find them.8283<negation>84A prohibition alone leaves the agent without a target. State the behavior you want first, as in "write one-line comments," and add a prohibition where a guardrail needs one. Give the prohibition its scope and its reason, so the agent applies it where it belongs and not everywhere. Current models follow a ban closely, so a ban without a scope spreads to cases it was never meant for.85</negation>86</leading_words>8788<conflicts_and_exceptions>89Two rules that pull against each other cost more than a missing rule, because the agent must weigh them on every run and one of them loses. Before you add a rule, search the documents the agent loads for a rule that pulls the other way, and reconcile the two in one place.90- Write an exception inside the rule it limits. A separate line that grants the exception changes little.91- Give a rule that orders work a condition tied to the size or risk of the task. An unconditional order runs on every task, however small.92- Write the document in the style you want back, because the layout of a prompt carries into the output.93- Word a reminder that a hook adds as a statement of fact. Text framed as a command from outside the conversation can be read as an injection.94</conflicts_and_exceptions>9596<pruning>97Five habits keep a document lean.98- Fix a recurring review complaint at its source. When reviews keep flagging the same problem, add the rule once to `CLAUDE.md`, `AGENTS.md`, a lint rule, or the skill that caused it. Later runs then avoid the problem instead of collecting the same comment.99- Keep each meaning in a single source of truth, so changing a behavior is a one-place edit. Duplication costs maintenance and tokens. It also lifts a meaning's prominence on the ladder past its real rank. Duplication is the accidental inverse of a leading word, which repeats a token on purpose, never the meaning.100- Treat the environment as a source of truth too. That covers `package.json` scripts, config files, the directory layout, and `--help` output. A document that restates it is a cache, meaning a copy of a lookup. A cache earns its load only when the lookup is expensive. Cache what the agent cannot find by looking. Examples are an unwritten convention, the reason behind a choice, or a gotcha no config reveals. Leave one-file and one-command lookups to the environment, where they cannot go stale.101- Check every line for relevance to what the document does. A line loses relevance when it never bears on the task. Mere exposition and a branch that belongs behind a pointer are such lines. It also loses relevance when the behavior or world it describes changes. Without a pruning habit, stale layers settle as sediment, because adding feels safe and removing feels risky.102- Hunt no-ops sentence by sentence. A no-op is an instruction the model already obeys by default, so it pays load to say nothing. The test asks whether the sentence changes behavior against the default. That test is relative to the model, not the reader. So settle a dispute by running the document, not by debate. When a sentence fails, delete the whole sentence rather than trim its words.103</pruning>104105<emphasis>106Current models follow instructions closely, so emphasis overcorrects. Capitals, "CRITICAL", "MUST", and pressure such as "be thorough, do not be lazy" make a model over-trigger and act rigidly. A hedge such as "try to" on a real requirement reads as permission to skip it. State each rule once at normal volume, with its reason beside it. A word too weak to beat the default is a no-op, so delete it. An example is "be thorough" for an agent that is already thorough. Choose a stronger word, such as "relentless", only when a run shows the default falls short. Trigger text in a description is the one place where calibrated urgency can help, because skills tend to under-trigger.107</emphasis>