Originally published at claudeguide.io/claude-code-skills-overview
Claude Code Skills Explained: What They Are & When to Use Them (2026)
Claude Code Skills are reusable, AI-callable workflows defined in SKILL.md files in your ~/.claude/skills/ directory. Each skill is auto-discovered by Claude Code, can be invoked via the Skill tool, and replaces what would otherwise be one-off prompts copy-pasted between sessions — turning 30-line instructions into a single /skill-name call. Skills are how power users compress repetitive workflows (code review, deployment, content generation, audit) into reusable building blocks. If you find yourself pasting the same instructions into Claude Code multiple times per week, a skill replaces them.
This guide covers the model: what counts as a skill, how Claude discovers them, when to use a skill vs a slash command vs a CLAUDE.md instruction, and what's already in the public skill library.
What is a Skill, exactly?
A skill is a markdown file (SKILL.md) with frontmatter that Claude Code can invoke as a tool. It contains:
- YAML frontmatter — name, description, when to invoke
- Markdown body — step-by-step instructions Claude follows
- Optional helper files — scripts, templates, references
Example skill at ~/.claude/skills/deploy/SKILL.md:
---
name: deploy
description: Ship the current branch to production. Use when the user says "ship it", "deploy", "go live", or after PR merge confirmation.
---
# Deploy current branch
1. Run `bun run build` — abort if exit code != 0
2. Run `vercel deploy --prod --yes`
3. Wait for "Aliased: ..." line, confirm HTTP 200
4. Submit IndexNow with any new content slugs
5. Report deployment URL + git SHA + line count of changed files
Now in any Claude Code session, you can say "ship it" and Claude invokes this skill instead of asking you to clarify the steps.
Skills vs Slash Commands vs CLAUDE.md
These three serve overlapping purposes. Picking right is half the battle:
| Use case | Choice |
|---|---|
| Repeatable multi-step workflow ("deploy", "audit", "review") | Skill |
One-shot UI command (Claude built-in like /clear, /exit) |
Slash command |
| Project-specific context (stack, conventions, commands) | CLAUDE.md |
Rule of thumb: if you'd write "follow these steps every time" in CLAUDE.md, make it a skill instead. Skills are invoked on demand; CLAUDE.md loads every session.
When to use a Skill
Good fits
-
Deployment workflows —
deploy,rollback,canary(see Claude Code Hooks Deep Dive for hook patterns) -
Audit/review —
aeo-audit,quality-gate,security-scan -
Content generation —
write-blog-post,generate-changelog,summarize-pr -
Investigation —
investigate-bug,find-related-tests,trace-deployment -
Setup —
init-project,setup-deploy,configure-monitoring(pairs well with Claude Code memory system)
Bad fits
- Trivial one-liners — "format this file" doesn't need a skill, just say it
- Highly variable workflows — if every invocation needs different parameters, a skill becomes brittle
- Project-specific commands — those belong in CLAUDE.md, not a global skill
The Public Skill Library
Anthropic and the community maintain skills at ~/.claude/skills/. Notable examples:
- gstack — full development stack (review, ship, qa, investigate)
- superpowers — TDD, debugging, code review patterns
- engineering — debug, system-design, deploy-checklist
- design — design-review, accessibility-check
- finance — reconciliation, journal-entry-prep
You can browse installed skills with ls ~/.claude/skills/. Each directory contains a SKILL.md defining when Claude should invoke that skill.
How Claude Discovers Skills
At session start, Claude Code lists all available skills with their descriptions. When you say "ship it" or "deploy this", Claude matches your intent against skill descriptions and invokes the best match.
If you say something ambiguous ("update the docs"), Claude either picks the best match silently or asks "which skill should I use?". Specific phrasing in the user prompt triggers faster matching.
ls ~/.claude/skills/
# deploy/ audit/ review/ investigate/ setup-deploy/
Building Your First Skill
The minimum viable skill is 5 lines:
---
name: bun-test
description: Run bun test on the current package. Use when user says "test it", "run tests", or after editing test files.
---
Run `bun test` and report results. If any tests fail, show the failure output and stop.
Save as ~/.claude/skills/bun-test/SKILL.md. Restart Claude Code. Done.
For a deeper guide on building skills with arguments, helper scripts, and conditional logic, see How to Build a Custom Claude Code Skill.
Skills with Arguments
Skills can accept arguments via $ARGUMENTS:
markdown
---
name: trace
description: Trace a deployment by its SHA. Usage: /trace <sha