//
Search across all documentation pages
Agent Skills are folder-based recipes that Claude loads on demand to guide how it carries out a task.
Instead of re-explaining your process every time you ask for a weekly report, a code review, or an onboarding walkthrough, you write the instructions once as a Skill.
From then on, Claude recognizes when a request matches that Skill and pulls in the full instructions automatically, without you needing to reference it by name.
SKILL.md, that Claude can discover and load when a task matches what the Skill covers.SKILL.md, description matching, on-demand loading, bundled reference files, portability across surfaces.At its simplest, a Skill is a folder.
Inside that folder sits one required file, SKILL.md, which holds a short block of metadata followed by plain-language instructions in the body.
The metadata tells Claude what the Skill is called and, most importantly, describes what it does and when it should be used.
The body is where the actual recipe lives - the steps, the format, the house rules you want followed every time this kind of task comes up.
A Skill can also bundle extra files alongside SKILL.md, such as a reference document with more detail than belongs in the main instructions, or a small script the Skill is allowed to run.
Think of a Skill as a job aid you hand to a new team member, except Claude reads it automatically rather than needing to be told to open it.
You do not invoke a Skill the way you'd run a command.
Claude scans the descriptions of all your available Skills against the task in front of it, and loads the one that matches.
That distinction - a Skill is discovered, not invoked - is the single most important thing to understand about how Skills behave day to day.
A Skill's description is doing more work than it looks like it is.
Claude does not read every Skill's full instructions on every single message - that would be slow and would clutter the conversation with irrelevant material.
Instead, it keeps a lightweight index of what each available Skill is for, built from the description field, and checks new tasks against that index.
When a task's language lines up with a Skill's description, Claude loads that Skill's complete SKILL.md body into the conversation before it starts working.
This is why the description matters more than almost anything else about a Skill: it is the trigger, not just a label.
A short illustrative shape of what that metadata looks like:
---
name: weekly-report
description: >-
Generates the weekly team status report in our standard format.
Use when asked for a weekly update, status report, or team summary.
allowed-tools: []
---Notice that the description above states both what the Skill does and when to use it - naming the trigger phrases a person would actually type, not just a category label.
An optional allowed-tools field can scope which tools a Skill is permitted to use, which matters more in Claude Code and Cowork than in the claude.ai web app, where tool access is already constrained by the surface itself.
Skills are portable by design: the same folder works whether Claude is running in Claude Code, in Cowork, or in the claude.ai chat interface, because the underlying mechanism - description matching, then loading instructions - is the same everywhere.
Skills sit alongside two other ways of giving Claude standing context: Projects and Custom Instructions.
Each solves a different shape of problem, and the useful distinction is between context that should always be present and context that should only load when relevant.
| Approach | Strength | Weakness | Best Fit |
|---|---|---|---|
| Agent Skill | Loads only when the task matches; portable across surfaces | Only as good as its description; invisible if the trigger is vague | A recurring task or process with a clear, nameable trigger |
| Project | Keeps files and context scoped to one workspace, always available inside it | Tied to a single workspace; not something Claude reaches for by matching a description | Ongoing work tied to one client, codebase, or initiative |
| Custom Instructions | Applies broadly, every conversation, no matching step needed | Always-on, so it can't stay narrow to one task without becoming noise | Standing preferences you want followed everywhere, all the time |
A team's first few Skills are usually the tasks they already do the same way every time: a weekly report with a fixed structure, a code review checklist, an onboarding walkthrough for new hires.
These are good starting points because the trigger is obvious and the payoff is immediate - the next time someone asks for that report, Claude already knows the format without being told again.
As a Skill library grows, the discipline that matters most is keeping each Skill's description specific enough that it does not overlap confusingly with another Skill covering similar ground.
SKILL.md, with a name and description in its frontmatter and instructions in the body.SKILL.md.SKILL.md file with plain-language instructions; bundled scripts are optional and not required for most Skills.Stack versions: Written against the Claude model lineup current as of ~June 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (the default), and Claude Haiku 4.5. Model names, pricing, and product features move quickly - verify current specifics at platform.claude.com/docs before relying on them.