What are Claude Skills? The complete guide to SKILL.md, triggers, and installing on every surface

Claude Skills are folders of instructions that Claude loads only when a task needs them. Each skill is a directory containing a SKILL.md file — instructions in plain Markdown with a name and description up front — plus optional scripts and reference files. Claude scans the descriptions on every request and pulls in the full skill only when it matches, so you can install dozens of skills without crowding the context window.

That's the 50-word version. The rest of this guide covers what every ranking explainer skips: how the trigger actually decides to load a skill, what a skill really costs in tokens, how to install skills on each Claude surface (the docs split this across three pages), how to vet a third-party skill before giving it your permissions — and the troubleshooting section for the single most-asked question, why isn't my skill firing?

What are Claude Skills, exactly?

Anthropic launched Agent Skills on October 16, 2025 across claude.ai, Claude Code, the Agent SDK, and the API. The launch was quieter than the feature deserved — six days earlier, Simon Willison had already found the document skills running live in claude.ai's /mnt/skills/public directory before any announcement existed.

The design is deliberately boring. A skill is:

my-skill/
├── SKILL.md          # required: YAML frontmatter + instructions
├── scripts/          # optional: code Claude can RUN instead of read
├── references/       # optional: deep documentation, loaded on demand
└── assets/           # optional: templates, fonts, boilerplate

The frontmatter requires exactly two fields — name and description — and those two fields are all Claude sees before deciding whether to load the rest. Willison called the format "conceptually extremely simple" — a Markdown file telling the model how to do something — and, in the same post, "maybe a bigger deal than MCP." Since December 2025 the format is an open standard, so a skill you write for Claude is a folder you can carry anywhere.

The mental model users converge on: a "job description" for Claude — how you structure reports, analyze data, or talk to clients, written down once instead of re-pasted into every chat. One designer condensed "8 years of product design experience" into a skill. Set it once, use it forever.

How skills actually work: progressive disclosure

Skills load in three levels, and the levels are the whole trick:

1. Level 1 — metadata, always loaded. Every installed skill's name + description sit in the system prompt. That's the entire standing cost.
2. Level 2 — the SKILL.md body, loaded on trigger. When your request matches a description, Claude reads the full instructions from the filesystem.
3. Level 3 — scripts and references, used on demand. Bundled files are pulled only when the task needs them — and scripts are executed, not read: Claude runs them in the environment, so a 500-line Python script contributes zero tokens of context.

The trigger mechanism (what "automatic" actually means)

Most explainers wave at this with "Claude decides automatically." Concretely: at selection time, the model sees only the name and description of each skill — nothing else. If the description says Extracts tables from PDF files and converts them to Excel, and you ask for exactly that, the skill loads. If the description says Helps with documents, it competes with everything else that "helps with documents" and loses unpredictably. Anthropic's own engineering guidance is blunt about this: routing is a metadata problem, and vague descriptions are the bug (more in the troubleshooting section).

What a skill costs your context window

No ranking article puts numbers on this, so here are the best available — all independent measurements, not official Anthropic figures:

