Home › Claude › Agent › Skill

📘 Skill: reusable know-how for agents

A tool lets an agent do something. A skill teaches it how to do a kind of task well: your team's steps, rules, templates and helper scripts, packaged once and reused whenever they're needed.

• Beginner
• ⏱ 25 min
• Claude feature: Agent Skills

What is it?

An Agent Skill is a folder that teaches Claude a specialised task. It always contains a file called SKILL.md with:

• a short header (called frontmatter) giving the skill's name and a description of what it does and when to use it, and
• the instructions themselves, written in plain language.

The folder can also hold supporting files, such as templates, reference documents and small scripts, that Claude reads or runs only when it needs them.

SKILL.md

The main instruction file of a skill. The .md means Markdown, a simple text format.

Frontmatter

A small block between --- lines at the top of the file holding settings such as name and description.

Context

Everything the model can "see" while working: your messages, instructions and tool results. Context space is limited and costs money, so less is better.

Progressive disclosure

Loading information a bit at a time, only when it's needed, instead of all at once.

Prompt

The instructions or question you type to the model for one request.

Skill, tool, prompt and agent compared

A useful way to remember it: a tool is a hand, a skill is a training manual, and an agent is the employee who uses both.

Why is it important?

• No more repeating yourself: without skills you paste the same long instructions ("use our template, cite sources like this…") into every conversation.
• Consistent results: everyone, and every agent, follows the same tested steps.
• Saves context: Claude keeps only each skill's short description in mind and loads the full instructions only when they're relevant. You can install many skills without filling up the context.
• Easy to share and improve: a skill is a folder you can store in version control, review and update like any document.

Real-world analogy

How does it work?

1. Install: put the skill folder where your Claude product looks for skills. In Claude Code this is .claude/skills/ in your project or ~/.claude/skills/ for personal skills. In the Claude apps you upload it in settings. With the API you upload it or use Anthropic's pre-built skills.
2. Startup: Claude sees only each skill's name and description, which is a few words per skill.
3. Match: when a request arrives, Claude compares it with the descriptions and decides whether a skill is relevant. A good description says both what the skill does and when to use it. In Claude Code you can also call a skill directly by typing / followed by its name, for example /weekly-report.
4. Load: Claude reads the full SKILL.md instructions.
5. Go deeper only if needed: Claude opens referenced files or runs included scripts. This needs an environment where Claude can read files and run code, such as Claude Code or the API with the code execution tool.
6. Do the task following the skill's steps, using tools where the skill says to.

Workflow diagram

Try it: which skill gets loaded?

Example skills

Anthropic also provides ready-made skills, for example for creating Word, Excel, PowerPoint and PDF files, and publishes example skills in the anthropics/skills repository.

Practical example: a weekly status report skill

Your team writes a status report every Friday and always forgets the format. Let's turn the format into a skill for Claude Code.

1. Create the folder .claude/skills/weekly-report/ in your project.
2. Add the SKILL.md shown below, plus a template.md file with the report layout.
3. In Claude Code, ask: "Write this week's status report from notes.md."
4. Claude sees that the weekly-report description matches, loads the instructions, opens template.md, reads notes.md with its file tool and writes the report in your format.

Code example

1. The skill file: a real, working Agent Skill for Claude Code.

---
name: weekly-report
description: Writes the team's Friday status report in our standard format. Use when the user asks for a weekly report, status update or end-of-week summary.
---

# Weekly status report

## Steps
1. Read the notes or files the user points to.
2. Open `template.md` in this folder and follow its section order exactly.
3. Put wins first, then risks, then next week's plan.
4. Keep it under 300 words. Use plain language, no jargon.
5. For every risk, name an owner. If no owner is known, write "Owner: TBD".

## Rules
- Never invent numbers. If a figure is missing, write "not reported".
- End with the line: "Questions? Reply in #team-status."

2. How a program could use skills behind the scenes. This is a simplified sketch to show the idea. It is not a real SDK API. Claude products do this for you.

# Step 1: at startup, load ONLY the name and description of every skill.
skills = load_skill_summaries("skills/")          # e.g. [("weekly-report", "Writes the team's...")]
system = "Available skills:\n" + "\n".join(f"- {s.name}: {s.description}" for s in skills)

# Step 2: the model decides which skill (if any) fits the request.
request = "Write this week's status report from notes.md"
chosen = model_choose_skill(request, skills)      # Claude reasons over the descriptions

# Step 3: load the full instructions only for the chosen skill.
if chosen:
    system += "\n\n" + read_file(chosen.folder + "/SKILL.md")

# Step 4: run the agent; it can read extra files (template.md) with its tools when told to.
answer = run_agent(request, system, tools=[read_file, write_file])

To use skills through the Claude API (pre-built skills or your own uploaded ones, which need the code execution tool), follow the official Skills guide. Its exact request format is documented there.

Step-by-step explanation

1. --- … --- marks the frontmatter. name uses lowercase letters, numbers and hyphens.
2. description is the "spine of the binder". It says what the skill does and when to use it. This is the only part Claude sees until the skill is chosen, so it decides whether the skill is ever used.
3. Below the frontmatter, the Steps section gives the procedure in order. Numbered steps are easy for Claude to follow.
4. "Open template.md" is a reference to an extra file. It's loaded only when Claude reaches this step.
5. The Rules section sets limits, such as "Never invent numbers". Clear rules make results consistent.
6. In the sketch, load_skill_summaries keeps startup cheap, model_choose_skill is the relevance decision, and the full file is read only afterwards. That is progressive disclosure in four lines.

Combining skills with tools

Skills and tools work together. The skill says what to do and in what order, and tools carry it out:

• A research-brief skill might say: "Use the web search tool for at least three sources, then record each source's title and link."
• A document-analysis skill might include a script, extract_dates.py, that Claude runs with a code tool. The script's code never has to be loaded into the context, only its output.
• A skill can't give Claude new permissions. If a skill mentions a tool the agent doesn't have, that step can't happen.

Versioning, testing and maintaining skills

• Version control: keep skill folders in Git (a system that tracks changes to files) so you can see who changed what and undo mistakes. Skills uploaded through the Claude API also have versions you can choose between.
• Test triggering: write a short list of requests that should use the skill and some that shouldn't, then check Claude's behaviour for each.
• Test results: keep a few sample inputs with known good outputs and re-check them after every change.
• Keep it focused: one skill per job. Move long reference material into separate files that the skill links to.
• Review for safety: skills can contain scripts. Only install skills from sources you trust, and read them first.

Use cases

• Company writing styles, report formats and brand guidelines
• Team checklists: code review, release steps, incident write-ups
• Working with file types: spreadsheets, slide decks, PDFs
• Domain know-how: your product's data model, your legal clause library

Advantages and limitations

Best practices

• Start the description with what the skill does, then add "Use when…" with the words people actually type.
• Keep SKILL.md short and clear, and link to extra files for details.
• Use numbered steps and explicit rules.
• Include an example of a good output.
• Name skills by their job: weekly-report, not helper2.
• Test with real requests before sharing with your team.

Knowledge check

Mini project

Key takeaways

• An Agent Skill is a folder with a SKILL.md file: reusable instructions plus optional files and scripts.
• Skills give know-how, tools give actions, prompts are one-off instructions, and agents do the work.
• Claude loads skills step by step, which is why the description is so important.
• Treat skills like code: version them, test them and only trust safe sources.

Further learning

• Agent Skills overview (official docs)
• Using Skills with the Claude API (official docs)
• Skills in Claude Code (official docs)
• anthropics/skills: example skills (official GitHub repository)
• Equipping agents for the real world with Agent Skills (Anthropic engineering blog)