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

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

*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](https://schubergphilis.github.io/ai-training/glossary/#skill-vs-tool-vs-instruction)
- **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](https://schubergphilis.github.io/ai-training/glossary/#skill-spec)
- **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](https://schubergphilis.github.io/ai-training/glossary/#progressive-disclosure)
- **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](https://schubergphilis.github.io/ai-training/glossary/#writing-a-good-skill)
- **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](https://schubergphilis.github.io/ai-training/glossary/#plugins)
- **Invocation mode**: Who may start a skill: the model, when a request matches the skill's description, or only the person, by typing its name. A model-invoked skill applies itself when it fits, and its description takes up context in every session. A user-invoked skill costs no context until it is called and runs only when the person decides, which suits procedures with side effects such as a deploy. A skill can also be hidden from the person and kept for the model. [glossary](https://schubergphilis.github.io/ai-training/glossary/#invocation-mode)
- **Skill scope**: Where a skill is installed decides who has it. A personal skill is in the user's own configuration and follows that person into every project. A project skill is committed to the repository, so everyone who works there gets the same version and can review changes to it. An organization can also install skills for all its users. When two skills share a name, a fixed order decides which one wins, and a personal skill hides a project skill of the same name. [glossary](https://schubergphilis.github.io/ai-training/glossary/#skill-scope)
- **Published skill sets**: Collections of skills that a vendor or a developer maintains for others to install, often as a plugin. Model vendors, tool makers and individual developers all publish them. A set like this is a dependency: it runs in your sessions, it changes when its author updates it, and its license can differ from one skill to the next. Judge it as you would a library, by who maintains it, how active it is, what it contains and what dropping it would cost. [glossary](https://schubergphilis.github.io/ai-training/glossary/#published-skill-sets)

## Links

- **Builds on:** [Project instructions](https://schubergphilis.github.io/ai-training/topics/customizing-agents/instructions/)
- **Leads to:** [Memory and session context](https://schubergphilis.github.io/ai-training/topics/customizing-agents/memory/)
- **Competencies drawing on it:** [Adopts a published skill set without giving up control of the project](https://schubergphilis.github.io/ai-training/competencies/customizing-agents/adopts-a-skill-set/), [Writes a reusable agent skill](https://schubergphilis.github.io/ai-training/competencies/customizing-agents/writes-skill/)

## Lessons

- [Adopting a published skill set](https://schubergphilis.github.io/ai-training/customizing-agents/adopting-a-skill-set/) (tutorial)
- [Writing your first skill](https://schubergphilis.github.io/ai-training/customizing-agents/first-skill/) (tutorial)
- [Reading a plugin before you install it](https://schubergphilis.github.io/ai-training/customizing-agents/plugins/) (explanation)
- [Loading only what the skill needs](https://schubergphilis.github.io/ai-training/customizing-agents/progressive-disclosure/) (tutorial)
- [Instruction, skill or tool?](https://schubergphilis.github.io/ai-training/customizing-agents/skill-or-tool-or-instruction/) (explanation)
- [Testing a skill from a fresh session](https://schubergphilis.github.io/ai-training/customizing-agents/testing-a-skill/) (tutorial)
- [Who invokes a skill, and where it lives](https://schubergphilis.github.io/ai-training/customizing-agents/who-invokes-a-skill/) (explanation)

## Sources

- `AEC-17` [Agent skills: skills versus tools, the spec, progressive disclosure](https://lsimons.github.io/agent-engineer-course/17-agent-skills/), Agent Engineer Course (course)
- `DLAI-10` [Agent Skills with Anthropic](https://www.deeplearning.ai/courses/agent-skills-with-anthropic), DeepLearning.AI (course)
- `Academy introduction-to-agent-skills` [Introduction to agent skills](https://academy.claude.com/courses/introduction-to-agent-skills), Claude Academy (course)
- `Academy claude-code-in-action` [Claude Code in action](https://academy.claude.com/courses/claude-code-in-action), Claude Academy (course)
- `Academy ai-native-sdlc-playbook` [The AI-native SDLC playbook](https://academy.claude.com/courses/ai-native-sdlc-playbook), Claude Academy (course)
- `Claude Code skills` [Extend Claude with skills](https://code.claude.com/docs/en/skills), Claude Code documentation (reference)
- `Agent Skills spec` [Agent Skills specification](https://agentskills.io/specification), agentskills.io (reference)
- `Claude Code plugins` [Plugins overview](https://code.claude.com/docs/en/plugins), Claude Code documentation (reference)
- `anthropics skills` [Agent Skills (the anthropics/skills repository)](https://github.com/anthropics/skills), GitHub (reference)
- `OpenAI Academy extend-codex-workflows-4e61p` [Extend Codex Workflows](https://academy.openai.com/public/courses/extend-codex-workflows-4e61p), OpenAI Academy (course)