What Are Claude Skills (Agent Skills)? How They Work, How to Build One, and How They Differ from MCP

"Explaining the same procedure to Claude over and over is a chore" — if that sounds familiar, Claude Skills (Agent Skills) is exactly the mechanism built to solve it. Anthropic announced it on October 16, 2025, and within just a few months it became the standard way to give Claude domain-specific abilities in Claude Code and the API.

This article lays out what Skills are, why they matter, and how to build one — written for beginners — and goes all the way to how they differ from the often-confused MCP and subagents.

1. What Are Claude Skills (Agent Skills)?

Claude Skills are a way to package "how to do a specific task" into a single folder and hand it to Claude. Inside the folder sits a manual called SKILL.md that holds the procedure, plus optional execution scripts and reference materials.

Think of it as an onboarding manual you give to a new hire. "How to generate an invoice PDF," "our commit message convention," "the meeting-notes format" — once you turn these fixed procedures into a manual, Claude can refer to it every time and produce the same quality. It feels like bolting specialized skills onto an AI agent after the fact.

2. Why They Matter: No More Re-Pasting Prompts

Until now, getting Claude to do specialized work usually meant pasting a long instruction prompt every single time. But that approach has weaknesses.

• Low reproducibility: tweak the prompt slightly and the result drifts
• It crowds the context: long instructions permanently occupy the context window
• Hard to share: it's tough to hit the same quality across a team

Skills replace this with a fold-out manual that opens only when needed. Most of the time, all Claude sees is each skill's short description (one or two lines). The actual procedure unfolds only the moment you ask for that task. So even with dozens of skills installed, your everyday context is barely touched.

When it launched, developer Simon Willison called it "maybe a bigger deal than MCP" — precisely because of this lightness and reusability. Your prompt engineering know-how becomes an asset you accumulate, rather than something you throw away after each use.

3. How It Works: SKILL.md and Progressive Disclosure

The heart of a skill is a file called SKILL.md. At the top you write a name and a description, and below them you write the procedure in plain Markdown.

---
name: pdf-filler
description: Fill PDF forms from data. Use when the user wants to populate a PDF application form or template.
---

# Filling a PDF form

1. Get the field names with `pdftk form.pdf dump_data_fields`
2. Map the user's data to those field names
3. Write it in with `pdftk form.pdf fill_form data.fdf output filled.pdf flatten`

See reference/fdf-format.md for FDF format details.

The key is the description. At the start of a session, Claude reads only each skill's description. It then decides for itself whether the task you just asked for matches that description, and only when it matches does it load the body, scripts, and reference files. This mechanism of "opening what you need, when you need it, in stages" is called progressive disclosure.

4. How to Build One (With a Minimal Example)

There are two ways. (1) Have Anthropic's official "skill-creator" skill build it for you, or (2) set up the folder yourself. A minimal structure looks like this.

.claude/skills/
└── pdf-filler/
    ├── SKILL.md          ← required: name, description, steps
    ├── reference/
    │   └── fdf-format.md ← extra detail, read only when needed
    └── scripts/
        └── fill.py       ← code Claude can run

In Claude Code, just drop the folder into your project's .claude/skills/ (that project only) or ~/.claude/skills/ (shared across all projects) and it's recognized automatically. A January 2026 update made added or edited folders take effect immediately without a restart, which makes experimenting much easier. The official sample collection is published at github.com/anthropics/skills.

As a first step, the best move is to pick one "standard procedure" you keep explaining to Claude and write it up as a SKILL.md. Start small — your team's Slack post format, how you write release notes — and you'll quickly get the hang of it.

5. Skills vs. MCP vs. Subagents

Skills aren't the only way to extend Claude. Let's sort out, by role, how they differ from the often-confused MCP and subagents. The three aren't competitors — they sit at different layers.

A simple rule of thumb: if the request involves "fetch, look up, current state," you want MCP. If it's "do it our usual way," you want a Skill. If it's "hand it to a separate unit to run in parallel," you want a subagent. And in practice, you combine all three (e.g., a subagent fetches data via MCP, then turns it into a report using a Skill's procedure).

6. Where It Works: An Open Standard

Skills aren't a feature locked to one product — they were published as an open standard. As long as you follow the shared SKILL.md format, the same skill runs across multiple tools.

In other words, a skill you write once can be reused on agents other than Claude. The same shift that made MCP the common standard for tool connections is now happening in the world of "work procedures" too. The more you juggle several coding tools, the bigger the payoff.

7. What Can You Use It For? Real Examples

It's hard to picture in the abstract, so here are some common uses.

• Document generation: produce Word, PowerPoint, PDF, and Excel files to your own templates (also included in the official samples)
• Enforcing internal rules: apply commit-message conventions, code-review checklists, and naming rules every time
• Routine reports: weekly sales summaries, meeting notes, and release notes in the same format
• Specialized workflows: data validation, how to call a specific API, steps to build a chart or diagram

Support on the third-party side is growing too: Box, Canva, and Notion offer their own operations as skills. In the context of business efficiency, the idea of "turning the work you do often into a skill, as a reusable asset" is on its way to becoming the norm.

Summary

Claude Skills (Agent Skills) is a way to package "how to do a specific task" into a folder and give it to Claude. Let's boil it down to three points.

• What it is: a folder centered on SKILL.md (name, description, steps). Much like an onboarding manual for a new hire
• Why it's smart: normally just the description; the body expands when a task matches — "progressive disclosure" that saves context
• How far it reaches: as an open standard, it's reusable on agents beyond Claude, and combines with MCP and subagents

Start by writing up one procedure you keep explaining to Claude as a SKILL.md. Once you build it, that task becomes an "asset" that needs no more explaining. If you want to dig deeper into the mechanics, see our pieces on MCP and harness engineering too. Another new Claude Code output surface alongside Skills is Claude Code Artifacts, which turns a coding session into a shareable live page.

FAQ