What is a Claude Agent Skill?

A Skill is a folder containing a SKILL.md file (YAML frontmatter with a name and description, plus body instructions) and optionally bundled scripts, templates, or reference documents. Claude discovers Skills by their description and loads the full instructions and files only when a task matches.

How is a Skill different from a subagent?

A subagent spins up a separate, isolated context window to handle delegated work and returns a result to the parent conversation — it is about parallelism and context isolation. A Skill does not create a new context window; it adds instructions and files into the existing conversation when relevant. The two can be combined.

What is progressive disclosure in Claude Skills?

Progressive disclosure means Claude only sees a Skill's lightweight frontmatter (name and description) by default. It reads the full SKILL.md body only when a task matches the description, and loads any bundled scripts or reference files only if the body instructs it to. This keeps the context window clean until a Skill is actually needed.

What should go in a Skill's description field?

Specific, explicit trigger conditions — the kinds of requests that should activate the Skill — not a general summary of what the Skill is. The description is the only signal Claude uses to decide relevance before loading the full instructions, so it should read like a matching pattern, not documentation.

Should I put logic in a Skill's script or in the SKILL.md instructions?

Push deterministic, repeatable computation — parsing, math, format conversion — into a bundled script rather than asking the model to do it in prose. Models are inconsistent at exact arithmetic and formatting across long context; a script is not. Reserve the SKILL.md body for judgment calls and step sequencing.

Can one Skill cover multiple workflows?

It can, but it is not recommended. A Skill that tries to cover several loosely related workflows is harder for Claude to match correctly against a description and harder to maintain over time. Splitting into one Skill per job keeps triggering accurate and instructions focused.

How do I test whether a Skill triggers correctly?

Ask Claude a handful of realistic requests that should activate the Skill, plus a few near-miss requests that should not, and confirm the behavior matches in both directions. Treat changes to a Skill's description field like a prompt change — test before shipping, since it is the sole signal used for discovery.

Claude Agent Skills: Complete Guide (2026)

Q: How is a Skill different from an MCP server?

An MCP server is a live connection to an external system (a database, API, or filesystem) that exposes tools and resources over a protocol. A Skill is a packaged set of instructions and static assets that Claude loads into context when relevant. A Skill's instructions can reference MCP tools by name, but it does not create a connection itself.

Q: How is a Skill different from a CLAUDE.md file or custom instructions?

CLAUDE.md and custom instructions are always-on context loaded into every conversation or session regardless of relevance. Skills are conditional: they only enter context when their description matches the current task, which lets you maintain many specialized workflows without bloating every conversation with instructions that do not apply.

Q: Where can I use Claude Agent Skills?

Skills are supported in Claude Code (typically via a .claude/skills/ directory), Claude.ai on Team and Enterprise plans, and the Claude Agent SDK, where you point the agent at a directory of Skills for discovery and progressive loading.

How Claude Agent Skills work: SKILL.md structure, progressive disclosure, Skills vs MCP vs subagents vs custom instructions, and how to build one.

Anthropic shipped Agent Skills as a way to package expertise — instructions, scripts, and reference files — into a folder Claude can discover and load on demand. If you have been writing the same procedural instructions into every system prompt, or copy-pasting a company style guide into every Claude Project, Skills replace that with something Claude finds and reads only when the task actually needs it.

This guide covers what Skills are, how they differ from MCP servers, custom instructions, and subagents, and how to build your own from a plain folder and a Markdown file.

What Are Claude Agent Skills?

A Skill is a directory containing a SKILL.md file plus, optionally, scripts, templates, and reference documents. The SKILL.md file starts with YAML frontmatter — a name and a description — followed by the actual instructions in the body.

The key design decision is progressive disclosure. Claude does not load every Skill's full instructions into context all the time. At the start of a session, it only sees the lightweight frontmatter (name + description) for every available Skill. When a task matches a Skill's description, Claude reads the full SKILL.md body — and only then, if the body references bundled scripts or files, does it load those too. This keeps the context window clean until a Skill is actually relevant.

Anatomy of a SKILL.md File

A minimal Skill folder looks like this:

pdf-report-builder/
  SKILL.md
  scripts/
    build_report.py
  templates/
    report_template.html

And the SKILL.md file itself:

---
name: pdf-report-builder
description: Generate branded PDF reports from CSV data. Use when the user asks for a report, export, or summary document from tabular data.
---

# PDF Report Builder

When the user provides CSV data and asks for a report:

