What a Skill Is and When It's Worth Building One#

TL;DR#

A skill is a self-contained, independently-triggerable packet of instructions (plus, optionally, supporting files, scripts, or reference material) that an agent discovers cheaply and loads in full only when its trigger condition matches the current task - a concrete implementation of the always-loaded/on-demand split (lesson 03) and progressive disclosure applied specifically to recurring, describable pieces of know-how. It's worth building one when a need recurs across tasks, is expensive to reconstruct from scratch each time, and can be captured well enough in a trigger description that the agent will actually find it (lessons 04-05) - not for one-off needs, and not for things better solved by a different primitive entirely (lesson 11 covers that comparison in full).

The idea#

By this point in the subject, three things are already established: the scaffolding surface has many places an agent reads instructions from (lesson 01), structured metadata is a cheap way to signal what a resource is about before committing to loading it in full (lesson 02), and a well-run system draws a deliberate line between what's always loaded and what's deferred (lesson 03), governed by trigger descriptions that can fail in patterned ways (lessons 04-05) and by writing that survives being read independently and out of order (lesson 06). A skill is where all of that lands as a concrete, buildable unit: it is the packaging format for "a piece of know-how the agent doesn't need most of the time, but needs completely and correctly some of the time."

The problem a skill solves is specific: an agent's baseline behavior - its training, plus whatever's always loaded - is necessarily generic, because the always-loaded budget is small (lesson 03) and has to serve every task, not just this one. But real work is full of narrow, recurring needs that are too specific to earn a permanent slot in the always-loaded core and too important to leave to the agent's untrained improvisation every single time: a house style for writing commit messages, a checklist for reviewing a specific kind of change, a multi-step procedure for a task that has a right way and several subtly-wrong ways to do it. Without a shared, loadable unit for this, an engineer either repeats the same guidance in every prompt (expensive, error-prone, easy to drift out of sync across prompts) or leaves the agent to reconstruct the right approach from first principles every time (inconsistent, and wrong exactly as often as the task is subtle). A skill is the answer: write the guidance once, attach a trigger description cheap enough to always keep in view, and let the agent pull in the full guidance only on the tasks that actually need it.

How it works#

The shape of a skill: metadata, body, and supporting material#

A skill's structure follows progressive disclosure in three tiers, mirroring the always-loaded/on-demand split from lesson 03 but applied within a single unit rather than across the whole scaffolding surface: 1. Metadata (always cheap, always visible). A name and a short description - typically on the order of a sentence or two - that the agent can hold in view alongside every other skill's metadata without materially denting the context budget. This tier's entire job is to let the agent decide, cheaply, whether the full skill might be relevant (this is exactly lesson 02's "structured metadata as cheap signal" applied to skills specifically, and lesson 04's trigger-description design governs how well this tier does its job). 2. Body (loaded on trigger). The actual instructions - loaded in full only once the agent judges, from the metadata, that this skill applies to the current task. This is where the substantive guidance lives: the steps, the constraints, the worked patterns. 3. Supporting files (loaded only as needed, and only some of them). Reference material, templates, or scripts that the body can point to but that don't need to load just because the skill triggered - a skill whose body says "for the exact current syntax, see reference.md" only pays the cost of loading reference.md on the (possibly rare) occasions a task actually needs that level of detail. Lesson 08 covers deciding what belongs at which tier in practice.

A skill is not the same thing as a tool, and not the same thing as raw ambient instructions#

It's worth being precise about the boundary, because the three are easy to conflate: - A tool extends what an agent can do - it's a capability (call an API, run a query, edit a file) that the agent invokes and that returns a result back into the loop. A skill doesn't add a capability; it adds knowledge about how to use existing capabilities well for a specific recurring situation. A skill might tell an agent how to structure a database migration; the actual run_sql tool that executes it is a separate, capability-granting primitive. - Raw always-loaded instructions (the top tier of lesson 03's split) are guidance the agent has in view on every single task, whether relevant or not. A skill is deliberately not that - its entire value proposition is staying out of context until it's actually relevant, trading a small discovery cost (the always-visible metadata) for a large savings (not paying the full body's token cost on the vast majority of tasks that don't need it). - Lesson 11 works through the full comparison against hooks and commands as well, once those primitives have been introduced (lesson 10); this lesson's job is narrower - establishing what a skill specifically is, in contrast to the two primitives most commonly confused with it.

