Skills: On-Demand Specialization
Skills inject domain expertise into an agent on demand via progressive disclosure — keeping the context window lean while giving the agent access to deep knowledge across many domains. This article covers when to use skills over subagents and tools, the full SKILL.md specification, derivable context budget math, how skills fail in production, and how to evaluate skill activation.
Quick Reference
- →Skills are prompt + knowledge bundles, not separate agents — the calling agent stays in control
- →Three disclosure levels: metadata always loaded (~100 tokens), body on activation (~2K tokens), bundled resources on demand
- →SKILL.md frontmatter controls activation: description and when_to_use are what the model reads to decide
- →Context math: 20 skills fully loaded = ~30K tokens; with disclosure = ~5K tokens — 83% savings
- →Skills fail in four ways: wrong activation, stale content, context overflow, compaction loss — each has a specific defense
- →Test skill activation with trajectory evaluations before shipping to production
- →Claude Code follows the Agent Skills open standard — skills port across compliant tools
- →After /compact, Claude Code preserves the first 5K tokens of each invoked skill (25K combined budget)
Should You Use Skills?
Knowing how → Skills · Doing in isolation → Subagents · Deterministic → Tools · Persistent facts → Memory
Before building a skill, ask: is the capability about knowing how to do something, or about doing something? Skills answer the first question. They inject procedural expertise — SQL conventions, API design patterns, security checklists — into an agent that already has the tools to act. If the agent needs to act independently, without access to the conversation history, use a subagent. If it needs to execute a deterministic function, use a tool.
| Scenario | Right pattern | Why skills are wrong |
|---|---|---|
| SQL query conventions, index strategies | Skills | — |
| Security review checklist for this codebase | Skills | — |
| Research task needing isolated web search | Subagents | Needs context isolation, not expertise injection |
| Calling an external API to fetch data | Tools | Deterministic — not a knowledge question |
| Running parallel data-processing jobs | Subagents | Concurrent execution, not domain knowledge |
| Facts that must persist across all sessions | Memory (CLAUDE.md) | Skills are per-session, not persistent |
Don't use a skill if the guidance is short enough to live permanently in the system prompt (<200 tokens). Don't use a skill for stateful operations — skills inject knowledge, they don't maintain state. Don't use a skill to wrap a tool call — use a tool. And don't use skills when you need true context isolation: if a subtask must not see the conversation history, use a subagent.