Claude Skills Explained: What Are Agent Skills?

If you have ever pasted the same long instructions into Claude over and over, Claude Skills are the fix. A Skill is a small folder of instructions and files that teaches Claude how to do a specific job your way, and Claude pulls it in automatically the moment it becomes relevant. No copy-pasting, no re-explaining your style guide, no reminding it about your folder structure every single time.

Anthropic also calls them Agent Skills, and the two names mean the same thing. In this guide you will learn what a Claude Skill actually is, how the SKILL.md file is put together, what Skills can and cannot do, how they compare to plain prompts, and where they fit alongside MCP and subagents. No prior experience required, but a working knowledge of Claude Code will help the examples land.

What are Claude Skills?

A Claude Skill is a reusable folder of instructions and resources that teaches Claude to perform a specific task consistently, loaded automatically only when it is relevant.

Think of a Skill as an onboarding document you would hand a new teammate: here is how we write release notes, here is the spreadsheet template we use, here is the script that formats the export. You write it once, and from then on Claude follows it without being reminded. Pre-built Skills exist for everyday document work like creating PowerPoint, Excel, Word, and PDF files, and you can write your own for anything specific to your team or project.

The thing that makes Skills feel different from a saved prompt is automatic activation. You do not type a command or paste anything. Claude reads the short description of every available Skill, and when your request matches, it pulls the full Skill into context on its own. The rest of the time the Skill stays out of the way and out of the context window.

How a Skill is built (SKILL.md and friends)

Every Skill is a folder containing a SKILL.md file, and optionally extra reference files, templates, and scripts that the main file points to.

At minimum a Skill is one directory with one Markdown file inside it. That file has two parts: a short YAML frontmatter block at the top and the instructions below it.

---
name: release-notes
description: Writes release notes from a list of merged pull requests in our house style. Use when the user asks for a changelog or release summary.
---

# Release Notes

When asked to write release notes:

1. Group changes into Added, Changed, and Fixed.
2. Write each line in plain past tense, one sentence each.
3. Never invent version numbers — ask if one is not provided.

The two frontmatter fields do most of the work. The name identifies the Skill, and the description is the part Claude scans to decide whether a Skill is relevant. A vague description means the Skill rarely triggers; a specific one that names the task and the trigger (“Use when the user asks for a changelog”) fires reliably.

Below the frontmatter you write the instructions in plain Markdown, the same way you would explain the job to a person. A Skill can also bundle supporting files in its folder — a template.docx, a reference.md with edge cases, or a Python script — and the SKILL.md simply tells Claude when to read or run them.

Instructions

The instructions are the body of SKILL.md, written as clear steps Claude follows when the Skill is active.

Treat this section like a checklist for a capable but new colleague. Be concrete about the steps, the order, the output format, and the rules that must never be broken. Short, specific, and unambiguous beats long and flowery. If there are tricky exceptions, you do not have to cram them all into the main file — you can move them into a separate reference file and tell Claude to read it only when needed.

Examples

Including a worked example or two inside a Skill dramatically improves how consistently Claude follows it.

Models learn the shape of what you want far faster from a sample than from description alone. A single before-and-after pair — a messy input and the polished output you expect — anchors the format better than three paragraphs of explanation. For more concrete patterns you can study, see our collection of Claude Skills examples.

What Skills can do — with examples

Skills let Claude apply your specific workflows, formats, and even run bundled code, turning a general assistant into a specialist for your tasks.

Because a Skill can carry instructions, reference files, and executable scripts, the range is wide. A few examples of what people build:

Document generation — a Skill that fills a branded slide template, or exports data to a correctly formatted Excel file using a bundled script.
House-style writing — a Skill that knows your tone, your banned words, and your formatting rules, so every draft comes out on-brand.
Code conventions — a Skill that enforces how your team names tests, structures commits, or writes API endpoints.
Data tasks — a Skill that runs a deterministic Python script to clean a CSV, so the result is reliable rather than improvised.

That last point matters. When a Skill bundles a script, Claude is not guessing at the math or the formatting — it runs real, deterministic code. That mixes the flexibility of a language model with the reliability of a program. Inside Claude Code, Skills slot neatly into your existing Claude Code workflows, so the assistant reaches for the right procedure at the right moment.

Skills vs. simple prompts: the real difference

A prompt is a one-off instruction for the current conversation, while a Skill is a saved, reusable capability that Claude activates automatically across every conversation when relevant.

You can absolutely get a good result by writing a detailed prompt. The problem is repetition. Every new chat, you paste the instructions again. If a teammate needs the same result, they need your prompt too. And a prompt cannot bundle a template file or run a script — it is just text.

A Skill solves all three. It lives on the filesystem, so it persists. It loads on demand, so it does not clutter your context window when unused. And it can carry files and code, not just words. The simplest way to think about it: a prompt is something you say once; a Skill is something Claude knows from now on.

