Agent Skills: why the best agents load their instructions lazily

Every team that builds an agent eventually writes the same document. It starts as a paragraph in the system prompt: how we write commit messages. Then how to run the test suite. Then how to file an incident, how our brand colours work, which Excel template finance expects. Six months later the system prompt is twelve thousand tokens, the agent is slower and more expensive on every request, and it still forgets the Excel rules because they are buried in the middle.

Agent Skills are the answer the industry converged on, and they are worth understanding even if you never write a SKILL.md file, because the idea underneath — progressive disclosure of context — applies to every agent you will build.

What a skill actually is

A skill is a folder. The only required file is SKILL.md:

---
name: quarterly-report
description: Builds the finance team's quarterly report workbook from a
  CSV export. Use when asked for a quarterly, Q1-Q4 or board finance report.
---

# Quarterly report

1. Validate the CSV with `scripts/validate.py` before doing anything else.
2. Use the template in `assets/template.xlsx`; never build sheets from scratch.
3. Revenue recognition rules are in `reference/revenue.md` — read it only
   if the export contains deferred revenue lines.
...

Everything else is optional: a scripts/ folder of code the agent can run, a reference/ folder of documents it can read, assets/ such as templates. The frontmatter needs a name and a description; the Markdown body is free-form instructions written for the model.

That is the entire format. Its power is in when each part gets loaded.

Three tiers of loading

Tier 1 — the menu. At startup the agent sees only the name and description of each installed skill. Fifty skills at a few dozen tokens each is a couple of thousand tokens — the size of a short email, not a novel.

Tier 2 — the recipe. When a request matches a description, the agent reads that skill’s SKILL.md. Now, and only now, the full instructions enter context.

Tier 3 — the pantry. The instructions can point at files. The agent reads reference/revenue.md only if the export has deferred revenue. It runs scripts/validate.py rather than reading it, so a 400-line validator costs only the tokens of its output.

The result is that the context an agent pays for scales with what the task needs, not with what the agent knows. That is the same principle behind good context engineering generally; skills make it a convention instead of a bespoke design.

Why scripts beat instructions for deterministic work

The quietly important part of the format is the scripts/ folder.

Language models are good at judgement and unreliable at procedures that must be exactly right every time: parsing a fixed-width file, validating a schema, computing a checksum, filling a template’s cells in a specific order. Written as prose, those steps get followed mostly. Written as a script, they get followed exactly, and the model only has to decide when to run it and what to do with the result.

That division of labour — model for judgement, code for procedure — is the single most reliable pattern for making agents dependable, and skills give it a standard home. It is the same reason code mode beats long tool chains for multi-step data work.

From one vendor’s feature to a standard

Anthropic introduced Agent Skills for Claude in October 2025 and published the format as an open specification in December 2025. Other agents adopted it quickly — OpenAI’s Codex, GitHub Copilot, Cursor and Gemini CLI among them — because the format asks almost nothing of the runtime. Any agent that can read files and run commands can implement the three tiers.

The practical consequence is portability. A skill your platform team writes once can be checked into a repository and used by whichever coding agent each engineer prefers, much as AGENTS.md files became a shared way to give coding agents project instructions.

The description is the whole game

Here is the part most teams get wrong. At tier 1, the description is the only thing the agent sees. If it does not match the way users phrase requests, the skill is never loaded, and the agent silently does the task its own way.

Compare:

# Invisible
description: Finance helper.

# Findable
description: Builds the finance team's quarterly report workbook from a
  CSV export. Use when asked for a quarterly, Q1-Q4 or board finance report.

The second says what it does, on what input, and when to use it, in the words a user would actually type. Treat descriptions the way you would treat tool descriptions in a large tool catalogue: they are retrieval keys, and they deserve the same testing.

Tier 1. If the skill never loads, nothing in its body matters yet — the description failed to match. Write five realistic user requests, check which ones trigger the skill, and rewrite the description until they all do.

Writing skills that hold up

A few habits separate skills that work from skills that rot:

• One job per skill. A skill that covers “all finance tasks” has a description too vague to match well and a body too long to follow.
• Keep the body short; push detail down a tier. Put the common path in SKILL.md and the rare cases in reference files the body points to conditionally.
• Make scripts the source of truth for anything exact. If a rule can be checked by code, check it with code.
• Test triggering, not just execution. Keep a list of requests that should and should not load each skill, and run it when you change a description.
• Review skills like code. A skill’s instructions and scripts run with the agent’s permissions. A skill from an unknown source is third-party code and should be reviewed the same way — the prompt injection risks of untrusted text apply directly to untrusted instructions.

What to take away

• A skill is a folder: SKILL.md with a name, a description and instructions, plus optional scripts, references and assets.
• Progressive disclosure is the point: descriptions always, bodies on match, files on demand. Context cost tracks the task, not the catalogue.
• Skills carry know-how; tools carry capability. Use both.
• Put exact procedures in scripts; let the model decide when to run them.
• The description decides whether a skill exists at all. Test it.

To see how skills fit alongside AGENTS.md files and tools in a working setup, the lesson on AGENTS.md, skills and tools walks through all three.