Here's a frustration anyone who works with AI agents knows well: every conversation starts from zero. The model doesn't remember how your team does code review, what your design system rules are, or the workflow you painstakingly explained yesterday. And the usual fix — stuffing all of that into one giant system prompt — makes things worse as it grows, because a bloated prompt dilutes the model's attention. SKILL.md is a genuinely clever answer to this, and I think it's one of the more important ideas in agent tooling right now.
The idea in one line
A SKILL.md is a standardized markdown file that packages domain expertise, a workflow, and its rules into a modular, reusable unit — a "skill." Instead of one enormous prompt, you build a library of focused skills the agent can pull from when they're relevant.
Think of it as the difference between briefing a new hire with a single 40-page document they must memorize, versus giving them a well-organized handbook they consult one section at a time. The second scales. The first doesn't.
Progressive disclosure: the key trick
The mechanism that makes this work is progressive disclosure — the agent only loads what it needs, when it needs it. Skills are structured in tiers:
- Tier 1 — a tiny bit of YAML metadata (name + description), maybe 30–100 tokens, always loaded. This is how the agent knows the skill exists.
- Tier 2 — the actual instructions and procedures, loaded only when a task matches the skill. Kept under ~5,000 tokens.
- Tier 3 — heavier resources (scripts, templates) pulled in only during active use.
The payoff is that your context window stays lean. The agent isn't carrying the weight of fifty skills at once; it's carrying the metadata of fifty and the full text of the one it's using. That avoids what people call "context poisoning" — where too many instructions actually degrade the model's reasoning.
Where it earns its keep
The examples that made it click for me are the ones that enforce discipline, not just supply knowledge:
- Test-driven development — a skill that refuses to let the agent write implementation before a failing test exists. Red, green, refactor, enforced mechanically.
- Design system compliance — a skill that makes the agent stick to your Tailwind utility classes and blocks one-off styles, which is essential the moment multiple agents touch the same UI.
- React performance — codified expert patterns for spotting needless re-renders and bundle bloat.
- Writing quality — hard rules like "no sentence over 25 words," turning vague "make it clearer" into something checkable.
The common thread: skills encode not just what an expert knows, but the procedure they follow. That's the "procedural memory" part, and it's why the results are more consistent than prompting.
Build skills like you build software
The part I appreciated most is that you're meant to develop skills using TDD: find a case where the agent fails without the skill (RED), measure the gap to the expert outcome, write instructions to close it (GREEN), then refine against edge cases (REFACTOR). A skill isn't "done" until it reliably bridges that gap. Treating prompts-as-artifacts you test, rather than magic incantations you tweak by vibes, is exactly the right instinct.
Skills know; tools do
One clarification worth making: a skill is knowledge and instructions, not execution. Pair it with tool integrations — a browser driver, a static analyzer, a math engine — and you get a two-part system: the skill is the brain, the tool is the hands. That combination is where the "automated QA loop" kind of magic actually comes from.
Why this matters
The mental shift here is the real takeaway. With a system prompt, you're chatting with a bot. With a well-built library of skills, you're configuring a colleague — one whose expertise persists, composes, and improves over time. For anyone trying to get reliable, repeatable work out of agents instead of one-off lucky outputs, that's the difference that counts.
