Master Claude Code Skills: The Complete Guide to Building Custom Skills

Master Claude Code Skills

The Complete Guide to Building Custom Skills v1.0 • Feb 2026 | By Carl Vellotti | The Full Stack PM

1: WHAT ARE SKILLS?

Skills are reusable instruction sets that teach Claude Code how to perform specific tasks. Save a workflow once as a skill, invoke it anytime with a slash command or let Claude auto-match it from your description.

The Flow:

1. User types: /deploy
2. Skill file loaded: Claude reads instructions
3. Claude follows instructions: Executes steps
4. Specialized output: Task completed

From Assistant to Specialist

Skills transform Claude from a general assistant into a domain specialist. Instead of re-explaining your deployment process, code review criteria, or content workflow every session, the skill file becomes Claude’s permanent playbook.

Skills are:

• Markdown instructions Claude follows
• Reusable across conversations
• Invoked via /cmd or auto-matched
• Scoped to project or global

Skills are NOT:

• Executable scripts or plugins
• Tied to a single session
• Always-on background rules
• Only for coding tasks

Key insight: A skill file is a prompt, not a program. It shapes how Claude behaves — it doesn’t execute code itself.

2: SKILL FILE ANATOMY

Every skill is a single SKILL.md file with YAML frontmatter + Markdown body. Example Path: .claude/skills/deploy-app/SKILL.md

Example File

---
name: deploy-app
version: 1.0.0
description: "When the user wants to deploy to production. Use when they say 'ship it' or 'push to prod'."
allowed-tools: "Read,Write,Edit,Bash"
---

# Deploy App
Instructions Claude follows when invoked.

## Steps
1. Run tests: `npm test`
2. Build: `npm run build`
3. Deploy: `vercel --prod`
4. Verify: URL returns 200

Frontmatter Fields

• name (Required): Becomes the slash command: /deploy-app
• description (Required): Trigger phrases for auto-matching (critical!)
• version (Optional): Track changes to your skill over time
• allowed-tools (Optional): Restrict which tools Claude can use

3: THE SKILL DEVELOPMENT WORKFLOW

1. Identify: Find a task you explain to Claude often.
2. Draft: Write SKILL.md with frontmatter + steps.
3. Test: Invoke with /name.
4. Iterate: Fix what Claude gets wrong.

Folder Structure

• Project Skills: Live in .claude/skills/ — only available in that project.
• Global Skills: Live in ~/.claude/skills/ — available in every project.

Tip: Start project-scoped. Promote to global after refining across projects.

4: KEY SKILL PATTERNS

• Tool Skill: Wraps a tool workflow (e.g., Deploy, lint, test suite).

• Tools: Read, Bash | Complexity: Low

• Generator Skill: Creates files from patterns (e.g., Components, routes).

• Tools: Read, Write, Glob | Complexity: Medium

• Reviewer Skill: Code review with specific criteria (e.g., Security, performance).

• Tools: Read, Grep, Bash | Complexity: Medium

• Research Skill: Gathers info across files/web (e.g., Docs, dependencies).

• Tools: Read, WebFetch, Bash | Complexity: High

• Orchestrator Skill: Coordinates multiple subagents (e.g., Parallel reviews).

• Tools: Task, Bash | Complexity: High

5: WRITING EFFECTIVE SKILLS

Be Specific

Bad: “Check the code” Good: “Run npm test, then npm run lint, then check for console.log statements in src/”

Include Examples

Show Claude exactly what you want:

## Expected Output Format
- File: path/to/file.js
- Issue: Description
- Fix: Suggested change

Handle Edge Cases

What should Claude do when tests fail? When files don’t exist? When commands error?

## Error Handling
If `npm test` fails:
1. Show the error output
2. Suggest common fixes
3. Ask if user wants to continue

Use Tool Constraints

Limit tools to prevent overreach:

allowed-tools: "Read,Edit,Bash"
# Claude won't use Write or WebFetch

6: SKILL TRIGGERS & AUTO-MATCHING

Slash Commands

/skill-name — explicit invocation

Auto-Matching

Claude scans skill descriptions for trigger phrases:

description: "When the user wants to deploy to production. Use when they say 'ship it' or 'push to prod'."

Triggers when you say:

• “Ship it to production”
• “Let’s push to prod”
• “Deploy the latest version”

Priority Order

