How to Create Claude Code Skills: A Step-by-Step Guide
By Tyler Cyert
Claude Code skills are reusable instruction packages that load on demand via /slash commands. Instead of cramming every procedure into your CLAUDE.md, you create focused skill files that Claude loads only when you need them. This keeps your base context lean and your specialized workflows powerful.
Think of skills as recipes. Your CLAUDE.md tells Claude what kitchen it is working in. Skills tell it how to make specific dishes — but only when you order them.
What Is a Skill?
A skill is a folder containing a SKILL.md file. That file has two parts:
- YAML frontmatter — name and description (used for matching)
- Markdown body — the instructions Claude follows when the skill is active
The frontmatter includes a name (like "deploy") and a description (like "Deploy the application to production via Railway"). The body contains the step-by-step instructions Claude should follow.
Where Skills Live
| Location | Scope | Use Case |
|---|---|---|
.claude/skills/<name>/SKILL.md | Project | Shared with your team via git |
~/.claude/skills/<name>/SKILL.md | Global | Available in every project |
Project skills are committed to your repo. When a teammate clones, they get the same skills. Global skills are personal — your own shortcuts that apply everywhere.
How Skills Load
Skills appear in Claude Code's context as a list of names and descriptions. When you invoke a skill with /skill-name, Claude loads the full SKILL.md content into context. The skill stays active for the rest of that response.
This is different from CLAUDE.md (always loaded) and rules (loaded when matching files are touched). Skills are explicitly invoked — you control when they activate.
Anatomy of a Good Skill
The Frontmatter
The description field determines whether Claude matches your request to this skill. Write it like a search query someone would use. Be specific — "Review code changes for bugs, security issues, and style violations" beats "Code review helper."
The Body
The body is standard markdown. Structure it with clear headings, numbered steps, and explicit criteria. A good skill body includes what to check, the expected output format, and rules about what the skill should not do.
What Makes Skills Effective
- One skill, one job. A deploy skill deploys. A review skill reviews. Do not combine unrelated workflows.
- Numbered steps. Claude follows sequential instructions more reliably than paragraph prose.
- Explicit output format. Tell Claude exactly what the result should look like.
- Guardrails. State what the skill should not do. This prevents scope creep during execution.
Practical Examples
Database Migration Skill
A skill named "migrate" with the description "Create and run database migrations with Drizzle ORM." The steps walk through reading the current schema, generating a migration with npx drizzle-kit generate, reviewing the SQL, applying with npx drizzle-kit push, and updating seed data. Rules include never modifying existing migration files and always generating before pushing.
Component Scaffold Skill
A skill named "component" that scaffolds a new React component with tests and stories. The steps create the component file, test file, story file, and barrel export. The template specifies named exports, a Props interface convention, and forwardRef usage.
Code Review Skill
A skill named "code-review" that checks for security issues (SQL injection, XSS, command injection, hardcoded secrets), logic errors (off-by-one, null handling, race conditions), style violations, and missing test coverage. The output format specifies file, line number, severity, and fix suggestion for each issue found.
Skills vs. Rules vs. CLAUDE.md
| CLAUDE.md | Rules | Skills | |
|---|---|---|---|
| Loaded | Every session | When matching files are touched | On demand via /command |
| Purpose | Project-wide context | File-specific conventions | Specialized procedures |
| Scope | Broad | Narrow (file glob) | Narrow (one workflow) |
| Use when | Agent needs it every time | Instructions are file-type-specific | You want to invoke a procedure explicitly |
If you find yourself adding conditional sections to CLAUDE.md ("when deploying, do X"), extract that into a skill instead.
Building Skills with DotBox
Creating skills means setting up the right folder structure, writing valid YAML frontmatter, and getting the description right for matching. DotBox lets you create skills through a guided editor — pick a name, write the description and instructions, and export the complete .claude/skills/ structure as part of your directory configuration.