speedy_devv

Posted on May 17

What Are Claude Skills

#claudecode #cloudskills #ai #buildinpublic

You keep seeing "Claude Skills" in repos, on X, in YouTube thumbnails. You still are not sure what the thing is. Anthropic's docs read like a spec. Most blog posts bury the answer under five paragraphs of intro.

Here it is in 30 seconds. A Claude Skill is a small folder with one file inside it called SKILL.md. That file tells Claude how to do one specific thing. Build the folder once. Claude uses it forever.

That sentence is the whole concept. The rest of this post is the proof, the parts list, the 12 real ones people are running today, and the 5-way matrix that tells you when to reach for a skill instead of a
n MCP server, a subagent, a plugin, or a project.

The One-Paragraph Definition

A Claude Skill is a folder of instructions Claude reads when it decides the topic fits your request. The folder lives at .claude/skills/your-skill-name/ and contains a single required file, SKILL.md. Claude scans the descriptions of every skill you have installed. When one matches what you asked for, it loads the body and follows it. You can also call a skill by hand with /skill-name.

Anthropic's own line: "Skills are folders containing instructions, scripts, and resources that Claude discovers and loads dynamically when relevant to a task." (Source: claude.com/blog/skills-explained.)

Three things follow from that. Skills sit on disk. Skills are discovered by description-matching, not by file extension or folder location. Skills are reusable across every session in the project they live in.

A Real SKILL.md File, Opened Up

Here is a working skill in ten lines, taken from Anthropic's own docs at code.claude.com/docs/en/skills:

---
description: "Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed, wants a commit message, or asks to review their diff."
---

## Current changes

!`git diff HEAD`

## Instructions

Summarize the changes above in two or three bullet points, then list any risks you notice.

Two parts. The block at the top fenced by --- lines is the frontmatter. It is a tiny block of settings written in YAML. The only required line is description, which tells Claude what the skill does and when to load it.

Below the frontmatter is plain Markdown. That is the body Claude reads when the skill fires. The line !\git diff HEAD`` is a shell command that runs first, with its output dropped into the message Claude sees. Then Claude follows the instructions under "Instructions". That is it. No build step. No registration. Save the file and Claude can use it on the next prompt.

How Claude Decides to Run a Skill

Two paths. You can call it by name, like /code-review, and the autocomplete list shows you every installed skill. Or you can let Claude pick. In a normal session, Claude only sees the descriptions of every installed skill, not the bodies. It reads the descriptions, decides which ones fit your prompt, and pulls in the full body of any that do. The body stays in context for the rest of the session.

This is why the description matters more than anything else in the file. Bad description, the skill never fires. Good description, Claude reaches for it the moment the topic lands.

Two caps you should know about. The combined description plus when_to_use text gets truncated at 1,536 characters in the listing Claude sees. So write the description to fit. The default budget for all skill listings together is 1% of the model's context window, configurable via a setting called skillListingBudgetFraction. Past that budget, lower-priority skills get cut. (Source: code.claude.com/docs/en/skills.)

Skills hot-reload. Edit the file mid-session and the change is live on the next turn.

12 Real Claude Skills People Run Today

Pulled from Anthropic's official set and the three highest-starred community repos on GitHub.

pdf from Anthropic: generate and process PDF documents. "Make a one-page PDF report from this CSV."
xlsx from Anthropic: create and edit Excel spreadsheets. "Turn this list into an Excel file with totals."
pptx from Anthropic: build PowerPoint decks. "Generate a 10-slide deck from this brief."
mcp-builder from Anthropic: scaffold a new MCP server. "Build an MCP server that talks to my internal API."
skill-creator from Anthropic: help Claude write new skills. "I keep doing X by hand. Make a skill out of it."
webapp-testing from Anthropic: run automated browser tests. "Click through the signup flow and tell me what breaks."
tdd from mattpocock: red-green-refactor TDD loop. "Add this feature using test-driven development."
caveman from mattpocock: compress prose to roughly 75% fewer tokens. "Rewrite this in caveman so it costs less to send."
diagnose from mattpocock: structured debugging methodology. "This bug is weird. Walk through it methodically."
code-review-and-quality from addyosmani: five-axis code review with severity labels. "Review this PR like a senior engineer would."
security-and-hardening from addyosmani: OWASP Top 10 prevention checks. "Audit my app for the top web security risks."
systematic-debugging from obra: four-phase root-cause analysis. "Don't patch the symptom. Find the actual root cause."