Deciding whether a need is worth packaging as a skill#

Three questions, applied together, separate a good skill candidate from a need that should stay as an ad hoc prompt or be solved a different way entirely:

Does it recur? A need that comes up once isn't worth the authoring and maintenance cost of a standalone, independently-triggered unit - just say it once, in the prompt, for that one task. A need that recurs across many tasks or many sessions is worth packaging, because the authoring cost amortizes.
Is reconstructing it from scratch expensive or error-prone? Some recurring needs are trivial for a capable agent to get right without help every time ("use present tense in commit messages" - most agents already lean this way from training). Others are specific enough, or counter-intuitive enough, that an agent reliably gets them wrong or inconsistent without explicit guidance (a house-specific migration safety rule that contradicts the generically "normal" way to write a migration). The second kind is what skills are for; the first kind doesn't need one.
Can the need be captured in a trigger description well enough that the agent will actually find it? This is where lessons 04-05 come back in directly - a skill that can't be described with a trigger tight enough to avoid over/under-triggering, and distinct enough to avoid colliding with a neighboring skill, will underperform its own authoring cost no matter how good its body is. A recurring, expensive-to-reconstruct need with no clean triggering story is a sign the guidance might belong somewhere more reliable than model-judged triggering - a deterministic lever instead (lesson 10 covers this alternative directly).

Anthropic's own guidance for building its internal library of skills (documented in its 2025-2026 engineering writing) describes essentially this same evaluation loop in practice: run the agent on representative tasks, observe where it struggles or improvises inconsistently without help, and only then build a skill to close that specific, observed gap - rather than pre-emptively packaging every plausible piece of knowledge as a skill regardless of whether a real gap was ever demonstrated.

Worked example: a candidate that clears the bar#

A team notices that every time an agent is asked to add a new field to a public API response, it sometimes adds the field directly to the existing response version and sometimes creates a new versioned endpoint - inconsistently, without a clear reason, because both are defensible in the abstract and the agent has no house-specific signal for which one this team wants. This recurs (every API change touches it), is expensive to get wrong (a breaking change shipped as if it were additive is a production incident), and is describable with a tight trigger ("when a task adds, removes, or changes the shape of a field in a public API response"). It clears all three bars - a skill capturing this team's specific compatibility rule (with a couple of worked before/after examples of additive vs. breaking changes) is a good investment.

Worked example: a candidate that doesn't clear the bar#

The same team also notices that an agent occasionally writes a slightly-too-long single-line commit message. This recurs, technically - but it's cheap to correct in the moment (a one-line prompt reminder, or catching it at review), doesn't compound into anything expensive if occasionally missed, and doesn't represent a case where the agent is missing knowledge it couldn't otherwise infer (most agents already know commit message conventions reasonably well from training). Packaging this as a standalone skill - complete with its own trigger description competing for the agent's attention alongside every other skill in the library - costs more in ongoing maintenance and potential trigger collision (lesson 05) than it saves. A one-line mention in an already-loaded document, or nothing at all, is the better call here.

Example (2026): several current agent products implement this exact metadata/body/supporting-file structure as a literal file format - a folder with one designated instruction file plus optional subdirectories for reference material and scripts, with the agent's harness handling the tiered loading automatically. Treat this as one illustrative implementation of the pattern, not the definition of a skill: the concrete file layout is covered, and kept current, in landscape-snapshot/06 - the durable idea is the three-tier packaging described above, which would hold even if every current product implementing it were replaced tomorrow.

Pros#

Amortizes authoring cost across every future occurrence of a recurring need, instead of re-explaining it in every relevant prompt.
Keeps the always-loaded core small (protecting the budget lesson 03 argues for) while still making narrow, specific knowledge available exactly when it's relevant.
Centralizes a piece of guidance in one place, so correcting or improving it once improves every future task that triggers it, rather than requiring the fix to be repeated everywhere the guidance was previously restated ad hoc.

Cons#

