When an agent skill grows into a large manual, split detailed material into focused references and tell the agent exactly when to read each one. Keep the rules that apply to every run in SKILL.md. Then check that the relevant requirements appear in the work, rather than assuming that a linked file was read and followed.
For a business team, the aim is to preserve a repeatable procedure without making every task carry every exception the organization has ever encountered. A report-review skill may need detailed guidance on numerical claims for one draft and incident-status language for another. Loading everything can add clutter; loading too little can omit the rule that matters.
Our editorial recommendation is to make reference selection an explicit step with observable completion criteria. This article develops that approach through a fictional service-report skill. It does not report an installed skill, product trial or measured improvement.
What the format supports
The Agent Skills specification describes a skill directory with a required SKILL.md and optional supporting resources, including references/. Its progressive-disclosure model separates discovery metadata, the activated skill’s instructions and resources loaded when needed. It recommends focused reference files and relative paths from the skill root, avoiding deeply nested reference chains.
That is a format and organization pattern, not proof that a particular assistant will select the right reference. A skill author still has to describe what each resource is for, and the target product must provide the necessary access and supported behavior.
Claude Code’s supporting-file documentation explicitly recommends linking files from SKILL.md so Claude knows their contents and when to load them. This is documented Claude Code behavior, not a claim that every product implements all Claude Code features or that this article’s example has been exercised there.
Research cautions against equating coverage with completion
In When and How Context Rot Appears in Coding Agents, Yue Xue examines structured code-audit skills under different working-context conditions. The inspected preprint revision is dated August 1, 2026. It reports cases where a small number of omitted obligations invalidate an otherwise largely complete artifact, and compares a detailed external checklist with a generic request to self-check.
The study is deliberately narrow: its strongest repeated evidence concerns one main task, model and scaffold, with small samples and substantial infrastructure missingness. A nearby task remains stable under the tested long contexts. Character counts are not token-equivalent controls, and the study does not establish a universal context threshold.
It also does not validate the service-report procedure proposed here. The useful distinction is between an agent receiving material and producing work that satisfies it. A reference-loading plan needs an output check, not just evidence that a read operation occurred.
Separate permanent rules from conditional detail
Consider a fictional service-report-review skill used to review internal operational reports before a manager shares them. Its recurring obligations are to distinguish supplied facts from assumptions, avoid inventing results, identify unresolved checks and return a concise review. Those obligations belong in the main instructions because every run needs them.
Detailed metric definitions can live in references/metrics.md. Guidance for incident causes and resolution states can live in references/incidents.md. Wording examples can live in references/style.md. These are proposed filenames and responsibilities, not files shipped with this website.
Do not hide an always-required confidentiality or authorization rule in a reference that is loaded only for an unusual case. The same applies to a required final check. If it governs every task, a conditional branch should not determine whether the agent encounters it.
Keep current task data separate from reusable procedure. A past report, a temporary exception or a one-off manager instruction should not quietly become the permanent rule for future reports. The skill can explain where to obtain approved task evidence without embedding private working records in a shared package.
Replace a file list with reading conditions
“Consult the relevant references” leaves relevance undefined. For the fictional skill, an illustrative excerpt from the body of SKILL.md could instead say:
Before review, classify the draft:
- Numeric claims: read references/metrics.md.
- Incident cause or status: read references/incidents.md.
- Wording changes: read references/style.md.
If several apply, read every relevant reference.
If a needed file is unavailable, mark that review incomplete.This is a design sketch, not a complete installable skill or a tested prompt. A real package needs its own validated instructions and reference contents.
The conditions should describe the task features a reviewer can recognize. “Read metrics for complex work” is weaker than a concrete trigger because different people may disagree about complexity. A draft that includes a percentage is easy to identify; the metric reference can then define which evidence that percentage requires.
Allow combined routes. A report may include both an outage-resolution claim and a recovery-rate calculation. The agent should not choose just one file because the first matching condition appears earlier in the list.
If classification is uncertain, inspect the relevant part of the draft or ask for the missing task information. Do not use a guess about the document’s subject as a reason to skip a potentially mandatory check.
Test the branches through their outputs
The following cases are proposed checks for the fictional skill. They have not been run against an assistant.
| Draft feature | Expected reference selection | Evidence to inspect in the review |
|---|---|---|
| Percentage with an unclear denominator | Metrics | The missing denominator is identified |
| Incident described as resolved with no supporting status | Incidents | Resolution remains unverified |
| Both numerical and incident claims | Metrics and incidents | Both kinds of requirement are addressed |
| Wording-only request on supplied factual text | Style | Wording changes preserve the supplied meaning |
| Required reference unavailable | Relevant check remains incomplete | The limitation is visible rather than silently skipped |
The expected outcomes must come from the actual reference contents. A filename cannot establish a review rule on its own. If metrics.md does not require a denominator check, changing the loading instruction will not repair that missing requirement.
Use observable traces where the product exposes them to investigate which files were read. Treat those traces as diagnostic evidence. The final report might list a reference without having applied it correctly, while a correct-looking answer could have been produced without consulting the intended rule.
Check both the route and the artifact. This helps distinguish an unclear trigger, an inaccessible file, a weak rule and an execution error. Each needs a different correction.
Keep enough context to make the decision
Anthropic’s September 2025 context-engineering article recommends retrieving relevant material as needed, while acknowledging that runtime exploration adds overhead and can fail without good guidance. This is vendor practitioner advice, not an independent performance estimate for a particular reference layout.
Moving text out of SKILL.md should not remove the information needed to select it. A short description of the reference’s purpose belongs alongside its path. Its detailed examples, definitions and uncommon cases belong in the reference itself.
Avoid a chain in which the main skill points to a general index, which points to another index, which finally points to the applicable rule. Direct links make dependencies easier to inspect and maintain. Where a reference is large, give it clear headings and specify the relevant section without turning that shortcut into permission to miss related requirements.
Do not reduce the design to a token-saving target. An extra read may be worthwhile if it brings a decisive rule into the working set. The useful outcome is a correct, reviewable task completed within an acceptable cost and time budget.
Close with checks tied to the chosen route
At completion, compare the artifact with the applicable obligations. For the fictional mixed report, that means checking the numerical claim and the incident-status claim separately. “Reviewed all references” is too vague to show either result.
A compact record can state which route applied, the reference revision used where available, the requirement checked and any unresolved evidence. It should not dump an entire internal manual into the final response or expose private source material to unauthorized recipients.
When a reference changes, rerun the cases that depend on it and include a nearby case that should remain unaffected. Our guide to comparing skill updates task by task covers evaluating that change. If the skill never activates, use the separate activation diagnostic before revising reference instructions.
Start with one overloaded skill. Mark what every run needs, give each remaining reference a concrete reading condition, and prepare one combined case plus one missing-file case. Inspect the resulting work against the actual requirements. That gives the team a practical way to improve a long skill without assuming that either a shorter file or a larger context window solves the problem.