1. Exact slash command match (/deploy)
2. Description phrase match (“push to prod”)
3. Claude’s general knowledge

7: ADVANCED PATTERNS

Skill Chaining

One skill calls another:

## Steps
1. Run `/test`
2. Run `/lint`
3. Run `/deploy`

Conditional Logic

Use Claude’s reasoning:

## Branching
If tests pass → deploy
If tests fail → show errors and stop

State Management

Skills can’t store state between runs, but can:

1. Read files for context
2. Use environment variables
3. Ask user for decisions

8: DEBUGGING SKILLS

Common Issues

Skill not triggering:

• Check description has relevant phrases
• Verify file is in correct .claude/skills/ folder
• Restart Claude session

Claude ignoring instructions:

• Make steps more explicit
• Add “DO NOT” directives
• Include concrete examples

Tool errors:

• Check allowed-tools includes needed tools
• Verify commands work in your environment
• Add error handling steps

Testing Checklist

• Skill loads with /name
• Auto-matches from description phrases
• Executes all steps correctly
• Handles errors gracefully
• Produces expected output format

9: EXAMPLE SKILLS

Simple: Run Tests

---
name: test
description: "Run the test suite. Use when user says 'run tests' or 'check tests'."
allowed-tools: "Bash"
---

# Run Tests
Execute the project's test suite.

## Steps
1. Run `npm test` (or `pytest`, `rake test`, etc.)
2. Show output
3. Report pass/fail status

Medium: Code Review

---
name: review
description: "Review code for security issues. Use when user says 'security review' or 'check for vulnerabilities'."
allowed-tools: "Read,Grep,Bash"
---

# Security Code Review
Check code for common security vulnerabilities.

## Steps
1. Search for hardcoded secrets (`grep -r "password\|api_key\|secret" src/`)
2. Check for SQL injection (`grep -r "execute.*%" src/`)
3. Verify input validation (`grep -r "request\.\(get\|post\)" src/`)
4. Report findings with file paths and line numbers

Complex: Full Deployment

---
name: deploy
description: "Full production deployment. Use when user says 'deploy to prod' or 'ship it'."
allowed-tools: "Read,Bash,Task"
---

# Production Deployment
Complete deployment workflow with safety checks.

## Steps
1. **Pre-flight:**
   - Run `/test`
   - Run `/lint`
   - Check git status for uncommitted changes

2. **Build:**
   - `npm run build` (or equivalent)
   - Verify build output exists

3. **Deploy:**
   - `vercel --prod` (or `git push production`, etc.)
   - Wait for deployment URL

4. **Verify:**
   - Check deployment health
   - Run smoke tests
   - Notify team if configured

10: BEST PRACTICES

Start Simple

Begin with tool skills before attempting orchestrators.

Document Assumptions

What environment does this skill assume? What project structure?

Version Skills

Use version: field to track changes.

Share Skills

Good skills are worth sharing across teams/projects.

Iterate Quickly

Skills are prompts — edit, test, repeat.

11: SKILL ECOSYSTEM

Built-in Skills

Claude Code comes with skills like:

• /help — Get help with using opencode
• /todo — Manage todo lists

Community Skills

Share skills via:

• GitHub repositories
• Team knowledge bases
• Internal documentation

Skill Discovery

Find skills by:

• Browsing .claude/skills/ folders
• Asking Claude “what skills are available?”
• Checking project documentation

12: GETTING STARTED

Your First Skill

1. Create .claude/skills/hello/SKILL.md
2. Add frontmatter with name and description
3. Write simple instructions
4. Test with /hello

Skill Ideas

• Run your test suite
• Deploy to staging
• Generate component boilerplate
• Check code style
• Update dependencies
• Backup database
• Generate documentation

FINAL THOUGHTS

Skills turn Claude from a general assistant into your personal specialist. They capture institutional knowledge, enforce best practices, and eliminate repetitive explanations.

Start today: Pick one task you explain to Claude weekly and skill it. In a month, you’ll have a toolbox that makes every project faster and more consistent.

Remember: Skills are living documents. Update them as your workflows evolve. The best skill is the one you actually use.

Carl Vellotti is a product leader and AI workflow specialist. He writes about developer tools, AI automation, and building better software at The Full Stack PM.

This guide is open for feedback and contributions. Found an error? Have a better pattern? Submit an issue or PR.