Question-led guide · how-to
What belongs in SKILL.md, references, and scripts?
Divide an agent skill into a decision spine, conditional reference material, and deterministic helpers without hiding essential rules or dependencies.
Direct answer
Keep the task boundary, required decisions, prerequisites, and stopping rules in SKILL.md. Put specialized facts and variants in directly linked references with explicit read conditions. Put exact parsing, calculation, validation, and repeatable transformations in inspectable scripts. A shorter entry file is useful only if the agent can still discover every requirement needed for the selected task.
Preserve the decision spine
An entry file should tell the agent whether the task fits, what must be known before work begins, which path to take, and how to recognize completion or a safe stop. Those decisions form the spine of the skill. Removing them to make the file shorter creates a navigation problem: the agent needs the missing rule to know which reference to read.
The Agent Skills specification supports deferred resources. Use that mechanism to load relevant detail when needed, while leaving the routing conditions visible in the entry point.
Detail is conditional; invariants travel with every task
A schema for one export format is conditional. A rule that every output must identify missing input is an invariant. If the latter is buried in a format-specific reference, tasks using a different format may never encounter it.
Separate both from precise computation. Parsing a date format or checking required columns should usually have an explicit implementation. A helper’s output should tell the model what was accepted, rejected, or unavailable so subsequent prose cannot quietly reinterpret a failed check as success.
A vendor-onboarding packet grows to 900 lines
In a hypothetical procurement workflow, one skill drafts an onboarding packet for software vendors. Its original entry file includes general procedure, three jurisdiction-specific field lists, two document templates, and code for normalizing registration identifiers. Authors append every new exception to the same file until it reaches 900 lines.
The useful split follows work state. The entry point first identifies the vendor’s operating jurisdiction and required packet type. It then directs the agent to exactly the corresponding reference. Templates remain assets. Identifier normalization becomes a helper with fixtures for accepted and rejected strings. A missing jurisdiction is reported before the agent fills a packet using whichever reference happened to appear first.
Build a content placement ledger
This ledger is an author-designed review artifact. It is not a required extension to the open skill format.
| Component | Location | Load or execution condition | Verification |
|---|---|---|---|
| Supported packet types and missing-input stop | SKILL.md | Every activation | Task-boundary cases |
| Jurisdiction selection rule | SKILL.md | Before field selection | Ambiguous-input case |
| Jurisdiction-specific field definitions | references/ | After jurisdiction is established | Required-field fixture |
| Blank packet layout | assets/ | When rendering that packet type | Rendered output review |
| Identifier normalizer | scripts/ | Before placing identifiers in output | Valid and invalid input tests |
| Accepted-result checklist | SKILL.md | Before reporting completion | Output and missing-data checks |
Add ownership and an expiry or review trigger to references whose facts can change. A stale local reference is still stale even if the model read it exactly as instructed.
Give references an explicit entrance and exit
Link from the entry file using the question the reference resolves. “For a renewal packet, read the renewal fields before drafting” is easier to test than “more information is available in references.” Keep the path shallow enough that a reviewer can enumerate the required material for one task.
After reading the reference, the agent should return to a named decision or validation step. Otherwise a detailed reference can become an accidental second procedure that bypasses the entry file’s completion rules. Check contradictory guidance during author review instead of expecting the model to reconcile it reliably.
Make helper failures visible at the interface
Define inputs, outputs, exit behavior, resource limits, and side effects for each helper. For the onboarding example, an unsupported identifier format should produce a structured rejection and preserve the original field for review. It should not guess a corrected value.
Anthropic’s engineering description explains the complementary role of executable helpers. The reliability claim still belongs to the actual implementation, dependencies, and tests. Packaging a script does not prove that it is correct.
Measure navigation, not just file length
Run one task for each conditional branch and inspect which files were read and which helper was executed. Add a missing-prerequisite case and a stale-reference case. Record omitted requirements as navigation defects even when the final document looks plausible.
For distribution, connect this placement ledger to release provenance so every influential file has an immutable identity. Skills in Production develops the full authoring and release method. The scenario and ledger here were independently written for the web.
Evidence
Agent Skills supports progressive loading of metadata, instructions, and additional resources.
The specification describes separate loading stages and recommends shallow references from the skill entry file.
Primary source · standard · checked Sep 8, 2026
Limit: The documented structure is an authoring convention; actual file access and loading behavior depend on the implementation.
Skill helpers can execute exact operations without requiring the model to reproduce their implementation in generated text.
The engineering article describes executable code and conditionally read files as complementary skill resources.
Primary source · official-doc · checked Sep 8, 2026
Limit: A deterministic helper can still contain defects, unsafe effects, or unpinned dependencies.
Content placement should follow when a rule is needed and whether a decision tolerates variation.
The placement ledger assigns a load condition, owner, and verification method to each skill component.
Signal Studio author framework · reviewed Sep 8, 2026
Limit: The ledger does not itself enforce required reads or prevent a host from skipping a reference.
Limitations
This design concerns the internal organization of one skill. It does not guarantee a host will obey read conditions, define a universal context budget, or establish correctness and safety of helper code.
FAQ
- Should I move every long section out of SKILL.md?
- No. Keep essential decisions and the conditions for loading other files in the entry point. Move detailed material when it has a clear task-specific read condition, not merely to meet a preferred file length.
- Does putting an operation in a script make it safe?
- No. It makes the implementation inspectable and testable. Its arguments, dependencies, file access, network access, and side effects still require appropriate controls and verification.
Related guides
Continue within Agent skills in production, or use one of these adjacent diagnostics:
Editorial QA: automated native-English, structure, source-presence, and link checks completed . This record is not an independent expert endorsement. Review boundary.