A skill needs one reliable entry point: SKILL.md. The rest of its directory should answer a practical question. Put the workflow in the main file, a team policy in a reference, a reusable format in an asset, and deterministic helper code in a script. If every rule and resource sits in one long file, the agent has to carry details it may not need for this task.

The Agent Skills specification requires a directory with a SKILL.md file and describes scripts/, references/, and assets/ as optional conventions. Anthropic’s overview explains how metadata, instructions, and resources load at different stages.

Give each file one job

The paths below show the example’s file split. They describe resources the skill author would create, not files installed by this article:

release-notes/
├── SKILL.md                         # entry point and workflow
├── references/
│   └── release-policy.md            # audience and inclusion rules
├── assets/
│   └── notes-template.md            # reusable output template
└── scripts/
    └── list-merged-prs.sh           # optional executable helper

For example, SKILL.md can say: “Read references/release-policy.md before classifying changes. Use assets/notes-template.md when writing the draft. Run scripts/list-merged-prs.sh only when source inputs need collecting.” Those links connect each extra file to a particular step.release-notes/SKILL.md, release-notes/references/release-policy.md, release-notes/assets/notes-template.md, and release-notes/scripts/list-merged-prs.sh. These names are examples; the important part is that the main instructions point to each resource when it is needed.

SKILL.md holds the trigger, steps, output contract, and boundaries. release-policy.md explains the audience, which internal changes belong in public notes, and how the team handles uncertain impact. The template gives the expected headings. The script can collect merged pull-request metadata in a stable format, if the environment has the required command and permissions.

The standard does not define a cli/ directory. A command-line interface is a tool the agent may invoke, such as git or gh; it is not a reserved Agent Skills folder. If the workflow relies on one, say which command it runs, what access it needs, what output to expect, and what to do when the tool is missing. Keep skill-owned executable helpers under scripts/ and make their dependencies clear.

Keep the main instructions operational

Use the main file to connect the task to its resources. For a release-note request, it can tell the agent to identify the release range, gather the merged pull requests, read diffs when titles are vague, and group changes by audience. It can point to the policy before deciding whether an internal helper rename belongs in public notes. It can point to the template when it writes the draft.

Use the same example inputs throughout: PR #41 fixes exported filenames that contain spaces; PR #42 renames an internal helper; PR #43 changes a timeout without describing its effect. The instructions should preserve the first as a verified fix, handle the second according to the release policy, and ask for clarification on the third. A helper script can fetch the records. It cannot decide whether a vague change is safe to claim.

Keep the instructions stepwise but short. Name the source of truth for the release range. Tell the agent to verify each note against a source. Return a draft for review. When a rule depends on team policy, link to the policy file instead of copying the full policy into every skill.

Use progressive disclosure with care

The specification separates three layers: metadata for discovery, the main instructions when the skill activates, and optional resources read when needed. Keep name and description in the YAML frontmatter. Match the name to the directory, and make the description specific enough to tell a release-note request from a general question. The Claude Platform authoring guide recommends a concise entry point and focused references.

A reference does not save context if SKILL.md tells the agent to read every reference on every task. Link each file beside the decision that needs it: load the release policy when choosing the audience, the template when formatting the draft, and the script only when collecting pull requests. Anthropic recommends keeping the main file under 500 lines and moving detailed material into referenced files.

Make the directory honest

Use relative paths that exist. If a script needs gh, do not assume every agent has that command or a logged-in account. Make the failure path clear: ask for the missing input, or return a partial draft with gaps called out. A skill should not claim it checked data that its tools could not reach.

The right split depends on the task. One short workflow may need only SKILL.md. Add a reference when policy is too detailed to repeat, an asset when output needs a stable shape, and a script when code can do a deterministic job. Test with the resources present and with an expected tool absent.

Test the files and tools agents will have

Give a fresh agent a release-note request and the three example pull requests. Check whether it finds SKILL.md, loads the release policy before classifying PR #42, and flags the missing impact in PR #43. Then remove gh or its credentials. The skill should ask for source data or report the gap, not invent a successful lookup.

Also send a request that should not trigger the skill, such as asking what a release branch is. A broad description can steal unrelated work; an exact-phrase description can miss normal requests. Run the same cases with the models and agent environments the team plans to use. The authoring guide recommends testing activation and output with real tasks.

For the writing choices behind the workflow, read how to write an effective Agent Skill. For a fuller evaluation loop, see evaluating Agent Skills. Keep the entry point short enough to use, and keep every extra file tied to a decision the agent has to make.