• Frontmatter metadata: ~dozens of tokens per skill, ~80 median across the official set (SwirlAI's measurement; Anthropic officially says only "lightweight").
• A full SKILL.md body: Anthropic's authoring guidance caps it at under ~500 lines / under ~3,000 words — roughly 5k tokens, paid only when triggered.
• MCP, for contrast, loads tool schemas whether you use them or not: "GitHub's official MCP on its own famously consumes tens of thousands of tokens of context" — versus a skill, where "each skill only takes up a few dozen extra tokens."

The caveat from the community backlash thread is worth taking seriously: install fifty skills with sloppy descriptions and you've rebuilt the bloat problem one level up. Curation beats quantity — a recurring theme below.

Anatomy of a SKILL.md

---
name: quarterly-report
description: Formats quarterly business analysis into the company report
  structure and publishes it as a tracked live URL. Use when asked to
  prepare, format, or publish a quarterly report or board update.
allowed-tools: Read, Write, Bash
---

# Quarterly report

## Structure
Every report has four sections in this order: summary, KPI table,
narrative, appendix. Pull KPI definitions from references/kpis.md.

## Publishing
Run scripts/publish.sh to publish the finished HTML and return the
tracked URL.

Three details that separate working skills from ignored ones:

• The description carries trigger phrases ("quarterly report", "board update") in third person — that's what the router matches against.
• allowed-tools declares what the skill needs — Claude Code restricts the skill to those tools while it runs. Treat it as a manifest, not a sandbox: bundled scripts still execute with your full permissions (more in the security section).
• Details live in references/, not in SKILL.md — the body stays short (the official skill-development skill recommends 1,500–2,000 words), and deep material loads only at Level 3.

Installing skills on every surface

The single biggest structural gap in the existing coverage: the official docs split installation across three different pages, one per surface. Unified:

The same folder works on all four — that's the open-standard part doing its job. Write once in Claude Code, ZIP it for claude.ai, register it via /v1/skills for production agents.

Skills vs MCP vs slash commands vs subagents vs CLAUDE.md

The token-economics framing makes the differences obvious:

They compose rather than compete — Willison's practitioner taxonomy is the best worked example. The rule of thumb: MCP for live connections (APIs, databases — things that need auth and state), skills for procedural knowledge (how to do a task, with scripts for the deterministic parts), CLAUDE.md only for what genuinely applies to every session.

To the recurring skeptic's point that skills are "just markdown files": yes — and that's the feature. A skill is readable before you install it, diffable in code review, and versionable in git. None of that is true of a binary plugin.

The ecosystem: what people actually install

The adoption curve has been steep enough to embarrass the previous standard-bearer:

Both skills repositories out-starred the official MCP servers repo despite an eleven-month head start (anthropics/skills: 167k; obra/superpowers: 269k; modelcontextprotocol/servers: 89k). The Skillful.sh tracker counted 264,073 AI skills by April 2026 — 80.6% of all tracked agent tools, though that directory counts forks and variants, so treat it as a directional number.

Two patterns in what people keep after the experimentation phase:

• Document-output skills dominate. Four of the 17 official skills produce documents (docx, pdf, pptx, xlsx), and community "can't live without" lists are dominated by the same set plus skill-creator. People use Claude to produce deliverables.
• Curation wins. The most-upvoted retrospective of 2026 so far is titled "I deleted most of my Claude skills last week" — a handful of precise, trusted skills beats a directory of 264k.

Are third-party skills safe?

The section almost nobody writes, and the one that matters most. A skill is not a document — it's instructions plus executable code that runs with your permissions. Two distinct risks:

1. Malicious scripts. In Claude Code, bundled scripts run in your local environment. A skill's scripts/ directory can do anything you can.
2. Prompt injection. Once an agent loads instructions from files, malicious skill content can steer it — exfiltrating data through tool calls the skill nudges Claude to make.

Before you install a random skill, a five-line checklist:

• Read SKILL.md end to end. It's Markdown; if you can't read it, that's your answer.
• Read every file in scripts/. No opaque binaries, no curl-pipe-to-bash, no network calls you can't explain.
• Check allowed-tools. It's a review signal, not an enforcement boundary — but a formatting skill declaring Bash access is over-scoped by design or by negligence, and either disqualifies.
• Prefer skills from repos with history — commits, issues, named maintainers — over ZIPs from a directory listing.
• Test in a low-stakes session first: fresh chat, no sensitive files, ask Claude to use the skill by name and watch what it does.

Anthropic's sandbox limits the blast radius on claude.ai and the API (the execution container has no internet access); in Claude Code, you are the sandbox.

Sharing skills with a team

The team story is quietly one of the strongest parts of the format:

• Project skills travel with the repo. A skill in .claude/skills/ is versioned, code-reviewed, and arrives via git clone — every teammate (and every CI agent) gets the same procedures with zero onboarding.
• Org-wide distribution exists on Team/Enterprise plans (admin-provisioned skills), and via the API a workspace shares custom skills with versioning per skill (/v1/skills/{id}/versions).
• The open standard means no lock-in: the same folder your team commits today remains portable if your stack changes tomorrow.

Why isn't my skill triggering? (troubleshooting)

The most-asked question in every skills community, and it's almost always the same bug. In order of likelihood:

1. Your description doesn't say when to use the skill. At selection time Claude sees only name + description. Rewrite the description in third person with explicit trigger phrases: not "Helps with reports" but "Formats quarterly business reports… Use when asked to prepare, format, or publish a quarterly report."
2. Restart the surface. In Claude Code, new skills are picked up on session start — a community tester of 30+ skills reports a restart resolves "about 80% of issues".
3. Check the location. Personal skills live in ~/.claude/skills/<name>/SKILL.md, project skills in .claude/skills/<name>/SKILL.md — the folder name is the skill's invocable name.
4. On claude.ai, check the capability. Skills require code execution to be enabled, and uploads must be a ZIP of the skill folder (help center).
5. Prove the routing. In a fresh session, ask Claude to use the skill by name. If it works by name but never fires organically, you've isolated the problem: it's the description.
6. Too many skills. If dozens of descriptions overlap, the router has to guess. Delete what you don't use.

Skills for publishing: the last mile of the deliverable

Here's the pattern hiding in all the adoption data: the skills people rely on produce documents — and then the workflow ends with a file. The docx skill hands you a Word document; you attach it to an email like it's 2009. The deliverable's last mile — getting it in front of a client as something trackable, branded, and live — is exactly the part the official skill set doesn't cover.

That's the gap a publishing skill closes, and it's a textbook use of the format: procedural knowledge (house style, report structure) plus one deterministic call. ReportRoom is the publishing layer AI agents call directly, and the skill shape looks like this:

---
name: publish-report
description: Publishes finished reports and decks as tracked live URLs
  via ReportRoom. Use when asked to publish, share, or send a report,
  analysis, or client deliverable.
---

# Publish a report

1. Format the content per references/house-style.md.
2. Publish via the ReportRoom MCP tool:
   publish { title, content, theme: "editorial" }
3. Return the live URL — analytics show who opened it and what they read.

One skill file, and every surface — Claude Code, claude.ai, an SDK agent — can turn agent output into a live, tracked URL instead of an attachment. The report-skills repo packages this pattern ready to install, and it's built the way the security section above demands: a readable SKILL.md, no opaque binaries, one scoped API call. Connect the MCP server (claude mcp add --transport http reportroom https://mcp.reportroom.io/mcp) and the skill's publish step is a single tool call.

FAQ

Are Claude Skills available on the free plan? Yes. As of 2026, skills are available on Free, Pro, Max, Team, and Enterprise plans — on claude.ai they're managed under Customize → Skills. Early launch coverage said Pro-and-up, which is now outdated.

Where does SKILL.md go? In Claude Code: ~/.claude/skills/<skill-name>/SKILL.md for personal skills, .claude/skills/<skill-name>/SKILL.md inside a repo for project skills. On claude.ai: upload the skill folder as a ZIP under Customize → Skills. Via the API: register it with /v1/skills and attach by skill_id.

Why doesn't my skill show up in claude.ai after uploading? The two usual causes: code execution isn't enabled for your account (skills require it), or the ZIP contains loose files instead of the skill folder with SKILL.md at its root. On Enterprise plans, an admin must also enable Skills org-wide before individual uploads appear.

Are claude.ai skills and Claude Code skills the same thing? Same format, different runtime. The folder is identical and portable (it's an open standard); the difference is where scripts execute — your local environment in Claude Code, Anthropic's sandboxed container on claude.ai and the API.

What's the difference between a skill and an MCP server? A skill is procedural knowledge that loads on demand (~30–100 tokens standing cost, community-measured); an MCP server is a live connection whose tool schemas occupy context for the whole session — famously tens of thousands of tokens for a large server. Use MCP for connections that need auth and state; use skills for how-to knowledge and deterministic scripts. They work best combined: a skill that calls an MCP tool.