What skills are
A skill is a markdown file that packages context, instructions, and a set of pre-approved tools into a single named, invokable workflow. If CLAUDE.md is the constitution Claude always carries, a skill is a playbook it pulls off the shelf only when needed.
The key mechanic is lazy loading. At session start Claude sees only each skill's short description. The full body — which may be hundreds of lines of detailed procedure — loads into context only when the skill is invoked. That keeps idle context cost near zero while giving you deep, focused instructions on demand.
CLAUDE.md
Always loaded. Project-wide rules, conventions, and facts Claude must know on every turn.
Skills
Loaded on demand. Focused, repeatable procedures invoked by name when the task calls for them.
Creating your first skill
Skills live in .claude/skills/ for project scope, or ~/.claude/skills/ for user scope. Each skill is a single markdown file with YAML frontmatter followed by the instructions. Here is a complete PR-review skill:
---
name: review-pr
description: "Review a pull request for quality, security, and convention compliance"
pre-approved-tools:
- bash
- read_file
---
# PR Review Skill
Review the current branch's changes against main with these lenses:
## Code Quality
- Functions doing more than one thing
- Missing error handling
- Performance concerns (N+1 queries, unnecessary loops)
- Dead code or unreachable branches
## Security
- SQL injection vectors (even with ORM — check raw queries)
- Unvalidated input reaching storage or external calls
- Secrets or credentials in code
- Exposed internal error messages in API responses
## Conventions
- Follows our naming conventions (camelCase functions, PascalCase types)
- Uses AppError class for all thrown errors
- Commits follow conventional commit format
## Output Format
Produce a review with: CRITICAL issues (block merge), SUGGESTIONS (should fix),
NITS (minor style), and APPROVED/NEEDS WORK verdict.
Drop that file at .claude/skills/review-pr.md and you can trigger the whole review with /review-pr — no copy-pasting the same prompt every time.
Frontmatter reference
The YAML block at the top controls how the skill is discovered, invoked, and permitted to act.
| Field | What it does |
|---|---|
| name | How you invoke the skill, e.g. /review-pr. |
| description | The one-liner Claude sees in the session's skill list — the only part loaded until invocation. |
| pre-approved-tools | Tools that auto-approve without a permission prompt while the skill runs. |
| disable-model-invocation | Set true to keep the skill out of context until you explicitly call it. |
| model | Pin a specific model for this skill — e.g. Opus for complex review work. |
| tools | Restrict the set of tools this skill is allowed to use at all. |
Dynamic context injection
Static instructions are useful, but the best skills adapt to the current state of your repo. Wrap a shell command in backticks and it executes when the skill loads, injecting fresh runtime data straight into the context:
## Current Status
Branch: `git branch --show-current`
Changed files: `git diff main --name-only`
Open TODOs: `grep -r "TODO" src/ --include="*.ts" | head -20`When the skill is invoked, those commands run and their output is substituted in place. Claude starts the workflow already knowing which branch it's on, what changed, and where the loose ends are — no manual briefing required.
An example skills library
Skills compound. A mature project keeps a folder of them so every recurring chore is a single command. A practical starting set:
.claude/skills/
review-pr.md # /review-pr — full PR review
deploy-staging.md # /deploy-staging — deployment checklist
db-migration.md # /db-migration — create and review migrations
refactor-module.md # /refactor-module — systematic refactoring
security-audit.md # /security-audit — security review
release-notes.md # /release-notes — generate from git log
onboard-feature.md # /onboard-feature — new feature checklistCommit these into the repo and the whole team inherits the same vetted workflows — onboarding, releases, and reviews all run the same way no matter who drives the session.
Bundled skills
Claude Code ships with a set of bundled skills for common tasks, so you're not starting from an empty shelf. Run /skills in any session to list what's available — both bundled and your own — and read each description before invoking so you know exactly what a skill will do.
Try it: Pick your three most repetitive Claude Code tasks and turn each into a skill. Run them, inspect the output, and tighten the instructions until the results are consistently good.
Hands-on exercise
Create three skills for your most repetitive Claude Code tasks — for example a PR review, a deployment checklist, and a release-notes generator. Invoke each one, then refine the instructions and frontmatter based on the quality of the output until each reliably does the job in one call.
Related tutorials
- CLAUDE.md — Your AI Constitution — the always-on context that complements on-demand skills.
- Sub-Agents & Parallel Work — compose skills into larger, parallel workflows.
- Browse the full Claude Code tutorial series.
Claude Code Skills FAQ
What is a Claude Code skill?
A skill is a markdown file that packages context, instructions, and a set of pre-approved tools into a single named, invokable workflow you trigger by name, such as /review-pr.
How are skills different from CLAUDE.md?
CLAUDE.md is always-on context loaded every session, while skills load on demand — only a skill's short description is loaded until you invoke it, keeping idle context cost near zero.
Where do Claude Code skills live?
Project-scoped skills live in .claude/skills/ and user-scoped skills live in ~/.claude/skills/. Each skill is a single markdown file with YAML frontmatter followed by its instructions.
What can skill frontmatter control?
Frontmatter controls the name you invoke, the description Claude sees, pre-approved tools, whether the model can auto-invoke it, a pinned model, and the set of tools the skill may use.
Can a skill use live data from my repo?
Yes. Wrap a shell command in backticks and it runs when the skill loads, injecting fresh runtime data — like the current branch or changed files — straight into the context.
Does Claude Code come with built-in skills?
Yes. Claude Code ships with bundled skills for common tasks. Run /skills in any session to list both bundled and your own, and read each description before invoking.
Quick summary
- Skills are markdown files in
.claude/skills/that package a named, on-demand workflow - Only the description loads at session start; the full body loads when you invoke the skill — cheap context
- Frontmatter controls invocation, pre-approved tools, model, and tool restrictions
- Backtick shell commands inject live repo state; commit a skills library so the whole team shares it