Claude Code Skills Explained — What They Are and How to Write Your Own
Skills are reusable prompt templates that extend Claude Code with on-demand capabilities. Learn the file structure, frontmatter options, how to write custom skills, and see practical examples for code review, commit messages, translation, and scaffolding.
Quick Reference
- →A skill is a Markdown file with YAML frontmatter + a prompt body
- →Skills live in .claude/skills/ at the project or user level
- →Invoke a skill with the Skill tool or by typing its slash command
- →Frontmatter supports: name, description, trigger (when to auto-suggest)
- →The prompt body is the actual instruction sent to Claude when the skill activates
- →Skills can reference files, use template variables, and call other tools
- →User-level skills (~/.claude/skills/) are available in every project
- →Project-level skills (.claude/skills/) are shared with the team via git
In this article
What Are Skills?
A skill is a reusable, on-demand prompt template stored as a Markdown file. When invoked, its content is injected into the conversation as instructions for Claude Code. Think of skills as macros that package expertise into a single command.
Without skills, you find yourself typing the same complex instructions repeatedly: 'Review this code for security issues, check for SQL injection, XSS, and CSRF, output findings in a table sorted by severity.' With a skill, that entire workflow becomes a single invocation. Skills capture your team's best practices in a portable, version-controlled format.
Skills are fundamentally different from CLAUDE.md. CLAUDE.md is always-on passive context — it tells Claude what your project looks like. Skills are on-demand active instructions — they tell Claude to do something specific right now.
Anatomy of a Skill File
Every skill file has two parts: YAML frontmatter (metadata) and a Markdown body (the prompt). The frontmatter tells Claude Code when and how to present the skill. The body is the actual instruction.
| Frontmatter Field | Required | Description |
|---|---|---|
| name | Yes | Unique identifier used to invoke the skill (kebab-case) |
| description | Yes | Short description shown in skill listings and auto-complete |
| trigger | No | Natural language description of when Claude should suggest this skill |
Where Skills Live
Skills follow the same user/project hierarchy as CLAUDE.md. User-level skills are your personal toolkit. Project-level skills are shared with everyone on the team.
| Level | Location | Scope | In Git? |
|---|---|---|---|
| User | ~/.claude/skills/ | Available in every project you open | No |
| Project | ./.claude/skills/ | Available to everyone working on this repo | Yes |
Project-level skills in .claude/skills/ should be committed to the repository. This means the entire team gets the same skill set, and skills evolve through code review just like any other code.
Writing Your First Skill
Let us walk through creating a practical skill step by step. We will build a commit message generator that follows your team's conventions.
Create the file
Create .claude/skills/commit-message.md in your project root. Make sure the .claude/skills/ directory exists.
Write the frontmatter
Add the YAML frontmatter with name, description, and an optional trigger.
Write the prompt body
Write clear, specific instructions that tell Claude exactly what to do and how to format the output.
Test the skill
Make some code changes, then invoke the skill to verify it produces the output you expect.
Practical Skill Examples
Here are four production-ready skills that solve real problems. Each demonstrates a different pattern for writing effective skills.
Skill Design Principles
Well-designed skills share common characteristics. These principles will help you write skills that are reliable, reusable, and produce consistent output.
- ▸Be specific about output format — tell Claude exactly how to structure the response (table, checklist, code blocks, etc.)
- ▸Include constraints — what should Claude NOT do, and what edge cases should it handle?
- ▸Use imperative mood — 'Analyze the changes' not 'You should analyze the changes'
- ▸Keep skills focused — one skill, one job. A skill that does three unrelated things should be three skills
- ▸Include examples when the output format is non-obvious — show Claude what good output looks like
- ▸Reference project conventions — link skills back to CLAUDE.md patterns so they stay consistent
A good skill produces similar quality output every time it runs. If you invoke the same skill twice on the same code, the results should be structurally consistent. If they vary wildly, your instructions are too vague.
Advanced Techniques
Once you have the basics down, these advanced patterns let you build more sophisticated skills.
- ▸Multi-step skills — break complex workflows into numbered steps so Claude can checkpoint progress
- ▸Conditional logic in prompts — use 'If the file is a React component, do X. If it is a utility function, do Y.'
- ▸Reference other files — instruct the skill to read specific config files or patterns from the codebase for context
- ▸Output to files — skills can instruct Claude to write results to specific files rather than just printing to chat
- ▸Chaining skills — design skills that produce output consumable by other skills (e.g., an audit skill that feeds a fix skill)
Managing Skills Over Time
Skills are code — they should be versioned, reviewed, and maintained like any other project artifact.
- ▸Review skill changes in PRs — a bad skill instruction creates bad output for everyone
- ▸Delete skills that are no longer used — unused skills clutter the skill list and cause confusion
- ▸Test skills when you update them — invoke the skill and verify the output still matches expectations
- ▸Document skill purpose in the description field — make it obvious what the skill does without reading the full prompt
- ▸Share useful personal skills with the team — if you find a skill invaluable, propose it as a project-level skill
Skills that reference specific file paths, API formats, or library versions can go stale when the project evolves. Review skills during major refactors or dependency upgrades to ensure they still produce correct output.
Best Practices
Do
- ✓Keep each skill focused on a single task or workflow
- ✓Be explicit about output format — tables, checklists, code blocks
- ✓Include constraints and edge cases in the skill prompt
- ✓Commit project-level skills to git for team sharing
- ✓Test skills after writing or updating them
- ✓Use descriptive names and descriptions for easy discovery
- ✓Reference project conventions from CLAUDE.md in your skills
Don’t
- ✗Don't create skills for things you only do once — they are for repeated workflows
- ✗Don't make skills that duplicate what CLAUDE.md already provides
- ✗Don't write vague instructions — 'review the code' is too ambiguous, specify what to look for
- ✗Don't hardcode file paths that might change — use patterns or describe the location
- ✗Don't skip the frontmatter — without name and description, the skill is hard to discover
- ✗Don't forget to update skills when project conventions change
Key Takeaways
- ✓Skills are reusable prompt templates that turn complex, repetitive workflows into single commands
- ✓A skill file has two parts: YAML frontmatter (metadata) and a Markdown body (the prompt)
- ✓User-level skills are personal; project-level skills are shared with the team via git
- ✓Good skills are specific about output format, include constraints, and focus on one job
- ✓Skills are fundamentally different from CLAUDE.md: skills are on-demand actions, CLAUDE.md is always-on context
- ✓Treat skills like code — version them, review them, test them, and retire them when they are no longer useful
Video on this topic
Claude Code Skills in 60 Seconds
tiktok