A skill is a versioned, reusable procedure that an agent can invoke on demand.
Skills are the manual's equivalent of a function library: prompts, scripts, and conventions that have been reviewed and tested, and that the agent can invoke without having to re-derive the procedure from first principles. Skills are the mechanism by which the manual's author captures the operator's accumulated craft.
What goes in a skill
A skill typically contains:
1. A procedure. The step-by-step instructions that the agent should follow. The procedure is the payload of the skill.
2. A trigger. The conditions under which the skill should be invoked. The trigger is the specification of when the procedure is appropriate.
3. A contract. The inputs the skill expects, the outputs the skill produces, and the failure modes the skill handles. The contract is the interface between the skill and the rest of the system.
4. A test. A way to verify that the skill is working correctly. The test is the operator's confidence that the skill is still producing the expected outcomes.
5. A history. The decision log: why the skill was created, what it replaced, and what it has been used for. The history is the operator's memory of the skill's evolution.
Why skills matter
Skills are the mechanism by which the operator's craft becomes reusable. Without skills, the agent re-derives the procedure from first principles every time, and the procedure is slightly different each time. With skills, the procedure is consistent, the procedure is reviewable, and the procedure is improvable. Skills are the way the operator scales the agent's capabilities without scaling the operator's workload.
Operator implications
Skills are the right place to start when an operator notices that the agent is performing the same procedure repeatedly with slight variations. The most common operator issue with skills is that the skill is not actually being invoked (the agent is re-deriving the procedure from scratch), and the second most common is that the skill is too rigid (the skill does not adapt to the specific situation). The skill is also the right place to start when an operator is adding capabilities — the canonical question is "should this be a new skill, or should an existing skill be extended?"
Related terms
A skill is a reusable procedure that an agent loop invokes. A skill is often exposed to the agent through a tool call or through an MCP interface. A skill's evolution is tracked through the observability layer. A skill's manual is this site.
For the full primer, see First Steps: Sessions and Memory.
Skills vs. prompts
A skill is not a prompt. A prompt is a single piece of input that the model processes; a skill is a procedure that the agent can invoke on demand. The difference is the difference between a sentence and a function: the sentence is a one-shot input, the function is a reusable procedure.
The skill is the right abstraction for the agent's reusable capabilities because the skill is versioned (the skill can be updated without updating the agent), the skill is testable (the skill can be verified in isolation), and the skill is shareable (the skill can be reused across agents and across sessions). The prompt is the wrong abstraction for reusable capabilities because the prompt is not versioned, the prompt is not testable, and the prompt is not shareable.