Building Custom Skills for Claude Code: A Complete Tutorial

Three sessions in a row, I pasted the same security checklist into Claude Code. The checklist had our team’s specific vulnerability patterns — the IDOR checks unique to our API design, the session handling rules for our auth flow, the data exposure rules for our PII fields. Each time, Claude applied them perfectly. Each time, I had to remember to paste them.

The moment you catch yourself re-explaining the same context is the moment you should build a skill.

TL;DR

Skills are model-invoked extensions — Claude discovers and applies them automatically based on context, without you explicitly calling them. The key to reliable skills is the description field: it determines when Claude activates the skill. Build skills for domain expertise that applies across sessions (security patterns, code style, business rules). Don’t build skills for one-off tasks — use slash commands instead.

Prerequisites: Familiarity with Claude Code’s extension system. For the comparison between skills, commands, and subagents, see the Skills section of the guide.

When to Build a Skill

Not every repeated prompt deserves a skill. The decision framework:

Skills are for knowledge Claude always has available. Slash commands are for actions you explicitly trigger. If you’re deciding between the two, ask: “Should Claude apply this automatically, or should I decide when to run it?”

Tutorial: Build a Code Review Skill

Step 1: Create the directory

Skills live in ~/.claude/skills/ (personal) or .claude/skills/ (project, shared via git).

mkdir -p ~/.claude/skills/code-reviewer

Step 2: Write SKILL.md with frontmatter

Every skill needs a SKILL.md file. The frontmatter is critical — especially description.

---
name: code-reviewer
description: Review code for security vulnerabilities, performance issues,
  and best practice violations. Use when examining code changes, reviewing
  PRs, analyzing code quality, or when asked to review, audit, or check code.
allowed-tools: Read, Grep, Glob
---

# Code Review Expertise

## Security Checks
When reviewing code, verify:

### Input Validation
- All user input sanitized before database operations
- Parameterized queries (no string interpolation in SQL)
- Output encoding for rendered HTML content

### Authentication
- Session tokens validated on every protected endpoint
- Permission checks before data mutations
- No hardcoded credentials or API keys in source

### Data Exposure
- PII masked in log output and error messages
- API responses don't leak internal IDs or stack traces
- Sensitive fields excluded from serialization defaults

Note allowed-tools: Read, Grep, Glob — this restricts the skill to read-only operations. The code reviewer can examine files but can’t modify them. Tool restrictions prevent skills from having unintended side effects.

Step 3: Add supporting resources

Skills can reference additional files in the same directory:

~/.claude/skills/code-reviewer/
├── SKILL.md                    # Required: frontmatter + core expertise
├── SECURITY_PATTERNS.md        # Referenced: detailed vulnerability patterns
└── PERFORMANCE_CHECKLIST.md    # Referenced: optimization guidelines

Reference them from SKILL.md with relative links:

See [SECURITY_PATTERNS.md](SECURITY_PATTERNS.md) for OWASP Top 10 checks.
See [PERFORMANCE_CHECKLIST.md](PERFORMANCE_CHECKLIST.md) for query optimization.

Claude loads these files when the skill activates, giving it access to your full knowledge base without bloating the main SKILL.md.

Step 4: Test activation

The skill activates the next time you start a Claude Code session. Test it:

# Ask Claude to review code — should trigger the skill automatically
claude "Review the authentication middleware in app/security/"

# Verify skill was loaded
claude --print "What skills are you currently using?"

If the skill doesn’t activate, the problem is almost always the description field. See Step 5.

Step 5: The critical step — writing the description

The description field is the single most important line in your skill. Claude matches your requests against skill descriptions to decide which skills to apply. A bad description means unreliable activation.

Bad description:

description: Helps with code

Claude has no idea when to activate this. “Helps with code” matches everything and nothing.

Better description:

description: Review code for bugs and issues

Too vague. What kind of bugs? What kind of issues? When should Claude use this instead of its built-in analysis?

Effective description:

description: Review code for security vulnerabilities, performance issues,
  and best practice violations. Use when examining code changes, reviewing
  PRs, analyzing code quality, or when asked to review, audit, or check code.

This works because it includes: - What it does: Review code for specific issue types - When to use it: Examining changes, PRs, quality analysis - Trigger phrases: review, audit, check — words the user naturally types

Test different descriptions. Start a fresh session, ask Claude to review code, and check if the skill activates. If not, add more trigger phrases. If it activates when it shouldn’t, make the description more specific.

Step 6: Iterate based on usage

After a week of use, you’ll discover: - Patterns the skill should check but doesn’t — add them to SKILL.md - False activations on unrelated tasks — tighten the description - Missing context — add supporting resource files - Tool restrictions that are too tight or too loose — adjust allowed-tools

Skills are living documents. The first version is never the final version.

Advanced: Skills as a Prompt Library

Beyond single-purpose skills, the directory structure works as an organized prompt library:

~/.claude/skills/
├── code-reviewer/          # Activates on: review, audit, check
├── api-designer/           # Activates on: design API, endpoint, schema
├── sql-analyst/            # Activates on: query, database, migration
├── deploy-checker/         # Activates on: deploy, release, production
└── incident-responder/     # Activates on: error, failure, outage, debug

Each skill encodes a different facet of your team’s expertise. Together, they form a knowledge base that Claude draws from automatically based on context. A junior developer gets senior-level guidance without asking for it.

Sharing Skills with Your Team

Personal skills (~/.claude/skills/) are yours alone. Use for personal preferences, experimental patterns, or expertise specific to your workflow.

Project skills (.claude/skills/ in the repo root) are shared via git:

# Create project-level skill
mkdir -p .claude/skills/domain-expert
# ... write SKILL.md ...

# Commit and push
git add .claude/skills/
git commit -m "feat: add domain-expert skill for payment processing rules"
git push

When teammates pull, they get the skill automatically. No installation, no configuration. This is the most effective way to standardize expertise across a team.

Guidelines for shared skills: - Keep project skills focused on domain expertise (business rules, architecture patterns) - Keep personal skills for workflow preferences (formatting, commit style) - Document why the skill exists in a comment at the top of SKILL.md - Review skill changes in PRs like any other code

Key Takeaways

• Build a skill when you catch yourself re-explaining context. If you paste the same checklist three times, it should be a skill.
• The description field determines everything. Invest more time in the description than in the skill content. Without reliable activation, the best expertise is useless.
• Use allowed-tools to constrain side effects. Read-only skills should be restricted to Read, Grep, Glob.
• Share project skills via git. This is team knowledge distribution with zero configuration.
• Don’t over-abstract. A skill for every micro-pattern creates maintenance burden. Build skills for expertise that’s stable, reusable, and valuable enough to maintain.

References

• Claude Code Guide — Skills Section — Full reference for skill structure, frontmatter, and tool restrictions
• Claude Code Hooks — Hooks complement skills: hooks enforce policy, skills provide expertise
• Context Engineering Is Architecture — Skills as a layer in the seven-tier context hierarchy
• AGENTS.md Patterns — Cross-tool project instructions (the Codex equivalent)