Claude skills are reusable markdown playbooks that make Claude dramatically better at specific tasks — and they're the most overlooked feature in the whole ecosystem. A Claude skill (often called a Claude Code skill, since that's where most people use it) teaches Claude how to approach a type of work, automatically, every time. If you've wondered what a Claude skill actually is, why people rate them so highly, or how they differ from MCP and CLAUDE.md — this is the complete answer.
This guide covers what Claude skills are, where they live, how to create one, how they differ from prompts, MCP, and CLAUDE.md, how to use them, and why they compound into a serious advantage.
What is a Claude Code skill?
A skill is a markdown file that teaches Claude Code how to approach a specific type of task. Think of it as a detailed playbook — not just "what to do" but "how to think about it, what to watch out for, and what good looks like."
Skills live in your ~/.claude/skills/ directory. Each skill is a folder containing a SKILL.md file with two parts: YAML frontmatter (a name and a description that tells Claude when to use it) and the markdown instructions themselves. When a task matches a skill's description, Claude automatically loads the relevant instructions and follows them — no command to run, no flag to set.
Why not just prompt it?
You could type detailed instructions every time. But that means:
- Repeating yourself on every conversation
- Forgetting edge cases you figured out last time
- Inconsistent results because your prompt was slightly different
Skills solve this by encoding your best thinking once. Every future conversation benefits from it. This is the core difference between Claude Code skills vs prompts: a prompt is a one-off instruction; a skill is a permanent capability that triggers itself when relevant.
Claude Code skills vs CLAUDE.md
People often ask how skills relate to the CLAUDE.md file. They solve different problems and work best together:
- CLAUDE.md is project-specific. It encodes conventions, architecture, and gotchas for one codebase.
- Skills are task-specific. They encode how to approach a type of work — writing tests, reviewing code, generating documentation — regardless of which project you're in.
CLAUDE.md says "this project uses Vitest." A testing skill says "here's how to write excellent tests, what to cover, what patterns to follow." Together, Claude writes Vitest tests that follow your testing philosophy and your project conventions.
Claude skills vs MCP
The other constant question: Claude skills vs MCP — aren't they the same thing? No, and the distinction matters:
- A skill is instructions — it shapes how Claude approaches a task (judgement and method).
- An MCP server is a connection — it gives Claude a new capability or data source (GitHub, a database, the browser).
A skill is the playbook; MCP is the tool. They compose: an MCP server can pull a GitHub diff, and a code-review skill tells Claude how to review it well. If you're choosing what to invest in first, a skill improves output on work you already do; MCP unlocks work you couldn't do at all. Most people need both, but skills are the faster win.
What makes a good skill?
The best skills aren't just instructions — they're expertise compressed into a format Claude can use. A well-built skill:
- Explains the why, not just the what
- Handles edge cases that trip people up
- Includes examples of good output
- Sets quality standards so the result is consistently high
For example, a Git Commit skill doesn't just say "write good commit messages." It explains the anatomy of a useful commit message, gives examples at different levels of complexity, and tells Claude how to decide what deserves its own commit versus what should be grouped.
Claude Code skills examples
Skills earn their keep on any task you do repeatedly with a consistent standard. Common examples:
- Code review — your review checklist, severity thresholds, and what to ignore (see the developer skill set)
- Commit messages — your team's conventional-commit format and grouping logic
- Test writing — your testing philosophy, coverage expectations, and patterns
- Documentation — how your READMEs and docstrings should be structured
- Writing — a voice profile so drafts sound like you, not a chatbot
- SEO content — keyword clustering, on-page checks, and tone in one workflow (the SEO automation guide walks through the full pipeline)
- Document handling — extracting fields, generating reports, filling forms (see Claude PDF skills)
- Obsidian / second brain — synthesis, linking, the weekly review you keep skipping (Obsidian skill guide)
- Design work — design critique, system consistency, frontend handoff, UX copy (designer skills)
If you find yourself giving Claude the same instructions across multiple conversations, that pattern is a skill waiting to be written. Our 5 ways to get more from Claude Code post goes deeper on spotting these.
How to create a Claude Code skill
Creating your own skill takes about a minute:
- Make a folder:
~/.claude/skills/my-skill/ - Create
SKILL.mdinside it - Add frontmatter — a
nameand adescriptionthat says when the skill should trigger (be specific; this is how Claude decides to load it) - Write the instructions below the frontmatter: the process, the edge cases, what good output looks like
- Save. Claude Code picks it up automatically on the next relevant task
The description field is the highest-leverage part. "Use when the user wants X, mentions Y, or is doing Z" triggers reliably. A vague description means the skill never fires.
How do you install someone else's skill?
Even faster — about 30 seconds:
- Copy the skill content
- Create a file at
~/.claude/skills/skill-name/SKILL.md - Paste and save
No configuration, no plugins, no restart. Claude Code reads it the next time a relevant task comes up.
The compound effect
Here's what most people miss: skills compound. One good skill makes Claude 20% better at that task. Ten skills across your workflow and suddenly Claude is dramatically more capable across everything you do — writing, code review, documentation, testing, architecture decisions.
It's the difference between a general-purpose assistant and one that's been trained on your exact standards. If you're still deciding whether Claude Code itself is right for you, start with the complete guide to Claude Code or the comparison with Cursor and Copilot.
FAQ
What are Claude Code skills?
Claude Code skills are markdown files (SKILL.md) that teach Claude how to handle a specific type of task. They live in ~/.claude/skills/ and load automatically when a task matches the skill's description — no command needed.
Where do Claude Code skills live?
In the ~/.claude/skills/ directory. Each skill is its own folder containing a SKILL.md file. Claude scans this directory and loads a skill when its description matches what you're doing.
What's the difference between a skill and a prompt?
A prompt is a one-off instruction you type each time. A skill is a permanent, reusable playbook that triggers itself whenever a relevant task appears — so you get consistent results without repeating yourself.
How do I create a Claude Code skill?
Create ~/.claude/skills/your-skill/SKILL.md, add YAML frontmatter with a name and a specific description of when to use it, then write the instructions. Claude picks it up automatically — no restart required.
Are Claude Code skills worth it?
For any task you do repeatedly with a quality standard, yes. One skill gives a modest lift; a library of them compounds into Claude consistently matching your standards across writing, code, testing, and docs.
How are skills different from CLAUDE.md?
CLAUDE.md encodes per-project conventions and gotchas. Skills encode how to do a type of task regardless of project. They complement each other — CLAUDE.md sets the project rules, skills set the craft.
What is a Claude skill?
A Claude skill is a markdown file (SKILL.md) containing a reusable playbook for a type of task — the method, the edge cases, and what good output looks like. Claude loads it automatically when a matching task appears, so you get expert-level handling without re-explaining it each time.
What's the difference between Claude skills and MCP?
A skill is instructions that shape how Claude does a task. MCP is a connection that gives Claude a new capability or data source. The skill is the playbook; MCP is the tool. They compose and most setups use both, but a skill is the faster quality win.
How do I use Claude skills?
Place a skill at ~/.claude/skills/<name>/SKILL.md (or install one from a library). It triggers automatically when a task matches its description — there's no command to run. You just work normally and Claude applies the skill when relevant.
Where can I get Claude skills?
You can write your own, pull free examples from community GitHub lists, or use a curated, tested library. We compare the options in the Claude skills marketplace guide.
Where to start
We offer 5 free skills so you can see the difference for yourself. No card required — just sign up, copy a skill, and try it on your next task. If the quality jump is as big as we think it is, the rest of the library is there when you're ready.