What Are Claude Skills? The Complete Guide (2026)

A Claude skill is a folder of instructions that changes how Claude works — permanently, across every conversation, without you re-explaining anything. At its core sits a SKILL.md file: a markdown document with frontmatter that tells Claude when to activate and what to do once it does. Some skills add reference files, scripts, or templates alongside it.

That’s the mechanical definition. The practical one: a skill is expertise you install once instead of prompting for every time.

Anthropic shipped Agent Skills in October 2025, and the format spread fast because it asks almost nothing of authors. A skill is markdown in a folder. No SDK, no build step, no registry approval. Anyone with a GitHub account can publish one, and thousands of people have.

That openness is also the problem. We run SkillProof, a catalog where every listed skill gets installed on a clean machine and tested against real work before it earns a verdict. Our catalog currently lists 73 skills: 35 passed, 10 work after extra setup, and 28 sit in the test queue. Roughly half of the community skills we pull from GitHub fail on first try. So this guide covers not only what skills are and how they work, but how to tell a good one from the markdown equivalent of an abandoned npm package.

How skills work under the hood

The design question skills answer is: how do you give a model hundreds of pages of specialized instructions without stuffing them all into context? The answer Anthropic landed on is progressive disclosure, and it works in three stages.

At startup, Claude scans your skills directories and reads only the frontmatter of each SKILL.md: a name and a description. Not the body, not the reference files. Just those two fields, typically 50 to 150 tokens per skill.

During a conversation, Claude matches your request against those descriptions. This is model-driven, not keyword matching. There’s no regex, no router. Claude reads “the user is asking me to clean up a spreadsheet export” and notices that one of its installed skills describes itself as handling exactly that. Only then does it load the full body of that skill into context.

If the skill references additional files, a reference.md with edge cases, a Python script, a template, those load even later, and only if the task actually needs them. A skill can carry megabytes of supporting material while costing nothing until the moment it’s used.

The token economics follow directly. Fifty installed skills cost you roughly 3,000 to 7,000 tokens of always-loaded metadata, about the size of one long email. The bodies, which can run to thousands of tokens each, stay on disk until triggered. Compare that with pasting your standards document into every conversation, or keeping everything in an always-loaded config file, and the difference compounds over hundreds of sessions. We measured this in detail in our token cost guide.

The design has one sharp edge: everything depends on the description field. If the author wrote a vague one (“Helps with documents”), Claude never fires the skill, and you get a folder of expertise that sits inert on your disk. Trigger failure is one of the two most common defects we find in testing, and it’s why “triggers reliably” is a scored criterion in our reviews rather than an assumption.

Skills vs prompts vs MCP servers vs subagents

The Claude ecosystem now has at least four ways to extend behavior, and people mix them up constantly. Here’s the honest comparison:

	What it is	What it changes	Persists?	Idle cost
Prompt	A one-off instruction in chat	This conversation only	No	None
Skill	Instructions loaded on demand from disk	How Claude approaches a task type	Yes	~100 tokens of metadata
MCP server	A live connection to external tools/data	What Claude can reach (your DB, Slack, a browser)	Yes	Tool definitions in context, often 1,000+ tokens each
Subagent	A delegated Claude instance with its own context	Where work happens (parallel, isolated)	Yes	Definition only

A prompt dies with its conversation. Fine for one-time tasks, useless for anything you do weekly.

A skill changes how Claude thinks about a class of task: how it structures a Word document, how it writes a cold email, how disciplined its debugging is. It needs no server, no process, no credentials. It’s text.

An MCP server changes what Claude can touch. It’s a running process that exposes tools: query this database, post to this channel, drive this browser. MCP is heavier in every sense. It requires configuration and often auth, and every connected server injects its tool definitions into context whether you use them or not.

A subagent changes where work happens. It’s a separate Claude instance with its own context window and system prompt, useful for parallelizing research or isolating a noisy task so it doesn’t pollute your main conversation.

They compose. A sales workflow might use a skill to teach cold-email structure, an MCP server to pull prospect data from the CRM, and a subagent to research ten accounts in parallel. If you’re deciding between the first two, our full breakdown is in Claude skills vs MCP servers. The short version: if your problem is “Claude doesn’t know how,” you want a skill. If it’s “Claude can’t reach my data,” you want MCP.

Anatomy of a SKILL.md

Here’s a trimmed-down version of a real skill, annotated:

---
name: meeting-notes
description: Turns raw meeting transcripts into structured notes with
  decisions, action items with owners, and open questions. Use when the
  user pastes a transcript or asks for meeting notes, minutes, or a recap.
---

# Meeting notes formatter

When the user provides a transcript:

1. Read the entire transcript before writing anything.
2. Extract decisions only where the transcript shows explicit agreement.
   Never infer a decision from a discussion that trailed off.
3. List action items as: task, owner, deadline. If an owner was not
   named, write "unassigned" — do not guess.
