Writes a reusable agent skill
Customizing agents · competency customizing-agents/writes-skill
Taught in: the Customizing agents course
Draws on: Agent skills, Project instructions
Learning objectives
Chooses between a skill, a tool and an instruction for a need (base)
| Claim | Why | Example |
|---|---|---|
| The learner picks an instruction for a rule, a skill for a procedure, and a tool for an ability the agent does not have. | Each does one thing, and a rule written as a skill or a procedure written as an instruction fails in a predictable way. | "Always use bun, never npm" is an instruction. "How to cut a release" is a skill, and "query the issue tracker" is a tool. |
| The learner asks whether the agent can already do the task with what it has before adding anything. | A skill that wraps a command the agent already knows adds context and no ability. | The agent can run gh pr create unaided, so the skill only records the team's PR template and review steps. |
| The learner weighs what each option costs the context window and the permission set. | Every tool and every loaded skill takes tokens on every turn, and a tool adds to what the agent can do wrong. | A read-only MCP server with forty tools is replaced by a CLI the agent calls when needed. |
Served by: Instruction, skill or tool?
Packages a repeatable procedure as a skill another person's agent can use (base)
| Claim | Why | Example |
|---|---|---|
| The skill states when to use it, the steps, and how to tell the result is right. | Another person's agent has none of the author's context and needs all three to run the procedure without asking. | A release skill says "use when asked to cut a release", lists the six commands in order, and ends with "the tag exists and CI on the tag is green". |
| The skill is tested by running it from a fresh session on someone else's machine. | A procedure that only works with the author's setup is not reusable. | A colleague's agent runs the skill and stops at a missing environment variable, so the skill gains a check for it. |
| The skill names the commands and files exactly, and says what to do when a step fails. | A procedure that assumes success stops at the first surprise. | "If mise run ci fails, fix the reported task and rerun; do not skip the task" is part of the skill. |
Served by: Writing your first skill, Testing a skill from a fresh session
Structures a skill so the agent loads only what it needs (base)
| Claim | Why | Example |
|---|---|---|
| The skill's front matter says in one or two lines what it is for, so the agent can decide whether to load it without reading it. | Every skill's description is in context on every turn, and a long one is paid for on every turn [1]. | The description is "Cut and publish a release of this package" and nothing more. |
| The main skill file holds the common path, and rare cases, long references and templates go into files the skill points to. | A skill that loads everything up front costs the context of the rare case on every run. | The release skill's body is forty lines, and the rollback procedure is in rollback.md, loaded only when needed. |
| The learner measures what the skill costs when loaded and trims it when it grows. | Skills grow by accretion, and no single addition looks expensive. | The learner counts the tokens of the skill directory after each change and moves a bloated table into a script. |
Served by: Loading only what the skill needs
Reads a plugin's parts before installing it and takes only what is needed (base)
| Claim | Why | Example |
|---|---|---|
Before an install, the learner opens the plugin's hook file and the scripts it names, its server list, its bin/ directory and each subagent's tool list. | Claude Code's install screen names each hook but doesn't show the command behind it [2], and a subagent without a tool list may use every tool that subagents are allowed [3]. | The learner opens hooks/hooks.json, sees a PreToolUse hook on Bash, and reads the script to learn that it blocks every commit without a staged changelog. |
| The learner names the parts that act in every session where the plugin is enabled, and the parts that no permission rule checks. | Hooks and server processes run with the user's own rights, outside the permission rules and the sandbox [2]. | For a plugin wanted for one skill, the learner notes that its hook and its tracker connection are active in sessions that never use that skill. |
| The learner decides between installing the plugin at the narrowest scope that fits, copying one skill out of it when the license allows, and leaving it. | A plugin installed for one part brings all of its parts into every session where it is enabled. | The team wants only the release skill, so the learner copies it into the project's .claude/skills/ and doesn't install the plugin. |
Served by: Reading a plugin before you install it
Alignment
| Framework | Code | Asks | Objectives here |
|---|---|---|---|
| Brilliant Coding with AI | SEC-3, SEC-5 | Evaluate AI code for vulnerabilities; supply-chain risk | evaluates-a-plugin |
| Brilliant Coding with AI | MEM-1, MEM-2 | Manage memory; turn repeated work into reusable knowledge | packages-a-procedure |
References
- Anthropic. Introduction to agent skills. Claude Academy. Course.
Academy introduction-to-agent-skills - Anthropic. Plugin security and trust. Claude Code documentation. Reference.
Claude Code plugin security - Anthropic. Create custom subagents. Claude Code documentation. Reference.
Claude Code subagents