Claude Code Skills Explained: What They Are and How They Work
Claude Code Skills are Markdown files stored in `.claude/skills/` (or `~/.claude/skills/` for global skills). Each skill is a prompt template with instructions, examples, and context that Claude reads when you reference the skill name. Skills turn repeatable workflows into reusable, shareable commands.
Skills are the Claude Code equivalent of saved prompts with execution context. You write a Markdown file describing how to do something — 'how to write a database migration for this project', 'how to write a PR description following our template', 'how to review a TypeScript file for security issues' — and store it in `.claude/skills/`. When you reference that skill, Claude reads the file and executes the workflow described in it.
The key distinction from a slash command: skills are content-driven, slash commands are action-driven. A slash command triggers a fixed behavior (like /clear or /compact). A skill is a document that Claude reads and follows — it can contain heuristics, examples, and context that would be impractical to encode as a command.
Claude discovers skills automatically at session start — it reads `.claude/skills/` and knows what skills are available. You can invoke a skill in two ways: explicitly ('use the migration skill to add a users table') or Claude can invoke the right skill proactively when you describe a task that matches a skill's description.
Skills differ from CLAUDE.md in scope. CLAUDE.md contains project-wide context that applies to every session. A skill contains workflow-specific context that only matters when you're doing a particular type of task. The migration skill doesn't need to be in every session's context — only sessions where you're writing migrations.
Skills can reference other files with @imports, just like CLAUDE.md. A 'write-tests' skill might @import your project's test patterns file and your mock data templates. This composability keeps individual skill files focused while giving Claude all the context it needs.
Global skills in `~/.claude/skills/` are available in every project. Personal skills you use everywhere (code review, commit message writing, PR descriptions) belong globally. Project-specific skills (database migrations, custom deploy scripts, specific API patterns) belong in the repo's `.claude/skills/` and get committed to git.
Examples
your-project/
├── .claude/
│ ├── settings.json
│ ├── skills/
│ │ ├── write-migration.md # DB migration helper
│ │ ├── pr-description.md # PR description template
│ │ ├── api-endpoint.md # New endpoint scaffold
│ │ └── security-review.md # Security checklist
│ └── ...
├── CLAUDE.md
└── src/
~/.claude/
├── settings.json
├── skills/
│ ├── commit-message.md # Global: commit messages
│ ├── code-review.md # Global: review checklist
│ └── changelog-entry.md # Global: changelog format# Explicit skill invocation
"Use the write-migration skill to add a sessions table with user_id, token, and expires_at columns"
# Claude proactively recognizes and uses relevant skills
"We need a new POST /api/payments endpoint"
# → Claude sees api-endpoint skill in .claude/skills/ and applies it
# Reference a skill by name with /skill prefix
/skill security-review
# Then describe the file: "Review src/lib/auth.ts"Tips
- →Start with 2-3 skills for your most frequent repetitive tasks — writing tests, creating API endpoints, writing commit messages. Measure the time saved before building a library of 20.
- →Give each skill a clear, distinctive description at the top — this is what Claude reads to decide whether to invoke the skill proactively.
- →Include examples of bad output in your skills ('do NOT generate migrations without a rollback') — explicit anti-patterns are more reliable than implicit positive rules.
- →Version your skills in git — when a skill produces bad output, you can diff it against the last-known-good version.
- →Use `@imports` in skills to pull in relevant examples or templates without duplicating content across multiple skill files.
- →Skills can include shell command examples that Claude will run — make these explicit so Claude doesn't have to guess at your project's commands.
FAQ
Do I have to explicitly invoke a skill or does Claude use them automatically?+
Both. Claude reads all available skill files at session start and can proactively apply a skill when your task matches the skill's description. You can also explicitly invoke a skill by name in your prompt. Proactive invocation works best when your skill's opening description clearly states what type of task it helps with.
Are skills stored in the repo or on Anthropic's servers?+
Skills are local files — either in your project's `.claude/skills/` directory (committed to git) or in `~/.claude/skills/` on your machine. Nothing is sent to Anthropic's servers except the content of skill files when Claude reads them as part of a session context.
What's the file size limit for a skill?+
There's no hard limit enforced by Claude Code, but practical limits apply from the context window. Each skill file you have loads into context when Claude reads it. Keep individual skills under 500 lines — if a skill gets longer, split it and use @imports.
Can skills call other skills?+
Not directly via a call mechanism, but a skill can reference another skill file with @imports. For example, your 'write-tests' skill can @import the 'test-patterns' skill to include that context. Claude will read both files when the parent skill is invoked.