4. Collect unresolved threads under "Open questions."

For speaker-attribution edge cases, see [attribution.md](attribution.md).

Four things carry the weight here.

The description does double duty: it says what the skill does and when to use it. That second clause (“Use when the user pastes a transcript or asks for…”) is what makes triggering reliable. The field caps out at 1,024 characters, and good authors spend them on trigger phrases, not marketing copy. The name must be lowercase letters, numbers, and hyphens, 64 characters max.

The body is instructions, not documentation. Notice the negative constraints: “never infer a decision,” “do not guess.” The best skills we test spend as many words on what Claude must not do as on what it should. Untested skills are usually all positive instruction, which is exactly how you get invented action items.

The file reference on the last line is progressive disclosure at work. attribution.md never loads unless a transcript actually has attribution problems.

And what’s absent matters: no version negotiation, no manifest, no schema beyond two required frontmatter fields. The whole format is roughly as complicated as a Jekyll blog post, which is why the ecosystem grew so fast, and why quality control didn’t come with it.

Where skills live on disk

Where a skill goes depends on which Claude surface you’re using.

In Claude Code, personal skills live in ~/.claude/skills/, one folder per skill, available in every project. Project skills live in .claude/skills/ inside a repository and travel with it through git, so your whole team gets them on clone. Project skills are the underrated option here. A skill that encodes your team’s migration checklist belongs in the repo, not on one person’s laptop. Claude Code also loads skills bundled inside plugins, which is how collections like Superpowers distribute a dozen skills in one install.

In the Claude desktop app and on claude.ai, skills are managed through Settings, under Capabilities. You upload a skill as a zip file or enable ones from Anthropic’s built-in set. This requires a paid plan (Pro, Max, Team, or Enterprise), and file-generating skills need the code execution feature enabled since documents get built in a sandboxed environment.

On the API, skills upload through a skills endpoint and attach to requests running in a code execution container, which is how you get the same SKILL.md behavior inside your own product.

One format, everywhere. A skill you write for Claude Code works on claude.ai unchanged, which is more portability than most of the AI tooling world offers right now. Our install guide walks through each surface with exact commands.

What separates good skills from junk

Anyone can publish a skill, so plenty of what’s on GitHub is junk: half-finished experiments, READMEs describing features that don’t exist, skills that were tested once against the demo in their own screenshot. When we test community skills on a clean setup, roughly half fail on the first attempt. We wrote up the failure taxonomy in why half of Claude skills don’t work, but the two dominant modes are worth knowing before you install anything: skills that don’t install cleanly from their own instructions, and skills that never trigger because the description is vague.

Every skill in our catalog is scored on four criteria. Install, out of 5: does it work from the README’s own instructions on a machine that isn’t the author’s? Trigger, out of 5: does it fire on the prompts it claims to handle, without being named explicitly? Output, out of 10: is the result measurably better than Claude without the skill? We run the same task with and without, because a skill that adds nothing over baseline is pure overhead. Docs, out of 5: does the README tell the truth about requirements and limitations? The weighted total becomes the x/10 score on every listing, and the full methodology is public, including what makes a skill fail outright.

The output criterion deserves emphasis because it’s the one nobody else checks. A skill can install perfectly, trigger reliably, and still be worthless if Claude’s default behavior already does the job. We’ve tested polished, well-documented skills whose entire body restates what the model would do anyway. They score high on three criteria and get buried by the fourth.

If you’re evaluating a skill we haven’t tested yet, our skill validator runs the structural checks automatically: frontmatter validity, description quality, common trigger-killing mistakes. It won’t tell you whether the output beats baseline, that still takes a human and an afternoon, but it catches the failures that account for most first-try breakage.

Real examples, real scores

Abstractions are cheap, so here’s what tested skills look like in practice, with the scores they earned.

Frontend Design (9.6/10, pass) is Anthropic’s own and the skill with the biggest payoff we’ve tested. We ran the same landing-page brief with and without it: the without version produced the default AI look, purple gradient hero, Inter everywhere, three identical feature cards. The with version had a real type scale and a deliberate palette. Largest quality delta in our catalog; its output score is a 10.

DOCX (9.6/10, pass) writes actual Word files: styles, tables of contents, numbered headings, tracked changes. Our test produced a 14-page report that opened clean in Word, and tracked-changes editing on an existing contract didn’t corrupt the file. If you produce documents for other humans, install this first.

Test-Driven Development (9.6/10, pass), from Jesse Vincent’s Superpowers collection, forces strict red-green-refactor. Across a three-feature session, Claude wrote the failing test first every time and refused to skip the cycle. This is a pure behavior skill, no scripts, no tools, and it still measurably reduced regressions.

Cold Email (9.2/10, pass) is the rare marketing skill we could test against reality: a 15-send live batch got 3 replies, with personalization built on verifiable specifics instead of “I loved your recent post.”

