# Writes a reusable agent skill

> Competency customizing-agents/writes-skill

Page: https://schubergphilis.github.io/ai-training/competencies/customizing-agents/writes-skill/
License: CC BY-SA 4.0, https://creativecommons.org/licenses/by-sa/4.0/

*Customizing agents* · competency `customizing-agents/writes-skill`

**Taught in:** the [Customizing agents](https://schubergphilis.github.io/ai-training/customizing-agents/) course

**Draws on:** [Agent skills](https://schubergphilis.github.io/ai-training/topics/customizing-agents/skills/), [Project instructions](https://schubergphilis.github.io/ai-training/topics/customizing-agents/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?](https://schubergphilis.github.io/ai-training/customizing-agents/skill-or-tool-or-instruction/)

### 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](https://schubergphilis.github.io/ai-training/customizing-agents/first-skill/), [Testing a skill from a fresh session](https://schubergphilis.github.io/ai-training/customizing-agents/testing-a-skill/)

### 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 (Introduction to agent skills, Claude Academy). | 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](https://schubergphilis.github.io/ai-training/customizing-agents/progressive-disclosure/)

### 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 (Plugin security and trust, Claude Code documentation), and a subagent without a tool list may use every tool that subagents are allowed (Create custom subagents, Claude Code documentation). | 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 (Plugin security and trust, Claude Code documentation). | 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](https://schubergphilis.github.io/ai-training/customizing-agents/plugins/)

### Chooses who invokes a skill and where it is installed (base)

| Claim | Why | Example |
| ----- | --- | ------- |
| The learner makes a skill with side effects invocable by the user only. | A deploy or a message to other people should run when a person decides, and a skill the model may start can run when its description happens to match (Extend Claude with skills, Claude Code documentation). | The deploy skill sets `disable-model-invocation: true`, and the coding-conventions skill stays available to the model. |
| The learner weighs the context a model-invoked skill costs against how often it helps. | The description of every model-invoked skill is in context in every session (Extend Claude with skills, Claude Code documentation). | The learner makes a rarely used report skill user-invoked, so its description no longer loads in every session. |
| The learner installs a skill the team needs in the project and keeps a personal skill in their own configuration. | A project skill is shared and reviewed with the code, and a personal one follows only its owner. | The release skill is committed to `.claude/skills/`, and the learner's own note-taking skill stays in their home directory. |

Served by: [Who invokes a skill, and where it lives](https://schubergphilis.github.io/ai-training/customizing-agents/who-invokes-a-skill/)

## 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

- Introduction to agent skills, Claude Academy, https://academy.claude.com/courses/introduction-to-agent-skills
- Plugin security and trust, Claude Code documentation, https://code.claude.com/docs/en/plugins/security
- Create custom subagents, Claude Code documentation, https://code.claude.com/docs/en/sub-agents
- Extend Claude with skills, Claude Code documentation, https://code.claude.com/docs/en/skills