SKILL.md Isn't a Prompt File, It's Lazy Loading for Agents

SKILL.md Isn't a Prompt File, It's Lazy Loading for Agents

Something odd happened between October 2025 and now. Anthropic shipped Agent Skills on October 16, 2025 as a Claude feature. Two months later it published the format at agentskills.io as an open standard. OpenAI and Microsoft added support within roughly 48 hours. Cursor 2.4 picked it up in January 2026. By now AgentAtlas counts 45-plus compatible products, governance sits with the Linux Foundation's Agentic AI Foundation, and skill repos like mattpocock/skills are pulling five-figure daily stars on GitHub trending.

Most developers still read a skill as a fancy prompt file. That reading misses the design. A skill is lazy loading applied to agent context, and once you see it that way, every quirk of the format starts making sense.

The format in sixty seconds

A skill is a folder containing a SKILL.md file. The file opens with YAML frontmatter. Two fields are required: name (1 to 64 characters, lowercase letters, digits, and hyphens only, matching the folder name exactly) and description (up to 1024 characters, covering both what the skill does and when to use it). Optional fields add a license, a compatibility note listing required CLIs like git or docker, a metadata map, and an experimental allowed-tools list that pre-approves specific tool calls. Support for allowed-tools varies by client, so treat it as a bonus.

The body after the frontmatter is plain Markdown with no format restrictions: step-by-step instructions, worked examples, edge cases. The folder can also carry three optional subdirectories: scripts/ for self-contained executables, references/ for on-demand documentation, and assets/ for templates and schemas.

Progressive disclosure is the whole point

The specification defines three loading stages, and they map cleanly onto how a lazy-loading module system works.

• Discovery. At startup the agent loads only each skill's name and description, roughly 50 to 100 tokens per skill. Fifty installed skills cost about 5,000 tokens, a rounding error in a modern context window.
• Activation. When a task matches a description, the agent reads the full SKILL.md body into context. The spec recommends keeping the body under 5,000 tokens and 500 lines.
• Execution. Files in references/ and assets/ load only when the instructions call for them. Scripts are the clever part: the agent can run a bundled utility and consume its output without the source code ever entering the prompt.

The survey paper on agent skills (arXiv 2602.12430) uses the analogy of an onboarding guide: level one is the table of contents, level two the chapter, level three the technical appendices. A skill with 50KB of reference documentation costs almost nothing until it fires.

Two consequences fall out of this that people keep getting wrong. First, the description field is not a summary, it is a routing function. It is the trigger text every agent reads at startup to decide whether to pay the activation cost. "A skill for commits" wastes it. "Generate semantic commit messages from staged changes. Use when committing code." tells the agent exactly when to load. Second, the budgets are enforced. Codex caps its initial skills list at 2% of the context window, or 8,000 characters when the window is unknown, so bloated descriptions get truncated and entries in large skill sets can be dropped entirely. A self-indulgent description doesn't just waste tokens, it can silently make your skill invisible.

Skills are not function calls

The distinction matters more than the marketing suggests. A function call produces a result. A skill changes the agent's preparation. When a skill activates, its instructions get injected into the conversation as a hidden message that the model sees but the user interface doesn't render, and the execution context shifts so pre-approved tools come online before the model generates anything. A tool answers a question; a skill reshapes what the agent knows and can do before it answers. That's why a perfectly useful skill can be pure Markdown with zero code in it.

Where each agent looks

Here's the part that will annoy you. The standard doesn't dictate a single discovery path, so the big three disagree.

The community workaround is one canonical copy at .agents/skills with the client paths symlinked back to it. Vercel's skills CLI automates the linking (skills install --agent claude-code --scope project --link, with copy or symlink modes). Before you link anything anywhere, run skills-ref validate against the frontmatter and wire that command into CI. A contributor's malformed name or over-length description otherwise drifts across three mirrored directories and fails silently in exactly one agent.

The spec carries one warning that reads like folklore but isn't: avoid XML angle brackets in frontmatter, because they can inject unintended content into the system prompt.

What belongs in a skill

The Red Hat framing of AGENTS.md versus skills is the cleanest test I've found. AGENTS.md is always-on project context, the README-for-agents: how to install, where the tests live, how to run them. Skills are situational knowledge. So the triage goes like this.

• A rule that must apply to every change never belongs behind an optional activation path. If it matters always, it lives in AGENTS.md or the system prompt. A skill the agent forgot to load enforces nothing.
• Situational procedures are the sweet spot: reviewing database migrations, incident triage runbooks, release preparation, a house style for commit messages.
• Inside the skill, always-needed steps go in the body, deep detail goes in focused reference files (agents load them on demand, so smaller files mean less context burned), and deterministic work belongs in scripts where the output, not the source, is what costs tokens.

The security note nobody should skip

A skill can contain instructions that steer tool use plus executable code that runs in your environment. Anthropic recommends auditing unfamiliar skills the way you'd audit a dependency, including bundled code and any network access the instructions assume. OpenClaw puts it blunter: treat third-party skills as untrusted code. A skill is an instruction mechanism, not a security boundary, and the ecosystem's skill marketplaces are exactly the kind of supply chain that deserves the paranoia.

When to skip the format

Knowledge for one prompt is a prompt, not a skill. A rule that applies to every change is AGENTS.md material. Logic that must run the same way every time is a function call, not prose. The format earns its keep when knowledge is situational, deep enough to hurt to re-explain, and reused across repos or agent products.

I keep coming back to the lazy-loading framing because it predicts the format's rules before you read them. Descriptions are import statements, so make them precise. The body is the module, so keep it small. References are the lazy chunks. Scripts are native bindings, run rather than read. Treat SKILL.md like a module system and the token math takes care of itself. Treat it like a prompt folder and you'll end up with a 900-line file that either never fires or burns a fifth of the window when it does.