What skills are, and when to use one

Strip away the tooling and a skill is two things: a short trigger, a name and a description, and a body of instructions the model reads only after that trigger fires. Package both as a folder, add scripts or reference files if the task needs them, and you have a skill. That sounds small until you have watched a system with dozens of tools and a pile of saved prompts slow down because every one of them sits in context on every single turn. Skills exist to fix exactly that: stay invisible until the moment calls for them. This guide covers what a skill actually is, how it differs from a one-off prompt, a saved template, and a tool the model calls, why that shape exists, and when writing one is worth the setup and when it is just extra plumbing.

What a skill actually is

A skill is a reusable, model-loadable capability: a named folder holding instructions, plus whatever scripts or reference files those instructions point to, that a model pulls into context only when a real request matches it. Anthropic's Agent Skills format is the concrete, documented version of this idea, and its own framing draws the same line: Skills are "reusable, filesystem-based resources that give Claude domain-specific expertise: workflows, context, and best practices," and unlike a prompt written for one conversation, "Skills load on demand, so you don't have to repeat the same guidance across conversations."¹ Nothing about a skill runs, costs tokens, or changes behavior until a request actually triggers it.

pdf-processing/
├── SKILL.md         # frontmatter always loaded (~100 tokens); body loads on trigger (<5k)
├── FORMS.md         # bundled resource; loads only if referenced
├── REFERENCE.md     # bundled resource; loads only if the task needs it
└── scripts/
    └── validate.py  # runs via bash; only its OUTPUT enters context

That structure has a name: progressive disclosure. Anthropic's docs lay out the three levels directly: name and description always loaded, at roughly 100 tokens per skill; the SKILL.md body loaded only once a request triggers it, under 5,000 tokens; and any bundled resources or scripts loaded only as the instructions actually reference them.¹ That last level is why a skill can carry far more than a prompt ever could: "Skills can include comprehensive API documentation, large datasets, or extensive examples," with no context cost until something in the current task actually opens them.¹

A skill vs. a one-off prompt, a saved template, and a tool

Three things get treated as roughly the same idea as a skill, and none of them are. The difference is what gets stored, where it lives, and when it loads.

The saved-template row is the one worth sitting with, because it is the actual baseline a skill has to beat. If you already keep a paragraph in a notes app and paste it in every time, you have already proven the task repeats. What a skill adds on top is that you stop pasting: the model finds it on its own, and the paragraph costs nothing on the turns where it does not apply.

Why skills exist

A skill earns its extra structure by solving problems a prompt, saved or not, genuinely cannot:

• Context stays lean. A model juggling many capabilities cannot afford to hold every instruction in view on every turn. Progressive disclosure means a hundred idle skills cost roughly a hundred short descriptions, not a hundred full instruction sets.¹
• The work carries across sessions on its own. A saved prompt only helps if you remember to paste it back in. A skill loads itself the moment a real request matches its description, with nothing for you to do.¹
• It is shareable. A skill is a folder, which means a team can point at the same one instead of five people keeping five slightly different versions of the same instructions in five different notes apps. Custom skills in a code environment are filesystem-based and can live in a project folder precisely so a team shares one copy.¹ Anthropic's own public skill library ships the same way, organized by domain rather than by author, across categories like document processing, development, and enterprise workflows.³
• It can bundle what a prompt cannot carry. A prompt is text. A skill can point to a script that runs a deterministic check and returns only its output, or a reference file too long to paste into a chat message every time. Neither one has anywhere to live inside a prompt.¹

When a skill is worth writing

Three conditions make the trade worth it. You generally want at least two of them before you bother:

• You have done the task more than once, in close to the same way. One example is not a pattern yet, it is a guess at what the pattern might be.
• The task needs more than prose. A script that validates a format, a template file, a lookup table too long to retype, anything a plain prompt has nowhere to carry.
• More than one person, or more than one session, needs it to behave the same way. A skill in a shared or project folder means nobody quietly drifts from the agreed format.

Two concrete cases. A code-review checklist your team runs on every pull request, with a linter script attached, is a skill: it repeats, it needs the script, and several engineers need it to fire the same way every time. A single, unusual data migration you are doing exactly once this quarter is not: there is no second occurrence to spread the setup cost across, and a clear one-off prompt with the specifics pasted in gets the same result for far less overhead.

When it is over-engineering

The failure mode in the other direction is building a skill for something that never needed one. Watch for these signs:

• You have only done it once. A skill written from a single example is a guess about the pattern, not the pattern itself.
• The task barely has a repeatable shape. If every instance differs enough that the instructions would just say "use your judgment," a skill is not adding anything a short live prompt would not.
• You are writing it to feel thorough, not because the job is narrow enough to trigger cleanly. A skill that is really three loosely related tasks stuffed into one file will misfire on all three.

How skills relate to tools and agents

These three ideas nest inside each other, and mixing them up is the most common confusion. A tool is one callable action with a fixed input and output: run a search, edit a file, query a database, nothing more. An agent is the system built around a model, the loop that lets it plan a step, call a tool, read the result, and decide the next step. A skill is neither of those. It is the packaged knowledge the model reads to know how to use the tools it already has well, for one specific kind of job, inside whatever loop it is currently running.

• A tool acts. A skill informs how the model acts, it supplies judgment, format, and rules the model would not otherwise know to apply.
• An agent can call a tool with no skill loaded at all, and often does, for anything ordinary. A skill shows up specifically when a task needs domain-specific handling a general-purpose model has no way to already know.
• Skills compose. An agent working a longer task can trigger more than one skill in sequence, each contributing its own slice of instructions, the same way it might call more than one tool.

For the fuller breakdown of that loop, the plan, act, observe, repeat cycle a skill often gets pulled into, see What an AI agent actually is.

Read next: for the hands-on build, spotting the repeated task, writing a description sharp enough to trigger correctly, bundling files, and testing it before you trust it, see Create a skill from scratch. For skills, tools, and agents covered together across a fuller build, the Building with AI course walks through all three with real code.