A common production failure mode is that an agent with a very large context window — for example 200k tokens — still ignores the exact instructions it needed. In the example given, the required 400-token instruction was buried at position 142k behind six tool definitions, four reference docs, and a brand guide no one asked it to read. The root cause is typically that the prompt got too big and the important content was buried.
The proposed fix is skills: a simple, file-based approach that decides where context lives and when it loads. This isn't about a bigger model, a larger window, or a smarter retriever; it's about design decisions that keep context organized and loaded on demand.
A skill folder as the unit
A skill is not a Python class or a registered tool; it's a folder on disk that must contain a single required file: SKILL.md. Everything else is optional: references (docs the agent can read on demand), assets (templates and brand files), and scripts (code the agent can execute). Because a skill is just files, you version it in Git, diff it in pull requests, copy it between projects, and publish it on GitHub. The format is the contract.
The same SKILL.md works across multiple runtimes: Claude Code, Codex, Gemini CLI, Cursor, Agent Development Kit, LangChain, and a growing list of agent tools and frameworks. One folder, many runtimes.
The first two lines are the search index
Every SKILL.md begins with YAML frontmatter containing two fields: name and description. These are not mere metadata — they form the search index. At session start, the agent loads the name and description of every installed skill, roughly 100 tokens per skill. The body, the references, and the scripts stay on disk.
When a request arrives, the model reads its own catalog and decides which skill to open based on the description. If you write a vague description the skill never fires; if you write a sharp description with concrete trigger words the skill activates precisely when needed. This single short line is often the most important bit of writing in the whole skill.
Progressive disclosure is the core trick
A single skill can contain tens of thousands of tokens of instructions and reference material. An agent with twenty skills could carry hundreds of thousands of tokens — multiple full context windows of dead weight before the user has even typed. Progressive disclosure prevents that with three loading tiers:
- L1 metadata: name and description. Always loaded at session start. Roughly 100 tokens per skill.
- L2 instructions: the body of SKILL.md. Loaded only when the description matches a user task. Usually a few thousand tokens.
- L3 references: files in references/, assets/, and scripts/. Loaded only when the L2 instructions explicitly point the agent there.
With this pattern, an agent with twenty skills pays the same upfront cost as an agent with one. Add a 21st skill tomorrow and yesterday's tasks cost what they cost yesterday. The caveat: progressive disclosure only saves tokens if you actually use the tiers. Stuff every example into SKILL.md and the body balloons to 10k tokens — now every task that triggers the skill pays that cost. Keep SKILL.md short and push edge cases, long examples, and reference tables into references/ so the agent pulls them only when needed.
The agent routes the query
When a request comes in, the model inspects the catalog and chooses the right tool — like reading labels on a toolbox, picking the correct drawer and opening it. Example: a user asks, “clean up this messy CSV and dedupe rows.” The model scans the catalog of descriptions: pdf-forms and brand-voice register low match; data-clean: CSV cleanup, dedup, nulls registers a strong match. The data-clean body loads and work begins.
Two details matter:
- The match is not vector retrieval. The model decides directly from descriptions inside its own context. There is no embedding step, no similarity score, and no separate routing layer. The LLM is the router.
- The match is exclusive. Only one skill activates per task; the others stay at L1. Their bodies never enter the context window. The cost of skills you do not need is essentially zero.
This is what differentiates skills from MCP tools or function calls, which are typically always loaded, always visible, and always paid for. Skills load only when relevant.
Composition without context bloat
Scale the idea up: one agent with eight skills installed and three different tasks across a session. The unused skills remain at L1, costing roughly 100 tokens each; the body cost is incurred only for tasks that require it.
The pattern also matters for team organization. Teams can ship skills independently: the data team owns data-clean and sql-runner, the design team owns brand-voice and deck-build, and the platform team wires up the agent. No central coordination, no merged prompts, no rebuilding of the system prompt every time a new capability lands.
The author compares skills to npm for JavaScript: small, focused, composable units behind a clear interface. The package manager won JavaScript; the same shape is argued to be likely to win for agents.
Practical recommendation
If you build agents and haven't written a skill yet, pick one recurring workflow and create a skill for it: one folder, one SKILL.md, version it in Git. Watch the agent activate it. The format is just files, but the leverage is large.
In short: structure context as files and load them in tiers so the model's routing can surface the right instruction when needed, preventing important 400-token prompts from being lost in a 200k-token window.