1. Run scripts/build_report.py with the CSV path as an argument
2. The script outputs a populated HTML file using templates/report_template.html
3. Convert to PDF and return the file path to the user

Always preserve the original column order. Never invent data not present in the CSV.

The description field does the heavy lifting. It is the only thing Claude sees before deciding whether a Skill applies, so it needs to state clearly and specifically when to use the Skill — not what it is philosophically, but the trigger conditions.

Skills vs. MCP Servers

These solve different problems and are often used together. An MCP server is a live connection to an external system — a database, a SaaS API, a filesystem — that exposes tools and resources over a protocol. A Skill is a packaged set of instructions and static assets that lives alongside Claude and gets loaded into context when relevant.

Put simply: MCP gives Claude a live line to the outside world. A Skill gives Claude a runbook for how to use what it already has — including MCP tools — to complete a specific kind of task. A Skill can reference an MCP tool by name in its instructions; it does not replace the connection itself.

Skills vs. Custom Instructions and CLAUDE.md

Custom instructions and CLAUDE.md files are always-on context — they load into every conversation or every session in that directory, whether or not they are relevant to the current message. That is appropriate for identity, tone, and standing rules that should apply universally.

Skills are conditional. They only enter context when their description matches the current task. This matters once you have more than a handful of specialized workflows: stuffing all of them into an always-loaded CLAUDE.md wastes context on tasks that do not need them and can dilute Claude's attention on the rules that do apply to the current request. Skills let you scale the number of specialized workflows without that always-on cost.

Skills vs. Subagents

Subagents (in Claude Code and the Agent SDK) spin up a separate context window to handle a delegated piece of work in isolation, then return a result to the parent agent. They are about parallelism and context isolation — running a large search or a long tool-calling loop without polluting the main conversation.

Skills do not create a new context window. They add instructions and files into the existing conversation when relevant. You can use both together: a subagent can itself have access to Skills, and a Skill's instructions can suggest delegating a subtask to a subagent for isolation.

Where Skills Work

Skills are supported across Claude Code, Claude.ai (Team and Enterprise plans), and the Claude Agent SDK. In Claude Code, Skills typically live in a .claude/skills/ directory at the project or user level. In the Agent SDK, you point the agent at a directory of Skills and it handles discovery and progressive loading the same way.

How to Build Your First Skill

Identify a repeated procedure. Good candidates: a multi-step workflow you explain to Claude the same way every time, a house style Claude keeps getting slightly wrong, or a script-driven task (data transform, file conversion, report generation).
Create the folder and SKILL.md. Write a description that names the trigger conditions explicitly — what kind of request should activate this Skill.
Write the body as a runbook, not an essay. Numbered steps, explicit constraints, and references to any bundled scripts by filename.
Bundle deterministic logic as scripts, not prose. If a step is "parse this CSV and compute totals," that is a Python script Claude runs, not a paragraph asking the model to do arithmetic by hand.
Test the trigger. Ask Claude a handful of realistic and near-miss requests and confirm the Skill activates when it should — and stays dormant when it should not.

Best Practices

Write descriptions for discovery, not documentation. The description is a matching signal, not a summary for humans. Front-load the trigger phrases a real user would say.
One Skill, one job. A Skill that tries to cover five loosely related workflows is harder for Claude to match correctly and harder for you to maintain. Split it.
Push repeatable computation into scripts. Models are inconsistent at arithmetic and exact-format transforms across long context. A script is not.
Keep the SKILL.md body short; put depth in reference files. Progressive disclosure means Claude only opens a bundled reference file if the body tells it to — use that to keep the primary instructions scannable.
Version and test Skills like code. Treat SKILL.md changes as you would a prompt change: test against real requests before shipping, especially changes to the description field.

Common Use Cases

Teams are using Skills for: generating documents in a specific brand format (slide decks, PDFs, spreadsheets), enforcing internal coding or data conventions Claude keeps drifting from, wrapping internal API call patterns with correct auth and error handling baked in, and standardizing recurring analysis workflows (weekly reporting, changelog generation, QA checklists) so every run follows the same steps.

The Bottom Line

Skills are the right tool when you have a specific, repeatable procedure that should only load when relevant — not always-on identity rules (that is CLAUDE.md or custom instructions), not a live external connection (that is MCP), and not a task that needs its own isolated context window (that is a subagent). Start with one real repeated workflow, write a tight description, push the deterministic parts into a script, and test the trigger before you scale to a library of them.