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:

1. YAML frontmatter — name, description, when to invoke
2. Markdown body — step-by-step instructions Claude follows
3. 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:

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:

---
name: trace
description: Trace a deployment by its SHA. Usage: /trace <sha>
---

Look up deployment for git SHA $ARGUMENTS.
1. Find Vercel deployment matching this SHA
2. Show deployment URL, build duration, status
3. List files changed in the corresponding git commit

Invoke with: /trace abc123

Composing Skills

Skills can invoke other skills. Common pattern: a ship skill that calls qa, review, then deploy in sequence.

---
name: ship
description: Full ship pipeline. Use when user says "ship this", after PR approval.
---

1. Invoke skill `qa` — abort if FAIL
2. Invoke skill `review` — wait for human approval
3. Invoke skill `deploy`
4. Report final deployment URL

This is how gstack and similar toolkits structure their workflows.

When Not to Use a Skill

• You'll only do this once. Just type the prompt directly.
• The workflow changes weekly. A skill becomes stale fast; keep instructions in CLAUDE.md.
• You need to reason about the task. Skills are good for procedures, not exploration. Use Claude's normal mode for investigation.

Skill Performance Considerations

Skills are loaded at session start. With 50+ skills installed, session bootstrap can add 1-3 seconds. The fix: keep skill descriptions short (1-2 sentences) and let Claude read the full SKILL.md only when invoked.

Skill bodies aren't loaded until invocation, so a 500-line skill is fine — it only enters context when used.

Frequently Asked Questions

Where do skills live on disk?

User-global skills: ~/.claude/skills/<name>/SKILL.md. Project skills: .claude/skills/<name>/SKILL.md. Both are auto-loaded; project skills take precedence on name collision.

Can I share skills across a team?

Yes. Commit .claude/skills/ to your repo for project-specific skills. For team-wide global skills, distribute them via a shared dotfiles repo or symlink ~/.claude/skills/ to a synced folder.

Do skills work in Claude.ai (not just Claude Code)?

No. Skills are a Claude Code feature. The web interface at claude.ai uses a different system (Projects, custom instructions). Skills are local to Claude Code installations.

How is a Skill different from an MCP server?

MCP servers expose tools (callable functions like query_database, send_email). Skills are workflows — step-by-step procedures using existing tools. You can build a skill that invokes MCP server tools.

Can a skill prompt the user for input?

Yes. Use AskUserQuestion within the skill body. Or use $ARGUMENTS for command-line-style invocation. Skills can mix both — accept optional arguments and ask for missing ones.

Master Claude Code Productivity

P1 Power Prompts 300 ($29) — 300 production-tested prompts you can turn into skills. Covers review, deploy, audit, content generation, investigation, and 14 other categories.