Claude Code Skills: Install, Build and Master Them

Claude Code skills are reusable instruction folders — each one a SKILL.md file with YAML frontmatter — that teach Anthropic's coding agent your workflows. Claude Code loads every skill's name and description (roughly 100 tokens each) at startup, then pulls in the full instructions only when your request matches. You install them under ~/.claude/skills/ or .claude/skills/.

Skill loading, progressive disclosure, and install paths verified 31 July 2026 against Anthropic's Claude Code skills documentation.

That's the whole mechanism. We run this site with Claude Code daily, and Claude Code skills are the extension we lean on most — more than MCP servers, more than hooks. Below: installing community skills, building your own, the eight we keep installed, and the fixes for skills that refuse to fire.

What are Claude Code skills, exactly?

A skill is a folder holding one SKILL.md: YAML frontmatter with a name and a description that acts as the routing rule, plus a Markdown body of instructions Claude follows once that description matches your request.

A skill is a folder containing a SKILL.md file. That file has two parts:

1. YAML frontmatter — a name and a description between --- markers. The description is the routing rule: it's how Claude Code decides whether this skill applies to your current request.
2. A Markdown body — the actual instructions Claude follows once the skill activates. Checklists, conventions, example commands, links to bundled scripts or templates in the same folder.

The clever part is what Anthropic calls progressive disclosure. At session startup, Claude Code reads only the name and description of every installed skill — around 100 tokens apiece — and holds them in its system prompt as a menu. The body stays on disk. When your request matches a description ("write a changelog", "review this PR"), Claude Code loads that one skill's full instructions and follows them. Fifty installed skills cost you almost nothing until one actually fires.

This is why skills beat pasting instructions into every prompt: they persist across sessions, they can bundle supporting files and scripts, and the agent selects them itself — the last point being the real line between Claude skills vs commands, since a typed command only ever fires when you ask for it by name. New to the tool entirely? Start with our pillar guide, What Is Claude Code?, then come back here.

The /skills command: your first stop

Typing /skills lists every skill Claude Code can see, with descriptions. If a skill is absent from that list it will never fire. /doctor reports descriptions that overflowed the budget and quietly stopped matching.

Type /skills inside a session and Claude Code lists every skill it can see — built-in, personal, and project-level — with their descriptions. We check it in two situations:

1. After installing anything. If a skill doesn't appear in the /skills list, Claude will never use it, full stop. No amount of prompt engineering fixes an unloaded skill.
2. When behavior gets weird. Two skills with overlapping descriptions compete for the same requests. Scanning the list side by side makes the collision obvious.

Any listed skill can also be invoked directly as /skill-name, which forces it to run regardless of the description — the fastest way to test a new install before trusting automatic matching. And if you've installed many, run /doctor: it reports when descriptions overflow the character budget and get shortened, which quietly breaks matching.

How to add skills to Claude Code

Drop the folder into ~/.claude/skills/ for personal use or .claude/skills/ to share it via git — by cloning a repo, adding a plugin marketplace, or copying one folder. Restart the session, then confirm with /skills.

Installing community Claude Code skills takes under a minute. Personal skills live in ~/.claude/skills/ (available in every project); project skills live in .claude/skills/ at the repo root (shared with your team via git). Three ways to get skills into those folders:

1. Clone a repo straight in. Most published skills are just GitHub folders: git clone https://github.com/obra/superpowers ~/.claude/skills/superpowers installs an entire collection in one command — our walkthrough on installing Claude skills from GitHub covers the edge cases.
2. Use the plugin marketplace. /plugin marketplace add anthropics/skills pulls Anthropic's official skill set — including the document skills claude.ai itself uses — through the plugin system.
3. Copy a single folder. For one-off skills, copying the folder containing SKILL.md into the skills directory is enough. No manifest, no registration step.

Then restart your session — skills load once at startup, so a running session won't see new installs. Confirm with /skills.

