Skills explained: reusable know-how packages for Claude

Imagine a new colleague who is handed a binder: "when a customer asks for a refund, follow page 12". They do not read the whole binder every morning; they open the right page when the situation comes up. Agent Skills are that binder for Claude. This part explains them with pictures first, and gives experts the exact structure, limits and loading rules from Anthropic's documentation.

What a skill is

The life of a skill.

Anthropic describes Skills as reusable, filesystem-based resources that give Claude domain-specific expertise: workflows, context and best practices. Unlike prompts, which are conversation-level instructions for one-off tasks, skills load on demand, so you do not repeat the same guidance in every conversation.

Expert viewAnatomy of a skill

Per Anthropic's platform documentation, every skill requires a SKILL.md file with YAML frontmatter containing name and description. The name has a maximum of 64 characters, only lowercase letters, numbers and hyphens, and cannot contain XML tags or the reserved words "anthropic" and "claude". The description must be non-empty, at most 1,024 characters, cannot contain XML tags, and must say both what the skill does and when to use it.

Text

pdf-processing/
  SKILL.md        // main instructions (name and description in the header)
  FORMS.md        // extra guidance, read only when needed
  REFERENCE.md    // detailed reference, read only when needed
  scripts/
    fill_form.py  // run by Claude; the code itself does not enter context

In Claude Code, the docs list many optional frontmatter fields (for example when_to_use, disable-model-invocation, user-invocable, allowed-tools, context, model, paths) and say only description is recommended there.

Skills folder to Claude (reply) At startup, each skill's name and description are included in the system prompt.
You to Claude For example: extract the text from this PDF.
Claude (to itself) Claude compares the request with the descriptions and finds a match.
Claude to Skills folder It reads the file using bash, and only then does the body enter context.
Skills folder to Claude (reply) The body is now on the page.
Claude to Skills folder If the instructions say so. Extra files are read only if needed.
Skills folder to Claude (reply) The script's code stays out of context. Only its output comes back.
Claude to You (reply) The answer, produced with the skill's instructions.

Takeaway. Cheap descriptions up front, full instructions only when matched.

The life of a skill request, per the platform documentation. Only the parts Claude needs ever enter the context.

Why skills save context

The big idea is progressive disclosure: Claude loads information in stages instead of all at once.

Three levels of loading, cheapest first.

~100tokens per skill for name and description
<5ktokens for a triggered SKILL.md body
0tokens for bundled files until they are accessed

Numbers from Anthropic's platform documentation.

Expert viewWhy this beats a giant CLAUDE.md

Anthropic's documentation says that until a skill is triggered, only its name and description occupy context, so you can install many skills without a context penalty. Bundled scripts are efficient too: when Claude runs a script, only its output enters context, not the code. Compare CLAUDE.md, which loads in full every session, so Anthropic's Claude Code guidance is to move long procedures and reference material out of CLAUDE.md into skills. In Claude Code, descriptions (plus when_to_use) are truncated at 1,536 characters in the skill listing, so put the key use case first. After compaction, invoked skill bodies are re-injected, capped at 5,000 tokens per skill and 25,000 total.

Skills versus the other tools

Tool	What it is	Loads when
CLAUDE.md	Standing facts and rules	Every session
Skill	Reusable knowledge and workflows	On demand, by description or /name
Subagent	An isolated worker with its own context	When spawned
MCP	A connection to an outside service	Tool names at start, details on demand
Hook	A script run on an event	On the event, with no context cost

Myth

A skill is just a saved prompt

Fact

A prompt lives in one conversation. A skill is a folder that can hold instructions, scripts and reference files, and loads itself only when relevant.

Myth

Skills and MCP do the same thing

Fact

MCP connects Claude to outside tools and data. Skills teach Claude how to work and how to use those tools well. They combine nicely.

Expert viewChoosing between them

Anthropic's extension guide summarises: CLAUDE.md for "always do X" rules; a skill for reference material Claude needs sometimes or a workflow you trigger with a command; a subagent for context isolation or parallel work; MCP for external services; and a hook when something must happen the same way every time. It notes that skills and subagents can combine: a skill can run in an isolated context with context: fork, and a subagent can preload skills. For guardrails, the guide is blunt: an instruction in CLAUDE.md or a skill is a request, not a guarantee; if a rule must hold every time, make it a hook.

1Must it happen the same way every time, with no exceptions?Yes A hook. Instructions are requests, not guarantees.No keep going
2Does it reach an outside service or data?Yes MCP.No keep going
3Would a side task flood your chat with output you will not reuse?Yes A subagent with its own context.No keep going
4Is it a procedure or reference needed only sometimes?Yes A skill.No keep going
5OtherwiseCLAUDE.md, for "always do X" rules and facts.

Takeaway. Match where the instruction loads to how often it is needed.

Where should an instruction go? The extension guide's advice, put in my own order of questions.

Examples of skills

A document checklistHow your team writes release notes.
A deployment workflowThe steps for /deploy, with a script.
A schema guideYour database tables and query patterns.
A style guideBrand voice and formatting rules.

Ideas that fit the skill shape.

Anthropic also provides ready-made skills. Its platform page lists pre-built Agent Skills for PowerPoint, Excel, Word and PDF on claude.ai and the API, and an open-source Claude API skill that comes bundled with Claude Code.

How to create one

Make a folder.claude/skills/my-skill/ in your project, or ~/.claude/skills/my-skill/ for yourself
Write SKILL.mdA short header with name and description, then clear steps
Try itType /my-skill, or ask for something that matches the description
Improve itEdits are picked up during the session without a restart

Making a first skill in Claude Code.

Text

---
name: release-notes
description: Write release notes from recent commits. Use when asked for release notes or a changelog.
---
1. List the commits since the last tag.
2. Group them: new, improved, fixed.
3. Write each item in one plain sentence.

Expert viewWhere skills live and how names resolve

Claude Code documentation lists these locations: enterprise (managed settings directory), personal (~/.claude/skills/<skill-name>/SKILL.md), project (.claude/skills/<skill-name>/SKILL.md, commit it to share), nested (<subdir>/.claude/skills/...), additional directories passed with --add-dir, and plugin (<plugin>/skills/<skill-name>/SKILL.md, invoked as /plugin-name:skill-name). When names collide, enterprise beats personal, and personal beats project. Custom commands in .claude/commands/ were merged into skills and keep working. Invocation: type /skill-name (with arguments if needed) or let Claude match the description; disable-model-invocation: true makes a skill user-only, which also keeps its description out of context.

In Claude Code

Commit .claude/skills/ to the repo
Or package it in a plugin
Or deploy through managed settings

In claude.ai and the API

claude.ai: individual only, uploaded as a zip in Settings
API: workspace-wide
Skills do not sync between these surfaces

Where a custom skill can be shared (per Anthropic's documentation).

Expert viewAvailability and constraints

Anthropic's platform page says custom skills in claude.ai are available on Pro, Max, Team and Enterprise plans with code execution enabled, are individual to each user, and cannot be centrally managed by admins there. On the API, skills run in a sandboxed container with no network access and no runtime package installation; in Claude Code they have the same network access as any other program on your computer. Agent Skills are not covered by zero-data-retention arrangements. Plan details change, so check your plan.

Frequently asked questions

Do skills cost tokens when I am not using them?

Only a short name and description each, according to Anthropic. The body and files load when the skill is used.

Can Claude run a skill automatically?

Yes, when your request matches its description, unless you set it to user-only. You can always call it by name.

Are skills the same in the app and in Claude Code?

They share the idea but are managed separately on each surface; custom skills do not sync across them.