Discovery is not guaranteed. A skill only helps on the tasks where its trigger actually fires; lesson 05's three failure modes apply directly and are the main way a well-written skill body still fails to help in practice.
Maintenance burden grows with the library. Every additional skill is one more description the agent has to disambiguate against every other skill's description at trigger time (lesson 05's ambiguity/collision mode gets more likely, not less, as the library grows) and one more document someone has to keep accurate as the underlying guidance evolves.
Not free even when it never over- or under-triggers. The always-visible metadata tier, while individually cheap, is not zero-cost - a library of hundreds of skills means hundreds of descriptions competing for space and attention in the agent's view of "what's available," which is itself a scaling problem addressed partly by good description hygiene (lesson 04) and partly by not building skills for needs that don't clear the bar in this lesson.

Alternatives#

A single, larger always-loaded document covering many topics - avoids the triggering problem entirely (nothing to fail to trigger, because it's always there) but only scales to a small number of topics before it violates the always-loaded budget (lesson 03); the whole reason skills exist is that this doesn't scale.
Ad hoc, per-task prompting ("remember to do X" restated in whichever prompt happens to need it) - zero authoring or maintenance overhead for genuinely one-off needs, but doesn't scale across a team or across sessions, and drifts out of sync the moment the guidance changes and only some copies get updated.
A deterministic lever (hook or command) instead of a model-judged skill - appropriate when the "when to apply this" decision should not be left to the model's judgment at all (a build step that must always run, a formatting pass that should never be skipped); lesson 10 covers this distinction, and lesson 11 covers choosing between all of these primitives directly.

When to use it#

Build a skill when a need recurs across tasks, when getting it wrong (or reconstructing it inconsistently) has a real cost, and when it can be described tightly enough that a model-judged trigger will reliably find it without colliding with something else already in the library. It's the right primitive specifically for knowledge that should apply only sometimes, but needs to apply correctly and consistently every time it does.

When NOT to use it#

Don't build a skill for a one-off need (just state it in the prompt), for something the agent already handles well without help (packaging it adds triggering risk and maintenance cost for no real gain), or for guidance that must apply unconditionally and deterministically every time a certain event happens - that's a hook's job, not a model-judged trigger's (lesson 10). Also don't build one when the underlying need genuinely can't be captured in a description tight enough to avoid lesson 05's failure modes; in that case, fix the describability problem first, or reconsider whether a skill is really the right primitive for this need at all.

Key takeaways / mental model#

Think of a skill as a specialist you keep on retainer rather than on staff: cheap to know they exist (their one-line bio is all you carry around), fully available the moment a task actually needs their specific expertise, and a wasted retainer if you never had a task that needed them or if you can never quite remember which specialist to call for which job. The retainer only pays for itself when the need is real, recurring, and clearly describable enough that you'll actually think to call them - exactly the three-question bar this lesson sets before reaching for the primitive at all.

Self-check questions#

A junior engineer proposes building a skill for "how to write good code comments" because they noticed the agent's comments were sometimes too sparse. Walk through this lesson's three-question bar (recurs? expensive to reconstruct? describable enough to trigger reliably?) and give your verdict, with reasoning for each question.
Explain, without using the word "tool" or "hook," what distinguishes a skill from a tool. Why doesn't packaging "how to call the payments API correctly" as a skill make sense if calling the payments API is itself implemented as a tool?
A team has 40 skills in their library and just noticed two of them have descriptions that both plausibly match a common task type. Which earlier lesson's failure mode does this represent, and what does it suggest about the trade-off of packaging more and more recurring needs as skills without bound?
Give a concrete example (not from this lesson) of a recurring need that should stay as ad hoc, per-prompt guidance rather than becoming a skill, and justify why using the three-question bar.
Why does the lesson describe a skill's metadata tier as "not zero-cost" even when a skill never over-triggers or under-triggers? What is the cost, specifically, and who pays it?

References#

Anthropic engineering blog: Equipping agents for the real world with Agent Skills
Anthropic Claude Docs: Agent Skills overview
Agentman Blog: The Agent Skills Ecosystem in 2026 - Who's Building, What's Working, and What's Next
This repository's own agent-docs/ dispatcher as one inspectable case study of packaged, on-demand guidance.