SEO Audit (9.2/10, pass) audited a 200-page site and matched a parallel Ahrefs audit on every major finding, which is the standard a free skill has to hit to justify itself.

Invoice Extractor (7.2/10, works with setup) shows what the middle tier looks like: genuinely useful output, 20 mixed-format invoices extracted into clean CSV, but it needed the PDF skill installed first and a config edit for European dates. Nothing in its README warned us. That’s the difference between a pass and a setup verdict, and it’s why we publish score breakdowns instead of a single thumbs-up.

The ecosystem in 2026

The center of gravity is anthropics/skills, Anthropic’s official repository. The document skills there (DOCX, XLSX, PPTX, PDF) are the reference standard, and every one of them passed our testing with output scores of 8 or better. When someone asks where skill quality tops out, this repo is the answer.

Around it sits a much larger and much messier community layer. The claude-skills topic on GitHub adds hundreds of new entries every month. There are curated awesome-lists, themed collections like obra/superpowers (whose TDD and Systematic Debugging skills both scored 9.6 with us, curation clearly works), and a growing number of directories that aggregate skills by scraping GitHub.

Those directories are worth a skeptical word, since we technically are one. Most aggregators list skills nobody has run. Stars measure marketing, not function, and a README is a claim, not evidence. The failure rate we see in testing, again, about half, comes from exactly the population those sites list unfiltered.

So our advice for finding skills in 2026 is unglamorous. Start with anthropics/skills. Then use curated collections from authors who eat their own cooking. Then, for the long tail, prefer anything with published test evidence over anything without. Our category pages exist for that last step: every entry has a verdict, a tested date, and notes on what actually happened when we ran it, including the failures.

Getting started in five minutes

Here’s the shortest path from zero to a working skill, assuming Claude Code.

Pick one proven skill that matches your daily work. Not five skills. One. DOCX if you write documents, Frontend Design if you ship UI, SQL Query Writer if you live in a database. Our best coding skills and best SEO skills pages rank each category by tested score if you want the shortlist.

Install it. For most skills that’s two commands:

git clone https://github.com/anthropics/skills
cp -r skills/document-skills/docx ~/.claude/skills/

Restart Claude Code, then test the trigger: ask for the thing the skill covers without naming the skill. “Turn these notes into a two-page Word memo” should activate DOCX on its own. If behavior visibly changed, it’s working. If not, check the install guide for the usual suspects.

Then build out by role rather than by curiosity. Our collections sequence tested skills into working setups for developers, marketers, sales teams, writers, and analysts, and the bundles package them for one-step install. Skill hoarding is real and mostly harmless thanks to lazy loading, but an installed skill you never trigger is just clutter with a description field.

FAQ

Are Claude skills free?

The skills themselves almost always are; the ecosystem runs on open GitHub repos, including Anthropic’s official set. What costs money is the Claude subscription to run them on. Claude Code works with Pro and Max plans or API billing, and skills on claude.ai and the desktop app require a paid plan.

Do skills work on claude.ai and the desktop app, or just Claude Code?

All of them, plus the API. The format is identical everywhere; only the installation differs. Claude Code reads folders on disk, claude.ai and desktop take a zip upload under Settings, and the API attaches skills to code-execution containers. A well-built skill moves between surfaces without edits.

Do installed skills slow Claude down or eat my context window?

Barely, and this is the clever part of the design. Each installed skill costs about 100 tokens of always-loaded metadata; the full instructions load only when a task matches. Fifty skills cost less standing context than one connected MCP server typically does. The real cost of over-installing is trigger confusion between skills with overlapping descriptions, not tokens.

What’s the difference between a skill and CLAUDE.md?

Loading behavior. CLAUDE.md is read into every conversation in a project regardless of relevance, which makes it right for facts that always apply: build commands, architecture, conventions. A skill loads only when triggered, which makes it right for procedural knowledge you need sometimes: how to write a migration, how to format a report. If your CLAUDE.md has grown a 300-line section that applies to 5% of your sessions, that section wants to be a skill.

Are skills safe to install?

Treat them like dependencies, because that’s what they are. A skill is instructions Claude will follow and sometimes scripts Claude will execute, so a malicious one could direct Claude to exfiltrate data or run hostile code. Before installing from an unfamiliar author, read the SKILL.md (it’s short), check any bundled scripts, and be suspicious of skills that demand broad permissions for narrow jobs. We cover the audit checklist in our security guide. Everything in our catalog was read by a human before it was run.

Can I write my own skill?

Yes, and for team-specific workflows you should; the format is a markdown file with two frontmatter fields. The craft is in the description (specific trigger phrases beat adjectives) and in testing against a baseline so you know the skill adds anything. Anthropic’s Skill Creator (9.6/10 in our tests) scaffolds the structure and measurably improved triggering when we used it. Our full walkthrough: how to write your own Claude skill.