Skills as an orientation map: how an agent loads expertise on demand

A general agent, and the wall of instructions

A capable general-purpose agent will do most things passably. Getting it to do your specialised work, your way — the house report format, the domain checklist, the procedure with the three non-obvious steps — is a different problem. The naive fix is to paste all of that into the prompt. It fails twice. Context is finite, so the procedures crowd out the actual task; and standing instructions are always on, competing for the model’s attention even when they are irrelevant to what you are doing right now. Past a certain size, a wall of instructions makes the agent worse at everything.

Agent Skills are the structured answer to that problem. The framing Anthropic uses is apt: building a skill is like writing an onboarding guide for a new hire, rather than re-explaining the job every morning.

What a skill actually is

At its simplest, a skill is a directory containing a SKILL.md file. That file begins with YAML frontmatter holding two required fields — name and description — followed by a body of instructions in plain Markdown. If the skill needs more, it can bundle extra files and scripts in the same folder and point to them from SKILL.md (overview).

That is the whole format. Anthropic ships pre-built skills for document work — PowerPoint, Excel, Word, PDF — and anyone can author custom ones; both work identically, and the agent uses them automatically when relevant (quickstart). The simplicity is the point: a skill is just files, which makes it easy to version, share, and audit.

The orientation map: progressive disclosure

The mechanism that makes skills scale is progressive disclosure, and it is best understood as a map rather than a manual. Information loads in three levels:

The first level is the map itself. At startup the agent pre-loads the name and description of every installed skill into its system prompt — just enough to know which skill to reach for, without loading any of them in full. Only when a skill looks relevant does the agent read its SKILL.md body (level two), and only when a specific sub-task demands it does it open a bundled file or run a script (level three) (engineering blog). Like a well-organised manual that opens with a table of contents, the agent never has to read every room to find the one it needs — which is exactly why a skill’s bundled content can be, in practice, unbounded.

The description is a router, not decoration

Here is the consequence people miss. The agent decides whether to use a skill almost entirely from its name and description, because at decision time that is all it has loaded. The description is therefore not marketing copy — it is a routing signal. It has to state both what the skill does and when to use it. A vague or generic description means the skill either never fires when it should, or fires for the wrong task and crowds out a better one. Anthropic’s own guidance is blunt about it: pay special attention to the name and description, because Claude uses them to decide whether to trigger the skill at all (best practices). Write the description from the trigger’s point of view, not the author’s.

Personal or professional — the same mechanism

None of this changes between contexts. At home, a skill might encode a personal writing voice, a recurring file-tidying routine, or the steps of some fiddly household-admin task. At work, it might hold a house report format, a compliance checklist, an onboarding runbook, or a domain procedure that must be done one specific way. The benefit is identical: capture the know-how once, and the agent applies it automatically instead of being re-briefed every time (overview). Because skills are just files, they sit naturally in version control, travel between people, and — since the format was published as an open standard in December 2025 — between tools as well.

Don’t overload the map

The discipline of skills is mostly the discipline of not overloading them, and there are two distinct ways to get it wrong.

The first is overloading the catalogue. Because every skill’s metadata sits permanently in the system prompt, a sprawl of skills with long, overlapping descriptions has a real, cumulative cost — and it muddies routing, leaving the agent to guess between three doors that all sound plausible. The fix is curation: few skills, sharp descriptions, distinct boundaries.

The second is overloading a single skill — cramming everything into one enormous SKILL.md. That defeats the whole design, because the entire thing loads at once the moment the skill triggers. The remedy is the structure the format was built for: keep SKILL.md lean, split rarely-used or mutually-exclusive material into separate bundled files, and push deterministic steps into scripts, since code is cheaper to run than to reason through and it behaves the same way every time (engineering blog).

It also helps to be clear about what a skill is not. A skill is reusable know-how; it is not a place to keep changing facts. Those belong in a separate memory layer, kept apart on purpose:

Known limits and constraints

A few hard edges are worth knowing before you build:

• name must be 1–64 characters, lowercase letters, numbers and hyphens only, and it must match the skill’s folder name or the skill won’t load (spec).
• description is capped at 1,024 characters and should state both what the skill does and when to use it (spec).
• Avoid angle brackets (< >) in the frontmatter — they can inject unintended instructions into the system prompt (spec).
• The catalogue tax. Level-1 metadata is always loaded, for every installed skill, whether or not you use it this session. The always-on cost scales with how many skills you keep installed — which is the real argument for a small, well-chosen set rather than a hoard.
• Skills are not memory. A skill is static; it remembers nothing between runs. Anything dynamic needs a separate memory mechanism (the diagram above).
• Runtime requirements. The unbounded-context benefit depends on the agent having a filesystem and code execution; in the API, skills run alongside the code-execution tool and its beta headers (quickstart).
• Security. A skill can carry and run code, so a malicious one can exfiltrate data or take unintended actions. Install only from trusted sources, and audit anything from a less-trusted one before use (overview).

The map, not the manual

A skill, done well, is a map and not a manual. Its job is to let the agent know which door to open without making it read the whole building first — and the craft is keeping that map small, legible, and honestly labelled. Overload it, in either direction, and you have quietly rebuilt the wall of instructions you adopted skills to escape.

Sources

• Anthropic, Equipping agents for the real world with Agent Skills (engineering blog).
• Claude Docs, Agent Skills — Overview.
• Claude Docs, Agent Skills — Quickstart.
• Claude Docs, Skill authoring best practices.
• Agent Skills open standard, Specification.