How it works
An Agent Skill separates a capability from the always-on context. The point is that most of what an agent could know is irrelevant to the task in front of it, so you keep that knowledge dormant until it earns its place. The mechanism is progressive disclosure:
- A folder holds an instruction file — the procedure or domain knowledge — plus optional scripts, templates, or reference material.
- Cheap metadata (a name and a one-line description) stays visible to the agent at all times.
- When the current task matches that description, the agent loads the full skill body into context.
- The skill runs: the model follows its steps, calls its scripts, or reads its references.
- When the task ends, the detail falls back out of the working window; only the index line remains.
So the model always sees a short catalog of what it can do, and pulls the expensive detail only on demand. The context cost you pay is proportional to relevance, not to the size of your whole capability library. A skill is not a tool call and not a fine-tune — it is packaged text (and sometimes code) that arrives at the moment it becomes useful and leaves when it stops.
Why it matters in an agent harness
Context is the scarcest resource in a long-running agent, and skills are how you manage it without amputating capability. If you paste every procedure into the system prompt, you pay for all of them on every turn, dilute the model's attention, and push toward the compaction boundary faster. Skills let capability scale sub-linearly with context: a hundred skills cost roughly what one costs until one is actually invoked.
They also give you a legible unit of behavior. A skill is a named, versioned folder you can read, diff, and review — which means a capability change is a reviewable change, not a silent edit buried in a mega-prompt. That matters for the same reasons the rest of a harness matters: you want the agent's competence to be observable and reversible. Roll a skill back and the behavior it encoded goes with it.
Finally, skills are a permission-shaped boundary. Because a skill only enters context when its trigger fires, you can reason about when a procedure is available and what it can reach. That is not a security control on its own — the model still decides what to load — but it narrows the surface you have to keep legible.
Agent Skill vs MCP server
Builders conflate these because both extend an agent, but they extend it at different layers, and the distinction changes how you design.
| Agent Skill | MCP server / tool | |
|---|---|---|
| What it adds | Instructions and knowledge into the model's context | A callable capability the model invokes |
| Where it runs | Inside the reasoning, as text the model reads | Outside, as a function with typed inputs and outputs |
| Cost model | Context tokens while loaded | A tool call round-trip |
| Failure mode | Model ignores or misapplies the procedure | Call errors, times out, or returns bad data |
The practical rule: reach for a skill when the agent needs to know how to do something it can already do with its existing tools. Reach for a tool or MCP server when the agent needs a new capability — to touch a system, run code, or fetch data it otherwise cannot reach. A well-designed skill often orchestrates existing tools; it does not replace them.
The Rifty take
We treat skills as the cheapest way to make an agent more capable without making it less legible. The thing we optimize for is a small, always-loaded index and detail that arrives only on demand — capability you can afford to keep because it is dormant until relevant. The tradeoff we accept is that a skill is advisory, not enforced: the model chooses to load and follow it, so a skill is where you put carried judgment, not where you put a hard boundary. Anything that must always hold belongs in a guardrail, not a skill.
Implementation checks
- Write the description line for retrieval, not for humans — it is the only part the model sees before deciding to load, so it must state precisely when the skill applies.
- Keep each skill single-purpose. A skill that does five things loads five things' worth of context and triggers on all of them.
- Version and diff-review skill folders like code; a capability change should be a visible change.
- Never encode a hard constraint in a skill alone. If violating it is unacceptable, enforce it in a guardrail or permission boundary the model cannot skip.
- Prefer skills that orchestrate existing tools over skills that reimplement a capability in prose.
- Watch for trigger collisions — several skills matching one task quietly inflate context and blur which procedure the agent actually followed.
Frequently asked questions
How is an Agent Skill different from a tool?
An Agent Skill injects instructions or domain knowledge into the model's context, teaching it how to do something; a tool exposes a callable capability the model invokes to act on an external system. Use a skill for know-how, a tool for reach. Skills often orchestrate existing tools rather than replacing them.
When should I put knowledge in a skill versus the system prompt?
Put knowledge in the system prompt when nearly every task needs it, and in a skill when only some tasks do. Skills keep task-specific procedures out of context until their trigger fires, so you avoid paying tokens and diluting attention for capabilities the current request will never use.
Can a skill enforce a rule the agent must not break?
No. A skill is advisory: the model decides whether to load and follow it, so it cannot guarantee compliance. Anything that must always hold belongs in a guardrail, permission boundary, or deterministic check the model cannot skip. Use skills for carried judgment, not for hard constraints.
What makes a skill description effective?
The description is the only part the model reads before deciding to load a skill, so write it for retrieval: state precisely which tasks the skill applies to. Vague descriptions cause missed loads or trigger collisions, where several skills match one task and quietly inflate context and blur behavior.
Do many skills slow an agent down?
Not while dormant. Only the short description of each skill stays in context, so a large library costs little until a skill is actually loaded. The real cost appears when overlapping triggers load several skills at once, so keep each skill single-purpose and its trigger specific.