Where to find skills worth installing: the awesome-claude-skills lists on GitHub are the de-facto directories. Several exist (travisvn's, ComposioHQ's with 1,000+ entries, karanb192's curated 50), and they're better browsing than search because each entry states what the skill automates.

One warning we'd underline twice: skills are instructions Claude executes with real tool access — they can run arbitrary code. Read the SKILL.md before installing, the way you'd skim a shell script before piping it to bash. Popularity is not an audit.

How to build your own Claude Code skill

Create the folder, write SKILL.md with a one-line YAML description phrased as a routing rule, restart, and check /skills. The description does the real work; the body is just the checklist Claude follows.

Community skills are generic by necessity. The skills that changed how we work are the ones encoding our conventions. Here's the full process for how to build a Claude skill — it's shorter than most READMEs.

Step 1: create the folder.

mkdir -p ~/.claude/skills/changelog-writer

Step 2: write SKILL.md. Frontmatter on top, instructions below:

---
name: changelog-writer
description: Write or update a changelog entry from recent git commits. Use when the user asks for a changelog, release notes, or a summary of what shipped.
---
 
# Changelog writer
 
1. Run `git log --oneline` since the last tag.
2. Group commits into Added / Changed / Fixed.
3. Write one line per entry, past tense, no commit hashes.
4. Insert above the previous release heading in CHANGELOG.md.

Step 3: restart Claude Code and check /skills. Done. Test it by asking naturally ("summarize what shipped this week"), then force it with /changelog-writer to compare.

The step people get wrong is the description, so treat it as a routing rule, not documentation:

Write the description by listing the three or four phrasings you'd genuinely type, then compress them into one sentence. It must be a single line of valid YAML — a multi-line description or an unquoted colon breaks parsing, and the skill silently vanishes from the menu.

The best Claude Code skills worth installing

The keepers are skill-creator, Anthropic's document skills, superpowers, Firecrawl scraping, Playwright verification, structured code review, a commit workflow, and status updates. Install two or three, not twenty — overlapping descriptions degrade matching.

We've tested a few dozen Claude Code skills from the awesome-claude-skills lists. Most are prompt wrappers you could live without. These eight earned their keep:

Our honest advice: install two or three, not twenty — overlapping descriptions degrade matching for all of them. Start with skill-creator plus whichever maps to your most repetitive task.

Why your skill isn't triggering (and the fixes)

Six causes cover nearly everything: the file is not named SKILL.md, you installed it mid-session, the description is vague, two descriptions overlap, the YAML is broken, or the description budget overflowed.

"Claude ignores my skill" is the most common complaint about Claude Code skills in every forum thread, and in our experience it's almost always one of six causes:

The universal escape hatch: invoke it directly as /skill-name. If that works but automatic matching doesn't, the body is fine and the description is the problem — which is fixable in one line.

Skills vs plugins vs MCP: pick the right layer

Skills teach procedure, MCP servers add connectivity, plugins package both for distribution. If Claude could already do the task but does it inconsistently, write a skill; if it cannot reach the data at all, reach for MCP.

Claude Code skills sit alongside two other extension mechanisms, and choosing the wrong one wastes an afternoon. They answer different questions:

The rule we use: skills teach, MCP connects, plugins package. If Claude already could do the task but does it inconsistently, write a skill. If Claude physically can't reach the data, that's MCP. To hand teammates both at once, wrap them in a plugin. The same SKILL.md format also works in Claude Cowork, Anthropic's agent for non-code knowledge work — covered in What Is Claude Cowork? — and skills ship across the claude.ai product line too; Claude AI Features covers that side of the fence.

Skills have been stable since the 2.0-era releases of Claude Code, and the loading behavior described here matches the current CLI.

Claude pricing at a glance

Claude is free to start, $20 a month on Pro, and from $100 a month on Max, with API access billed per token. Claude Code itself needs a paid plan or API credits.

For the full breakdown of every plan, see our how much Claude costs guide.

Skills are one of four places a lesson can live — compound engineering with Claude covers which learning belongs in a rule, a skill, a hook, or a subagent.

Skills work in Cowork too, and they bite harder there — Claude Cowork skills covers how one gets selected and why yours might be greyed out.

Curious about the mechanism itself? How Claude skills work explains progressive disclosure — why a skill costs almost nothing until Claude actually needs it.