Before you start
You need the reviewing-api-changes folder from lesson 1, though any skill whose SKILL.md has started to grow will do. The script in this lesson is Bash and calls git, so a shell with both is enough.
The sample skill and its script were written for this course. The rules come from the Agent Skills specification and guides, Anthropic's authoring guide and Claude Code's documentation, listed under Sources.
Every fact here comes from the pages under Sources, read on 4 November 2026. This lesson is not hands-on testing.
Split a skill into four parts
A SKILL.md that has grown into a manual is the usual starting point. Anthropic's authoring guide asks of every paragraph whether the model needs it and whether it justifies its token cost. The Agent Skills guide turns that into a test: would the agent get this wrong without the instruction? If not, cut it.
The version below is what the sample skill looks like after the split. Its steps are short because the detail moved out, and each pointer names the file to read and the reason.
---
name: reviewing-api-changes
description: Reviews changes to an OpenAPI or Swagger spec for breaking changes such as removed fields, renamed paths and stricter validation. Use when the user asks whether an API change is safe to ship, compares two versions of an API, or edits a spec file, even if they never say "breaking change".
---
# Reviewing API changes
1. Run scripts/changed_specs.sh to list the spec files changed on this branch.
2. Read the old and the new version of each file.
3. If a change removes, renames or retypes a field, or tightens validation, read references/breaking-changes.md before you judge it.
4. Write the review with assets/review-template.md.
## Gotchas
- Specs under api/ are generated from the .yaml files. Review the .yaml source and skip the .json copies.
- A new required request field breaks existing clients, even though adding fields usually doesn't.
- Cut what the agent already knows. The guide's example is a paragraph that explains what a PDF is. Naming the library to use stays, and the explanation goes.
- Move material that only some tasks need into
references/. Herebreaking-changes.mdholds the catalog of changes that break clients. Keep one topic per file, because smaller files cost less context when they load, and start any file over 100 lines with a contents list. - Move work that must come out the same every time into
scripts/. Finding the changed spec files is that kind of work, so it becomeschanged_specs.sh. - Put output templates and fixed data in
assets/. The review template loads only when the agent writes the review. - Point at each file from SKILL.md and say when to open it. "Read references/api-errors.md if the API returns a non-200 status code" is the guide's example of a pointer that works, next to a vague "see references/ for details".
- Link every file straight from SKILL.md. When one reference file points to a second, Claude may preview the second with
head -100and miss the rest. - Write paths relative to the skill folder, with forward slashes even on Windows. In Claude Code,
${CLAUDE_SKILL_DIR}/scripts/changed_specs.shalso resolves wherever the skill is installed.
What goes where, and what it costs
Agents load a skill in three stages. The name and description come first, for every skill. The SKILL.md body follows when a task matches. Files in the skill folder come last, and only when a step reaches for one. The overview gives the consequence: a skill can hold dozens of reference files, and a task that needs one reads one.
Scripts get a cheaper path still. When the agent runs changed_specs.sh, the code never enters the context. Only what the script prints does. That is why Anthropic prefers a tested script to code the agent writes on the spot, which costs tokens and time on every run.
~100
tokens per skill, always loaded: its name and description
Source: Claude Platform docs: Agent Skills (read November 4, 2026)
5,000
tokens is the recommended ceiling for a SKILL.md body
Source: Agent Skills specification (read November 4, 2026)
500
lines is the most the specification suggests for SKILL.md
Source: Agent Skills specification (read November 4, 2026)
0
tokens for a bundled file until the agent reads it
Source: Claude Platform docs: Agent Skills (read November 4, 2026)
reviewing-api-changes/
├── SKILL.md
├── references/
│ └── breaking-changes.md
├── scripts/
│ └── changed_specs.sh
└── assets/
└── review-template.md| Part | Holds | Loads when | In this skill |
|---|---|---|---|
| SKILL.md | The steps, the pointers and the gotchas | The skill is triggered | Four steps and two gotchas |
references/ | Documents the agent reads | A step points to one and the task needs it | breaking-changes.md |
scripts/ | Code the agent runs | A step runs it, and only its output enters the context | changed_specs.sh |
assets/ | Templates, images and lookup data | A step points to one | review-template.md |
Write scripts an agent can run
State in SKILL.md whether a script is for running or for reading. Anthropic's guide contrasts "Run analyze_form.py to extract fields" with "See analyze_form.py for the extraction algorithm". Running is the usual choice, since it is more reliable than regenerated code. The Agent Skills guide adds a signal for when to bundle one. If the agent reinvents the same helper in every run, such as a chart builder or a parser, write it once, test it and put it in scripts/.
A one-off command needs no script at all. When a package already does the job, call it from the instructions with a pinned version, as the guide on using scripts does with npx eslint@9 --fix . and uvx ruff@0.8.0 check .. Also state prerequisites such as the Node.js version.
The sample script below follows the guide's rules for agent-run code. It never prompts, prints usage for --help, names a fix when a branch is missing, and returns one path per line.
#!/usr/bin/env bash
# List OpenAPI or Swagger files changed against a base branch, one path per line.
set -euo pipefail
if [ "${1:-}" = "--help" ]; then
echo "Usage: scripts/changed_specs.sh [BASE_BRANCH]"
echo "Prints one changed OpenAPI or Swagger file per line. BASE_BRANCH defaults to main."
exit 0
fi
base="${1:-main}"
if ! git rev-parse --verify --quiet "$base" > /dev/null; then
echo "Error: branch '$base' was not found. Pass the branch to compare against, for example: scripts/changed_specs.sh origin/main" >&2
exit 2
fi
git diff --name-only "$base"...HEAD | grep -Ei '(openapi|swagger).*\.(ya?ml|json)$' || true
- No interactive prompts. Agents work in non-interactive shells, and a script that waits for input hangs. Take input from flags, environment variables or stdin.
- A short
--helptext, because that is how an agent learns the interface. Its output enters the context window, so keep it brief. - Error messages that say what went wrong, what was expected and what to try. An opaque "invalid input" wastes a turn.
- Data on stdout and diagnostics on stderr, in a structured format such as JSON, CSV or TSV.
- Safe retries. Agents may run a command twice, so "create if not exists" beats "create and fail on duplicate".
How Barry Zhang and Lydia Hallie of Anthropic use the skill folder
Barry Zhang, a research engineer at Anthropic, replied on X in October 2025 that Skills grew out of a prototype he built to show Claude Code is a general-purpose agent. The team concluded that bash and a filesystem were all a skill needed. That is the layout from this lesson: a reference is a file the agent reads with bash, and a script is a program it runs the same way.
Lydia Hallie, who works on Claude Code at Anthropic, posted a tip in March 2026 for a skill that needs fresh data. In Claude Code, a SKILL.md line made of an exclamation mark and a command in backticks runs when the skill is invoked. Claude Code swaps in the command's output, and the model sees only the result. In the sample skill, that line could hand over the list of changed spec files before the agent reads step 1.
It was a natural conclusion once we realized that bash + filesystem were all we needed
Screenshots of X's own embeds of the posts, taken on 5 November 2026, with the time in UTC. X cuts the first post short with Show more. Select a screenshot to open the post on X.
Common mistakes
- A pointer with no condition. "See references/ for details" leaves the agent guessing, and the file may never open.
- A chain of references, where SKILL.md links to advanced.md and that links to details.md. Keep every file one level from SKILL.md.
- A rule the agent must always follow, buried in a reference file. The Agent Skills guide keeps gotchas in SKILL.md, because the agent may not recognize the situation that calls for a separate file.
- A menu of tools. Name one default and mention a single fallback, such as pdfplumber for text and pytesseract only for scans.
- A script that assumes its packages exist. List them in SKILL.md. The Claude API sandbox has no runtime package installation, so a script that needs a package fails there.
Try it yourself
Open a SKILL.md you wrote and count its lines with wc -l SKILL.md. Find one paragraph that only some tasks need, move it into a file under references/, and replace it with a pointer that says which file to open and when. Rerun the prompts from lesson 1.
Then look for a step the agent does the same way every time, such as listing files or validating output. If it takes more than a few commands, write it as a script and add a --help text.
- Is every file in the folder linked from SKILL.md, with a reason to open it?
- Could any script run twice without damage?
- Does the SKILL.md body stay well under the limits in the numbers above?
Next
A skill split this way is easy to read and cheap to load. Whether it works is a separate question. Lesson 3 tests triggering and output quality with prompts, repeat runs and a baseline without the skill.
The first draft of a skill, the folder rules and the frontmatter limits are in how to create an Agent Skill. Finished skill folders appear on Mindket as kits. Instructions that hold for every task in a project, rather than one job, belong in CLAUDE.md, which Claude Code loads at the start of every session.
Check yourself
Where does the template the agent uses to write its review belong in a skill folder?
Show answer
D.
assets/Output templates and fixed data go inassets/, and the agent loads one only when a step points to it.Which pointer in SKILL.md works best?
Show answer
B. "Read references/breaking-changes.md if a change removes, renames or retypes a field" A pointer that names the file and the condition for opening it tells the agent when the file is worth the tokens.
An agent runs
scripts/changed_specs.sh. What enters its context?Show answer
A. Only what the script prints The script's code never enters the context, only its output does, which is why a tested script costs less than code written on the spot.
Which design suits a script that an agent runs?
Show answer
C. It takes input from flags or stdin and never waits for a prompt Agents work in non-interactive shells, so a script that waits for input hangs.
Frequently asked questions
How long should a SKILL.md be?
Under 500 lines and, as a recommendation, under 5,000 tokens, according to the specification. Past that, move reference material into separate files and keep only what the agent needs on every run.
Why doesn't the agent open my reference file?
Anthropic's guide lists what to watch for when you read a run: files opened in an odd order, links the agent never follows, and a file it reads again and again. A file that is never opened may be unnecessary or poorly signaled in SKILL.md. A file read on every run may belong in SKILL.md itself.
What goes in the assets folder?
Static resources: templates such as document or configuration templates, images such as diagrams, and data files such as lookup tables or schemas. The Agent Skills guide stores longer output templates there and points to them from SKILL.md, so they load only when needed.
Can a skill have folders other than scripts, references and assets?
Yes. The specification says a skill directory may hold any files and directories beyond SKILL.md, and the three names are conventions. Anthropic's examples use files such as reference.md and examples.md beside a scripts/ folder.
What language can a skill script use?
The specification names Python, Bash and JavaScript as common options, and each agent decides what it supports. The Agent Skills guide shows self-contained scripts that declare their dependencies inline for Python (run with uv), Deno, Bun and Ruby, so the agent needs no separate install step.
Do skill scripts work the same in every Claude product?
No. Claude Code gives a skill the same network access as any other program on your computer. The Claude API runs it in a sandbox with no network access and no runtime package installation, and claude.ai varies with user and admin settings.
Sources
- Agent Skills specification https://agentskills.io/specification
- Agent Skills: Best practices for skill creators https://agentskills.io/skill-creation/best-practices
- Agent Skills: Using scripts in skills https://agentskills.io/skill-creation/using-scripts
- Claude Platform docs: Skill authoring best practices https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices
- Claude Platform docs: Agent Skills https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview
- Claude Code docs: Skills https://code.claude.com/docs/en/skills
- Barry Zhang on X: where Skills came from, 16 October 2025 https://x.com/barry_zyj/status/1978951690452615413
- Lydia Hallie on X: inject shell output into a skill, 18 March 2026 https://x.com/lydiahallie/status/2034337963820327017