Claude Skills and progressive context disclosure as a real engineering pattern, not prompt engineering
Claude Skills Are Not Prompt Engineering. Stop Treating Them That Way.
I’ve spent the last year building agents, and I keep watching developers make the same mistake. They discover Claude Skills, read the YAML frontmatter, see the instruction blocks, and immediately think: “Oh, this is just a fancier way to write a system prompt.” Then they proceed to dump everything into context anyway. Every edge case. Every contingency. Every rule they can think of. The model bogs down and they wonder why performance degrades.
That’s not a model problem. That’s an architecture problem.
The Real Pattern: Progressive Context Disclosure
Anthropic’s guide “The Complete Guide to Building Skills for Claude” outlines something that deserves more attention from engineers who build seriously with LLMs. The pattern they describe is progressive context disclosure. A lightweight YAML header tells Claude when a skill applies. Full instructions load only when relevant. Additional reference files pull in only if needed.
This is not prompt engineering. This is information architecture. The distinction matters more than most people realize.
The Failure Mode Nobody Talks About
Here’s what I’ve seen consistently in production agent systems: premature context saturation. You write an exhaustive system prompt because you’re afraid the model will miss something. So you cover every case. The model reads all of it, and paradoxically, performance on the common case gets worse, not better. The signal drowns in the noise you added to protect against edge cases that may never trigger.
Andrej Karpathy described something adjacent to this when writing about his multi-agent nanochat experiments. His agents, even at high intelligence settings, struggled not because they lacked capability but because they lacked well-scoped, properly structured instructions. They ran nonsensical variations and missed obvious baselines. The problem wasn’t the model. It was how information was being fed to it.
Skills as Infrastructure, Not Spells
The analogy in Anthropic’s guide is worth quoting directly. MCP gives Claude the kitchen. Skills give it the recipe. Without a skill attached, a user might connect tools and have no idea what to do next. With a properly designed skill, workflows trigger automatically, best practices are embedded in the execution path, and API calls stay consistent across runs.
The guide outlines three major patterns where this shows up in practice: document and asset creation, workflow automation, and MCP tool enhancement. What ties all three together is that the skill functions as an execution layer, not a conversation starter.
This reframes how I think about what I’m actually building when I write agent logic. I’m not writing prompts. I’m writing a specification for an information system that controls what the model sees and when it sees it.
Testing Is the Part Everyone Skips
The guide emphasizes four concrete metrics that most teams track poorly or not at all: trigger accuracy (does the skill activate when it should?), tool call efficiency (is the model taking unnecessary steps?), failure rate, and token usage. These are software engineering metrics applied to context management. That framing is correct and I wish more teams adopted it from day one rather than retrofitting observability after something breaks in production.
Skills built this way also have a genuine deployment advantage. Build once, deploy to Claude, Claude Code, or directly through the API. The structure travels with the behavior.
Where This Goes
Karpathy framed the multi-agent case well: you are now programming an organization, and the source code is the collection of skills, prompts, tools, and processes that make it up. The daily standup becomes part of the org’s code. Optimization tasks become evals. That mental model scales. What doesn’t scale is treating every new agent capability as a prompt to be rewritten from scratch.
The engineers who figure out progressive context disclosure as a first-class design pattern, not an afterthought, are going to build systems that are faster, cheaper to run, and dramatically easier to debug. The engineers who keep writing longer and longer system prompts are going to hit a wall that no model upgrade will fix for them.
Sources
#AIEngineering #LLMs #AgentDesign #ClaudeAI #MLEngineering