There is also a context-efficiency angle worth understanding. Skills use progressive disclosure — Claude only reads the short description until a Skill is actually needed, then loads the full instructions, and only opens bundled reference files if the task calls for them. A giant prompt, by contrast, sits in context whether it is relevant or not.

Where Skills work

Claude Skills work across Claude Code, the Claude API and Agent SDK, and Anthropic’s apps — anywhere Claude runs as an agent with file access.

In Claude Code, Skills live in a skills folder and are picked up automatically; this is the most common home for custom Skills among developers. Through the Claude API you can reference pre-built Skills by id or upload your own, which is how teams ship Skills inside their own products. The Agent SDK exposes the same mechanism for custom agent builds.

The common requirement is an agentic environment — one where Claude can read files and, when a Skill includes a script, execute it. The same Skill folder is portable across these surfaces, so a Skill you write for Claude Code can often move to an SDK-based agent with little change. For setup details and the exact folder locations, the official Claude Code documentation is the source of truth.

How to get started

Start by creating one small Skill folder with a single SKILL.md file, give it a sharp description, and test it on a real task.

Here is the shortest path from zero to a working Skill:

Pick one repetitive task — something you explain to Claude often, like formatting reports or writing commit messages.
Create a folder for the Skill in your Claude Code skills directory.
Write SKILL.md with a name, a specific description that says when to use it, and clear step-by-step instructions.
Add an example of the input and the output you want.
Test it by asking Claude to do the task without mentioning the Skill — if your description is good, it should trigger on its own.
Refine the description and steps based on what Claude actually does.

Keep your first Skill small. A focused Skill that does one thing well is far more reliable than a sprawling one that tries to cover everything. When you are ready for the full walkthrough, see our step-by-step guide on how to create an Agent Skill. If you are newer to the tooling itself, the Claude Code tutorial covers the basics first.

Skills vs. MCP vs. subagents

Skills teach Claude how to do a task, MCP connects Claude to external tools and data, and subagents give Claude separate workers with their own context — they solve different problems and are often used together.

These three get mixed up constantly, so here is the clean split:

Skills are knowledge and procedure. They package instructions, examples, and optional scripts so Claude performs a task your way. Think expertise.
MCP servers (Model Context Protocol) are connections. They give Claude live access to outside systems — a database, GitHub, your CRM, a search API. Think plumbing to the outside world. If you want a sense of what is available, browse the best MCP servers.
Subagents are delegation. They are separate Claude instances with their own clean context that the main agent hands focused jobs to, which is the foundation of multi-agent systems. Think a team of specialists.

A real workflow uses all three. A subagent might be assigned a task, use a Skill to know the house style for that task, and call an MCP server to fetch the live data it needs. They are layers, not competitors. For a deeper side-by-side, see our dedicated comparison of Skills vs. MCP vs. subagents.

FAQ

What is the difference between a Claude Skill and a prompt?

A prompt is a one-time instruction you type into a single conversation. A Claude Skill is a saved folder of instructions that Claude activates automatically across conversations whenever the task is relevant, and unlike a prompt it can also bundle templates and runnable scripts. In short, a prompt is something you say once; a Skill is something Claude keeps knowing.

Do I need to know how to code to create a Claude Skill?

No. The core of a Skill is a SKILL.md file written in plain Markdown — basically clear instructions in everyday language. Coding only becomes relevant if you want a Skill to bundle a script for deterministic tasks, which is optional. Non-coders can build genuinely useful Skills, and our guide on Claude Code for non-coders is a good place to start.

How does Claude decide which Skill to use?

Claude reads the short description field in each Skill’s frontmatter and matches it against your request. When a description clearly states the task and when to use it, the matching Skill loads automatically. This is why a specific, trigger-oriented description (“Use when the user asks for release notes”) works far better than a vague one.

Are Claude Skills the same as MCP?

No. Skills teach Claude how to perform a task using instructions and examples, while MCP (Model Context Protocol) is a standard for connecting Claude to external tools and data sources like databases or APIs. They address different needs and are frequently used together — see MCP vs. function calling if you want to go deeper on the connection side.

Where do I save a Skill so Claude Code picks it up?

You place the Skill folder in Claude Code’s skills directory, and it is detected automatically the next time you run Claude. Because folder locations can change as the tooling evolves, always confirm the exact path against the official Claude Code documentation rather than relying on a number you saw in a blog post.

Conclusion

Claude Skills turn the instructions you keep repeating into a reusable capability Claude reaches for on its own. The mechanics are refreshingly simple: a folder, a SKILL.md file with a sharp description, clear steps, and ideally an example — with optional reference files and scripts when you need reliability. That small package is enough to turn a general assistant into one that does your tasks your way, every time.

The best way to understand Skills is to build one. Pick a single repetitive task, write a tight Skill for it, and watch Claude apply it without being asked. From there, Skills, MCP, and subagents become the three building blocks of agentic AI work — each handling a different layer, and far more powerful together than any one of them alone.