Skip to content
AI Training

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

Lessons

Your reference

Each lesson above adds its takeaways and its example here once you finish it. Your reference lists every lesson you have finished.

Adopting a published skill set

Unlocks when you finish Adopting a published skill set.

Writing your first skill

Unlocks when you finish Writing your first skill.

Reading a plugin before you install it

Unlocks when you finish Reading a plugin before you install it.

Loading only what the skill needs

Unlocks when you finish Loading only what the skill needs.

Instruction, skill or tool?

Unlocks when you finish Instruction, skill or tool?.

Testing a skill from a fresh session

Unlocks when you finish Testing a skill from a fresh session.

Who invokes a skill, and where it lives

Unlocks when you finish Who invokes a skill, and where it lives.

Sources