The three community repos behind rows 7 to 12 carry well over 80,000 stars each on GitHub, with obra/superpowers the most-starred of the bunch.

Skill vs Subagent vs MCP vs Plugin vs Project

Five things people confuse with each other. Here is the plain-English version.

Use a Skill when you want to teach Claude how to do something the same way every time. Static instructions Claude reads when the description matches. Cheap. Lives on disk.

Use an MCP server when you want to connect Claude to a live system like Stripe, Postgres, or Slack. MCP is the connection layer. It pulls live data and runs actions.

Use a subagent when you want to spawn an isolated worker with its own context window and tools. Subagents have their own context, system prompt, and tool list.

Use a plugin when you want to bundle skills, MCP servers, commands, and hooks together to share. A plugin is the distributable container around the other primitives.

Use a project when you want to provide background reference for one workspace. Projects hold knowledge files scoped to one workspace.

Anthropic's own framing: "If you've got more skills than MCP servers, you're probably doing it right." (Source: claude.com/blog/skills-explained.)

Cleanest way to remember it. MCP brings live data in. Subagents fork off a worker. Plugins package the whole bundle for distribution. Projects hold reference material. Skills teach procedure.

What Else Goes Inside a Skill Folder

SKILL.md is the only required file. Most production skills also carry one or more of these:

scripts/ for helper scripts the skill calls
references/ for documentation Claude can read on demand
examples/ for sample inputs and outputs
templates/ for files the skill copies and fills in

None of those are loaded into context by default. Claude opens them only when the body of SKILL.md tells it to. That is how a skill can carry hundreds of pages of reference without burning tokens until it needs them.

What Changed in 2026

The skills format moved fast through the spring. Three things worth knowing as of May 2026.

Root SKILL.md auto-surface. Around Claude Code v2.1.69 in late April 2026, plugins with a root-level SKILL.md and no skills/ subdirectory now show up as a single skill. Single-file plugin distribution is no longer awkward.

Custom commands merged into skills. A file at .claude/commands/deploy.md and a skill at .claude/skills/deploy/SKILL.md both create /deploy and behave the same way. Old .claude/commands/ files keep working. The distinction has dissolved.

An open standard. The format is published at agentskills.io, so the same SKILL.md file works across more than just Claude. Community marketplaces collectively list more than 4,000 skills as of May 2026. The official source remains github.com/anthropics/skills.

Bundled skills now ship with Claude Code itself: /simplify, /batch, /debug, /loop, /claude-api, /init, /review, /security-review. You already have those even if you have never installed a thing.

When a Skill Refuses to Fire

Most common reason: Claude never picked your skill, because the description did not match the prompt the user wrote. Three fixes.

Rewrite the description to lead with what the skill does, then add explicit example phrases the user might say. The 1,536-character cap is generous, so use it.

Run /doctor to confirm Claude is seeing the skill at all. The output lists every skill loaded in the current session, with their descriptions.

If you have hundreds of skills installed and most are getting cut from the listing, raise skillListingBudgetFraction past the default 1%.

Triggering is probabilistic, not deterministic. Claude usually picks the right skill. Sometimes it does not. The description is the lever.

Closing

A skill is a folder. A folder is a file. A file is a description plus a recipe. Build the folder once. Claude uses it forever.

Full version with the live decision matrix and frontmatter field reference: https://www.buildthisnow.com/blog/guide/mechanics/what-are-claude-skills

DEV Community