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/.

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 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. New to the tool entirely? Start with our pillar guide, What Is Claude Code?, then come back here.

The /skills command: your first stop

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

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.
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

Community skills are generic by necessity. The skills that changed how we work are the ones encoding our conventions. Here's the full build process — 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

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)

"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

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

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