Context Engineering in Claude Skills
Anthropic's Claude Skills mechanism — a 3-layer context system that lets an agent use hundreds of specialized workflows without overloading its context window.
▶📚 Prerequisites(1)
🎓 Learning objectives
- •Explain the problem Claude Skills solves: reusable agent abilities without restating instructions every time
- •Describe the 3-layer context system (Main Context, Skill Metadata, Active Skill Context) and its token cost per layer
- •Explain the anatomy of a skill (skill.md, YAML frontmatter, supporting files) and how to build one
- •Describe how Skills complement (rather than replace) Projects, MCP, and Subagents
What is it?
Claude Skills are Anthropic's mechanism for giving agents reusable, persistent abilities without overloading the model's context window. They solve a very practical problem in agent design: LLMs forget everything unless all instructions, examples, and edge cases are restated every single time. Skills package this information into small, self-contained units that Claude loads only when they're relevant, letting an agent draw on hundreds of specialized workflows while keeping its active context lightweight.
Why it exists
Without Skills, every specialized capability an agent needs has to be either baked into an ever-growing system prompt (which eventually exceeds context limits and dilutes attention across too much irrelevant material) or re-explained fresh each time it's needed (wasteful and error-prone). Skills exist to let you define a workflow once — its steps, examples, constraints, edge cases — and reuse it forever, loaded into context only at the moment it's actually relevant, rather than sitting in every prompt regardless of whether it's needed.
Problem it solves
It solves the scalability problem of agent instructions: without Skills, an agent that needs to know 50 different specialized procedures either can't fit them all in context, or pays the token cost of all 50 on every single request regardless of which one (if any) is actually relevant. Skills solve this by making the cost of 'knowing about' a skill nearly free (just its lightweight metadata, ~200 tokens) while the expensive full instructions only load when the skill is actually invoked — this is what makes hundreds of skills coexist without breaching context limits.
Intuition
Think of Skills like a library of standard operating procedure (SOP) binders on a shelf. You don't memorize all 200 SOPs before starting your shift — you just need to know the shelf exists and roughly what each binder's spine label says (the lightweight metadata). The moment a task matches a specific SOP, you pull that one binder off the shelf and read the full procedure (the active skill context) — the other 199 binders cost you nothing until you need them too.
Analogy
It's like the difference between a doctor trying to memorize every possible diagnosis and treatment protocol in medical school (impossible, and irrelevant most of the time) versus a doctor who knows which reference manual to pull off the shelf for a specific symptom pattern, reads just that chapter, and applies it. The doctor doesn't carry the entire medical library in active working memory at all times — only the specific, relevant chapter, loaded exactly when needed.
Technical explanation
The 3-layer context management system works as follows: Layer 1 (Main Context) is always loaded and contains the project configuration — the baseline context every interaction has regardless of skills. Layer 2 (Skill Metadata) comprises only the YAML frontmatter of each available skill, about 2-3 lines and under 200 tokens per skill — this is what Claude scans to decide which skill(s), if any, are relevant to the current task, and its low cost is what allows hundreds of skills to coexist. Layer 3 (Active Skill Context) loads the full SKILL.md file and associated documentation, but only for the skill(s) actually deemed relevant and activated — everything else stays dormant. Supporting files like scripts and templates aren't pre-loaded even within an active skill; they're accessed directly when actually used, consuming zero tokens until that point. This architecture is what supports hundreds of skills without breaching context limits.
A skill's anatomy: a skill is simply a folder containing a skill.md file with two internal layers of its own — YAML Front Matter (a tiny descriptor Claude uses to decide relevance, corresponding to Layer 2 above) and the Skill Body (the detailed instructions, workflows, examples, and guidance used during actual execution, corresponding to Layer 3). Optionally, a skill folder can include supporting files (scripts, templates, reference docs) that aren't loaded into context but fetched only when the agent actually needs them.
How Skills fit the broader agent architecture: Skills don't replace Projects, Subagents, or MCP — they complement them. Projects organize your workspace; MCP connects Claude to tools and external services; Subagents handle delegated reasoning; Skills package the reusable expertise that all of the above can rely on. Each solves a different layer of the agent problem, with Skills specifically serving as the procedural knowledge base.
Architecture
A Claude Skills-enabled agent has: a Main Context layer (always loaded, project-level configuration), a Skill Registry (the set of available skills, each contributing only its lightweight YAML-frontmatter metadata to context by default), an Activation mechanism (Claude scanning available metadata to decide which skill(s) are relevant to the current task), and, once activated, a full-context load of that specific skill's SKILL.md body plus on-demand (not pre-loaded) access to any supporting files. This sits alongside, not in place of, Projects (workspace organization), MCP (external tool/service connectivity), and Subagents (delegated reasoning).
Workflow
- Identify a workflow you repeat constantly — a recurring task with steps, examples, constraints, and edge cases that would otherwise need re-explaining every time.
- Create a skill folder and add a skill.md file inside it.
- Write the YAML front matter (the lightweight descriptor Claude uses to decide when this skill is relevant) plus the full markdown instructions (the detailed body used once the skill is activated).
- Add any supporting scripts, examples, or reference resources as additional files in the folder — these won't be pre-loaded into context.
- Zip the folder and upload it into Claude's capabilities (or use Claude Desktop's built-in 'Skill Creator' skill, which helps generate this structure for you).
- Test that the skill activates correctly for relevant tasks and stays dormant (near-zero context cost) for unrelated ones.
Example
File structure of a skill folder:
commit-message-style/
skill.md
examples/good_commits.txt
── skill.md ──
SKILL_MD = '''
name: commit-message-style description: Use when writing a git commit message for this repo — enforces our Conventional Commits style with a 50-char subject and a 'why' body.
Commit Message Style Guide
When writing a commit message:
- Subject line: (): , max 50 chars
- Leave a blank line
- Body: explain WHY the change was made, not what changed (the diff shows what)
- Reference the ticket number if applicable
See examples/good_commits.txt for real examples from this repo. '''
Only the YAML frontmatter (~40 tokens here) is loaded by default (Layer 2).
The full body + examples/good_commits.txt only load (Layer 3) when Claude
decides this skill is relevant to the current task — e.g., when asked to
write a commit message for this specific repo.
Real-world usage
Anthropic ships Claude Desktop with a built-in 'Skill Creator' skill specifically to help users generate the skill.md structure for their own custom skills, lowering the barrier to building the first one. Teams standardizing on Claude for internal workflows (code review conventions, report-writing templates, customer-response formats) use Skills to encode 'how we do things here' once and have it apply consistently across every relevant interaction, instead of re-pasting the same instructions into every conversation. Because Skills coexist cheaply (just ~200 tokens of metadata each when inactive), organizations can build out large skill libraries — dozens or hundreds of specialized procedures — without the context-budget concerns that would come from trying to fit the same information into an ever-growing system prompt.
Trade-offs
Skills trade a small one-time authoring cost (writing the skill.md, deciding what belongs in metadata vs. body) for near-zero ongoing context cost when a skill isn't relevant, and full, rich context when it is. This is a clear win over the alternative of either omitting the capability entirely or paying its full token cost on every single request regardless of relevance. The tradeoff shows up mainly in authoring quality: a skill with a vague or overly broad YAML description may activate when it shouldn't (false positive) or fail to activate when it should (false negative) — the quality of the metadata layer directly determines how well the whole system works.
Visual explanation
A 3-layer stack diagram.
Layer 1 (bottom, always present): [Main Context] — project configuration, always loaded regardless of which skills exist.
Layer 2 (a thin band above it): [Skill Metadata] — for every available skill, just its YAML frontmatter (2-3 lines, under 200 tokens) — cheap enough that having hundreds of these doesn't meaningfully cost context.
Layer 3 (loaded conditionally, shown as dashed/optional boxes): [Active Skill Context] — the full SKILL.md and associated documentation, loaded only for the specific skill(s) actually relevant to the current task; supporting files (scripts, templates) aren't even pre-loaded at this layer — they're accessed directly when in use, consuming zero tokens until touched.
Advantages
- —
Lets an agent draw on hundreds of specialized workflows while keeping active context lightweight (~200 tokens metadata per dormant skill)
- —
Solves the 're-explain everything every time' problem by packaging a workflow once and reusing it indefinitely
- —
Cleanly complements (rather than duplicates or conflicts with) Projects, MCP, and Subagents — each handles a distinct layer of the agent problem
- —
Supporting files (scripts, templates) cost zero tokens until actually accessed, keeping even large skills cheap when dormant
Disadvantages
- —
Requires upfront authoring effort to write clear YAML frontmatter and a well-structured skill body
- —
Poorly-written metadata (too vague or too broad) can cause incorrect activation — either missing relevant skills or triggering irrelevant ones
- —
Skills are Anthropic/Claude-specific, so this exact mechanism doesn't directly transfer to other model providers
- —
Managing a large skill library still requires organizational discipline to avoid duplicate, outdated, or conflicting skills over time
Common mistakes
- —
Writing overly vague or overly broad YAML frontmatter descriptions, causing the skill to activate for irrelevant tasks or fail to activate for relevant ones
- —
Putting the entire skill body's content into the YAML frontmatter instead of keeping Layer 2 lightweight and detail in Layer 3, defeating the token-efficiency purpose of the 3-layer split
- —
Bundling large reference data directly into the skill.md body instead of as a separate supporting file, unnecessarily inflating the cost of the active-skill layer
- —
Treating Skills as a replacement for MCP, Projects, or Subagents rather than understanding they solve a different, complementary problem (reusable procedural knowledge, not tool connectivity or workspace organization)
- —
Never testing a new skill's activation behavior on both relevant and irrelevant tasks, missing false-positive or false-negative activation issues before deployment
📂 Subtopics
Layer 1: Main Context — The Problem Skills Solve
Skills exist to fix a specific problem: LLMs forget everything unless instructions are restated each time. Layer 1, Main Context, is the always-loaded foundation everything else builds on.
~12 min
Layer 2: Skill Metadata — The Cheap, Always-Scanned Descriptor
Layer 2 is just the YAML frontmatter of every skill — 2-3 lines, under 200 tokens — cheap enough that Claude can scan ALL of a project's skills every turn to decide relevance.
~11 min
Layer 3: Active Skill Context — Full Instructions, Loaded On Demand
Layer 3 loads a skill's full SKILL.md body only once it's been selected as relevant — and supporting files (scripts, templates) go further still, never entering context at all until actually invoked.
~13 min
Practical Implementation: Building Skills and Fitting Them Into the Agent Architecture
The book's 5-step process for building your own Skill, and how Skills complement — rather than replace — Projects, MCP, and Subagents in a real agent architecture.
~13 min