TL;DR: Claude Code skills are custom instruction files that transform repetitive prompts into reusable commands. This guide shows you how to create your own skills, with practical examples for code review, commits, and documentation.
You’ve probably spent hours copying and pasting prompts between conversations. Repeating the same instruction. Adjusting the context. Explaining the project again.
Claude Code skills solve this.
They turn prompts you use all the time into reusable commands. Instead of typing the same instruction every time, you invoke a skill with a short command — and Claude executes it with full context.
Skills are your shortcut to consistency. You define once, use forever.
What are skills and why you should create your own
A skill is a Markdown file with structured instructions that Claude Code loads automatically.
When you use a skill, Claude:
- reads the instructions from the file
- understands the project context
- executes the task with prior knowledge
The difference between using Claude and having a personalized assistant
Without skills, every conversation starts from scratch:
- you explain the project
- you define the context
- you repeat instructions
- you adjust the tone
With skills, Claude enters already knowing:
- what you want
- how you want it
- which patterns to follow
Insight Skills transform Claude from a generic assistant into a specialist for your project.
When it makes sense to create a skill
You should create a skill when:
- you repeat the same type of prompt frequently
- you need consistency in reviews, commits, or documentation
- you want Claude to follow a specific pattern
- you work on a project with well-defined rules
- you automate tasks involving multiple steps
It doesn’t make sense to create a skill for:
- one-off tasks
- quick questions
- code exploration without defined patterns
The anatomy of a skill
A skill is simple: a SKILL.md file in a specific directory.
The SKILL.md file
Basic structure:
.claude/skills/
└── skill-name/
└── SKILL.md
Required frontmatter
The file needs to start with YAML frontmatter:
---
name: skill-name
description: short description of the skill
---
# Objective
[explain what the skill does]
# Process
[steps Claude should follow]
Skill body
The skill body contains:
- Objective: what the skill should do
- Process: steps in sequence
- Rules: restrictions and preferences
- Examples: when useful
- Expected output: result format
The more specific the skill, the better the result.
How to create your first skill
Step 1: Identify the repetitive task
Ask: “What task do I do frequently that could be automated?”
Examples:
- review code before commit
- generate function documentation
- create tests for new features
- format commits semantically
Step 2: Define the objective
Write in one sentence what the skill should do:
“The skill should review code and point out security, performance, and readability issues.”
Step 3: Write the prompt
Transform the objective into structured instructions:
---
name: code-review
description: reviews code focusing on security, performance, and readability
---
# Objective
Review code before commit, identifying problems in three categories:
1. Security
2. Performance
3. Readability
# Process
## 1. Security analysis
Check for:
- SQL injection
- XSS
- authentication/authorization
- sensitive data exposure
## 2. Performance analysis
Check for:
- inefficient loops
- N+1 queries
- necessary memoization
- bundle size (frontend)
## 3. Readability analysis
Check for:
- variable names
- long functions
- necessary comments
- cyclomatic complexity
# Expected output
For each problem found, return:
- file and line
- problem category
- severity (high/medium/low)
- fix suggestion
Step 4: Test and iterate
- Save the file to
.claude/skills/code-review/SKILL.md - Open Claude Code
- Type
/code-review(or use the skill) - Check if the output is as expected
- Adjust instructions if needed
Practical tip Start simple. A 10-line well-defined skill works better than a 100-line generic one.
Examples of practical skills
Code review skill
# .claude/skills/code-review/SKILL.md
---
name: code-review
description: reviews code with focus on security and quality
---
# Objective
Review code changes before commit.
# Criteria
1. **Security**: vulnerabilities, data exposure
2. **Performance**: bottlenecks, bad queries
3. **Maintainability**: names, structure, duplication
# Output
List of problems found with:
- location
- severity
- suggestion
Semantic commit skill
# .claude/skills/semantic-commit/SKILL.md
---
name: semantic-commit
description: creates commits following conventional commits
---
# Objective
Generate semantic commit messages.
# Rules
- Use prefixes: feat, fix, docs, refactor, test, chore
- Message in English
- Maximum 72 characters in title
- Explain the "why" in the body
# Output
Co-Authored-By: Claude noreply@anthropic.com
Automatic documentation skill
# .claude/skills/doc-generator/SKILL.md
---
name: doc-generator
description: generates documentation for functions and components
---
# Objective
Document code with clear comments.
# Format
For functions:
- purpose description
- parameters with types
- expected return
- usage examples
For components:
- description
- props
- examples
# Rules
- Don't document the obvious
- Use simple language
- Keep updated
Best practices when creating skills
Be specific, not generic
Bad:
“Review the code.”
Good:
“Review the code looking for security vulnerabilities, performance issues, and style guide violations.”
Include project context
Skills can access project files. Use this:
Read the CLAUDE.md file to understand the project patterns.
Check if the code follows the defined rules.
Prefer small, focused skills
One skill that does one thing well is better than a skill that does ten things poorly.
Document the intent
Always make clear:
- what the skill does
- when to use it
- what output to expect
Advanced skills
Skills with arguments
Skills can receive parameters:
Use the doc-generator skill for function X.
Claude understands the context and applies the skill correctly.
Skills that use other skills
You can create skills that compose others:
---
name: pre-commit
description: executes full review before commit
---
# Process
1. Run skill code-review
2. Run skill semantic-commit
3. Check tests
MCP integration
Skills can use MCP servers to:
- search the web
- access external APIs
- read databases
This expands automation possibilities.
Organizing your skills
Project skills vs global skills
Project skills: located in .claude/skills/ inside the project
- specific to that code
- versioned with the project
Global skills: located in ~/.claude/skills/
- apply to all projects
- personal patterns
Version control
Skills are code. They should be:
- versioned in git
- tested
- updated when necessary
Common mistakes when creating skills
Instructions too vague. “Improve the code” is not a useful instruction. Be specific about what to improve and how.
Skills too long. A skill with 50 rules becomes noise. Claude ignores parts. Prefer focused skills with 5 to 10 clear rules.
Ignoring project context. Generic skills that don’t consider local architecture generate irrelevant suggestions. Whenever possible, include reference to project pattern files.
Not testing. A skill that works for one case may fail for another. Test with different scenarios before trusting.
Not updating. Projects change, skills become outdated. Periodically review if the rules still make sense.
FAQ
Do I need to know programming to create skills?
No. Skills are text files with instructions in natural language. If you can write a clear prompt, you can create a skill.
Are skills the same as MCP servers?
No. MCP servers are external integrations (APIs, databases, services). Skills are internal instructions for Claude. Skills can use MCP servers, but they’re different concepts.
Can I share skills between projects?
Yes. Global skills (in ~/.claude/skills/) work in all projects. Project skills are versioned with the code.
How to debug a skill that doesn’t work as expected?
- Check if the file is in the correct location
- Confirm if the frontmatter is valid
- Test the instruction as a direct prompt first
- Simplify the skill to isolate the problem
Is there a repository of ready-made skills?
The community shares skills in GitHub repositories and forums. But the ideal is to create your own — they’re specific to your workflow and project.
Conclusion
Claude Code skills transform repetitive prompts into reusable commands.
Instead of explaining the same context every time, you define once and use consistently. This saves time, reduces errors, and ensures quality.
For solopreneurs working alone, skills are a productivity multiplier. They work like external memory — storing patterns, rules, and processes you don’t need to repeat.
Start by identifying a task you do frequently. Create a simple skill. Test. Iterate.
The best skill isn’t the most complex. It’s the one you actually use.