Agent skills
Customizing agents · topic customizing-agents/skills
A skill packages a procedure so an agent can load and follow it on demand: a description of when it applies, instructions to follow and any files it needs. This topic distinguishes skills from tools and instructions, introduces the skill specification, explains progressive disclosure and covers what makes a skill worth reusing.
Concepts
- Skill vs tool vs instruction
- Three ways to change what an agent does. An instruction is standing text loaded every session, for rules that always apply. A tool is a function the agent can call, for capabilities it lacks. A skill is a procedure loaded only when relevant, for repeatable multi-step work the agent could do but does inconsistently. Pick by frequency, by whether the need is knowledge or capability, and by context cost. glossary
- Skill spec
- The open format for an agent skill: a directory with a metadata file that names the skill, describes when to use it and holds the instructions, plus optional scripts and reference files alongside. The description is what the agent reads to decide whether to load the skill, so it carries the trigger; the body carries the procedure. Because the format is shared, skills move between agents. glossary
- Progressive disclosure
- Structuring a skill so the agent reads only what the current step needs: a short description always visible, the main instructions loaded when the skill is chosen, and detailed references or scripts opened only when a step calls for them. It keeps the context window small across many available skills and puts depth where it is used instead of where it is loaded. glossary
- Writing a good skill
- A good skill has a description that fires on the right requests and no others, steps that are concrete enough to follow without guessing, a way for the agent to check its own result, and scripts for anything deterministic. It is tested by watching an agent use it on a real task and revising where it hesitated or went wrong, the same iteration loop as prompting. glossary
- Plugins
- The unit for distributing customizations together: a plugin bundles skills, hooks, subagents and server connections into one installable package with a version. A marketplace is a catalog of plugins that a team or vendor publishes so others can install from it by name. Installing a plugin lets its hooks run in your sessions and gives its servers the access you grant, so treat it like any other dependency and read what it contains. glossary
Links
- Builds on: Project instructions
- Leads to: Memory and session context
- Competencies drawing on it: Writes a reusable agent skill
Lessons
- Writing your first skill (tutorial)
- Reading a plugin before you install it (explanation)
- Loading only what the skill needs (tutorial)
- Instruction, skill or tool? (explanation)
- Testing a skill from a fresh session (tutorial)
Your reference
Each lesson above adds its takeaways and its example here once you finish it. Your reference lists every lesson you have finished.
Writing your first skill
Unlocks when you finish Writing your first skill.
Takeaways
- A skill is a directory named after the skill with a
SKILL.mdin it. Its front matter needsnameanddescription, andnamemust equal the directory name. - The description is the trigger. It is in context on every turn, and the body is loaded when a task matches it or you invoke the skill, and remains on later turns until compaction. Name the requests that should load it and no others.
- The body says when to use the skill, gives the steps in order with exact commands and file names, and ends with a check the agent can run, with the line that means the result is right.
- Each step that can fail says what the agent sees, what it does about it, and what it must not do. The agent then knows what to do at the first surprise.
- A skill is done when someone else's agent runs it from a fresh session without asking. Running it that way is the next lesson.
Example
Run the release check · open in the lesson
Run this in the copied package, and compare with the output below.
python3 release_check.pyPrints: release 0.3.0: ok (verified in CI from site/examples/customizing-agents/first-skill/check.py)
Reading a plugin before you install it
Unlocks when you finish Reading a plugin before you install it.
Takeaways
- A plugin ships skills, subagents, hooks and MCP servers together, and you usually install it by name from a marketplace.
- An enabled plugin costs context on every turn and runs its hooks on their events, also in sessions that never use it.
- Your permission rules check the calls Claude makes to a plugin's tools. Hooks and server processes run with your user rights, outside both the rules and the sandbox.
- Read
hooks/hooks.json, the scripts it names,.mcp.jsonandbin/before you install. Claude Code's install screen names each hook but doesn't show the command behind it. - Weigh a plugin like a dependency: install it, copy one skill out of it when the license allows, or leave it.
Example
List what release-kit holds · open in the lesson
Run this, and compare with the output below.
python3 inventory.py release-kitPrints the lines below (verified in CI from site/examples/customizing-agents/plugins/release_kit.py)
plugin release-kit 1.4.0
skills:
release
commands: none
agents:
release-notes, tools: Read, Grep, Bash
hooks:
PreToolUse, tool matches Bash: python3 "${CLAUDE_PLUGIN_ROOT}/scripts/changelog_guard.py"
servers:
tracker: calls https://tracker.example.com/mcp
bin: none
always loaded, names and descriptions: 50Loading only what the skill needs
Unlocks when you finish Loading only what the skill needs.
Takeaways
- An agent loads a skill in stages: the name and description of every skill at startup, the whole
SKILL.mdwhen a task matches it, and other files only when a step points to them. - The description is paid for on every turn of every session, and the body on every run of the skill. In Claude Code the body stays in the conversation for the turns after it runs.
- Keep the common path in
SKILL.md. Move a rare case or a long reference into a file one level fromSKILL.md, and leave a pointer that names when to read it. - Measure the skill with the same rule before and after a change. An estimate is enough to compare two versions. The exact count for a model comes from the vendor's tokenizer.
- Skills grow a little at a time, so measure after each addition.
Example
Measure the skill as it stands · open in the lesson
Run this, and compare with the output below.
python3 measure.py grown/releasePrints the lines below (verified in CI from site/examples/customizing-agents/progressive-disclosure/before.py)
grown/release always loaded, name and description: 39 when the skill runs, SKILL.md: 1256 when a step reads it: no other files total, SKILL.md read: 1295 total, every file read: 1295
Instruction, skill or tool?
Unlocks when you finish Instruction, skill or tool?.
Takeaways
- An instruction is standing text on every turn, a skill is a procedure loaded when a task matches its description, and a tool is a function for an ability the agent lacks.
- Before writing any of them, ask whether the agent can already do the task with a shell and what the model knows. A skill that repeats public documentation adds a line to every turn and teaches nothing.
- Choose by whether the rule always applies (instruction), whether the agent knows how but is inconsistent (skill), or whether it lacks the ability (tool).
- Instructions and skills spend context and add no new access. A tool spends context on every turn and adds an ability with whatever access its credentials carry.
- A skill that wraps a command the agent can already run is the middle way between using the command bare and connecting a tool server.
Example
This lesson has no runnable example or prompt block.
Testing a skill from a fresh session
Unlocks when you finish Testing a skill from a fresh session.
Takeaways
- Test a skill in a clean clone and a new session, with auto memory off, so the conversation you had while writing it can't fill a gap for the agent. Your personal instructions still load, and a colleague's machine is the test without them.
- Read the transcript for each place the agent hesitated, asked or guessed. Each one is a line missing from the skill.
- A missing line is often a check on the environment before the steps, a step that names the tool or state it needs, or a success test exact enough to fail a wrong result.
- When a fact is missing from the repository, the right line tells the agent to stop and ask. A clear stop is better than a guess that passes the check.
- Rerun in a new session after each revision, and compare the two runs.
Example
What does step 3 have to work with? · open in the lesson
Predict the output for both repositories. The script prints none where git describe --tags --abbrev=0 fails.
python3 fresh_clone.pyPrints the lines below (verified in CI from site/examples/customizing-agents/testing-a-skill/fresh_clone.py)
author's repository last release tag: v0.3.0 commits since it: Document where notes are stored clean clone last release tag: none whole log: Import the notes package
Sources
AEC-17Agent skills: skills versus tools, the spec, progressive disclosure, Agent Engineer Course (course)DLAI-10Agent Skills with Anthropic, DeepLearning.AI (course)Academy introduction-to-agent-skillsIntroduction to agent skills, Claude Academy (course)Academy claude-code-in-actionClaude Code in action, Claude Academy (course)Academy ai-native-sdlc-playbookThe AI-native SDLC playbook, Claude Academy (course)