Claude Code skills — what they are and how to use them

What a Claude Code skill is

When you keep pasting the same instructions into every new session — a deployment checklist, a code-review rubric, a PRD template — that's a skill waiting to be written. A skill bundles the instructions into a SKILL.md file. Claude reads the description at session start (one line, ~a handful of tokens) and loads the full body only when the task matches.

Skills follow the open Agent Skills standard, which means a skill you write for Claude Code can also work in other compatible tools. They can include more than prose: a skill directory can hold scripts Claude executes, example outputs it references, and template files it fills in.

Anthropic says skills have become "one of the most used extension points in Claude Code" internally, with hundreds in active use across the company.

Skills vs CLAUDE.md vs slash commands

People reach for all three and end up confused about which to use. The distinction is practical:

The rule of thumb from Anthropic's own team: CLAUDE.md holds facts; skills hold procedures. When a section of your CLAUDE.md starts reading like a step-by-step runbook, extract it into a skill so it only loads when it's needed.

Note: custom commands have been merged into skills. A file at .claude/commands/deploy.md and one at .claude/skills/deploy/SKILL.md both create /deploy and work identically. The skill path adds optional features: invocation control, subagent execution, supporting files.

Where skills live

Skills load from four levels, each with a different scope:

When names collide, enterprise overrides personal, and personal overrides project. A project skill with the same name as a bundled skill (like code-review) replaces the bundled one for that repo — useful for enforcing your own review standards.

In a monorepo, Claude also picks up skills from nested .claude/skills/ directories as you work on files in subdirectories, so a package can carry its own skills without polluting the root.

How to create your first skill

The minimum viable skill is two parts: a description (what triggers it) and a body (what Claude does). Here's a real example — a skill that summarizes uncommitted git changes:

~/.claude/skills/summarize-changes/SKILL.md

---
description: Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed, wants a commit message, or asks to review their diff.
---
 
## Current changes
 
!`git diff HEAD`
 
## Instructions
 
Summarize the changes above in two or three bullet points, then list any risks:
missing error handling, hardcoded values, tests that need updating.
If the diff is empty, say there are no uncommitted changes.

The !`git diff HEAD` line is dynamic context injection — Claude Code runs that command and replaces the line with the output before Claude sees the skill body. This is the pattern that makes skills genuinely useful: they arrive pre-loaded with real state, not guesses.

Test it two ways after saving:

• Automatic: ask "what did I change?" in a git repo — Claude should detect the match and load the skill.
• Explicit: type /summarize-changes directly.

Claude Code watches the skills directory for changes, so edits take effect in the current session without restarting.

What goes into a skill directory

A skill can be a single SKILL.md, but it doesn't have to stop there:

my-skill/
├── SKILL.md           # Required — the entry point
├── template.md        # A template Claude fills in
├── examples/
│   └── sample.md      # Example output format
└── scripts/
    └── validate.sh    # A script Claude can run

Reference the supporting files from SKILL.md so Claude knows they exist. A skill that does code review might point at examples/good-review.md to anchor what "good" looks like rather than describing it in prose.

The nine categories Anthropic actually uses

When Anthropic catalogued its internal skills, they clustered into nine types. The most valuable by measurable impact on output quality: product verification — skills that test and check Claude's own work. The other eight:

1. Library and API reference (documentation + gotchas)
2. Data fetching and analysis
3. Business process automation
4. Code scaffolding and templates
5. Code quality and review
6. CI/CD and deployment
7. Runbooks (multi-step troubleshooting)
8. Infrastructure operations

The best skills fit cleanly into one category. A skill that tries to do "deployment + code review + standup update" confuses the trigger and produces mediocre results at all three. One concern, one skill.

Anthropic's team also notes a common mistake: don't restate what Claude already knows. A skill that says "write clean, readable code" adds context without adding value. Effective skills encode decisions Claude can't infer from the codebase alone — your team's review standards, your deployment gate, your real failure points.

Installing skills from the marketplace

Claude Code has a built-in plugin command for browsing and installing community skills without leaving the terminal:

• Open Claude Code and run /plugin to open the discovery panel.
• Find a skill, press Enter, and choose scope: User (available in all projects, installs to ~/.claude/skills/) or Project (this repo only, installs to .claude/skills/, committed to git so the team shares it).

The official marketplace includes bundled skills like /code-review, /debug, /loop, and /run — these are available in every session by default. Third-party and community skills are also listed, reviewed, and security-scanned before inclusion.

For makers and PMs who aren't writing code daily, the highest-return skills tend to be: customer interview summarization (with a template that enforces structure), PRD generation from scattered notes, competitive analysis pipelines, and standup updates from recent commits and activity.

Sharing skills with your team

The simplest team sharing path: commit .claude/skills/ to your repo. Every teammate who pulls the repo gets the skills automatically, and Claude uses them for the whole team without any individual setup.

For skills you want available across all your projects (not just one repo), put them in ~/.claude/skills/ and share the directory via a dotfiles repo or a git submodule.

Published skills live on GitHub under a claude-skills-hub topic or on marketplaces like tonsofskills.com. If you build something that closes a real gap, publishing it makes it installable by anyone with /plugin install <name>.

When a skill produces an artifact worth sharing

The pattern: a skill generates the artifact, you push it to a link, the team annotates it, the agent reads the feedback and ships a revision. Skills close the generation gap; a shared link closes the review gap.