What is an AI Skill? Understanding Reusable AI Patterns
Discover what AI skills are, how they differ from prompts, and why they are essential for scaling AI capabilities across projects and teams.
What is an AI Skill? Understanding Reusable AI Patterns
You have probably written the same prompt multiple times. "Format this code according to our style guide." "Review this PR for security issues." "Generate documentation for this function." Each time, you craft the prompt slightly differently, sometimes getting better results, sometimes worse.
Skills solve this problem. A skill is a reusable package of instructions that teaches Claude how to handle a specific task or domain. Instead of writing prompts from scratch, you load a skill that contains tested, optimized instructions. The skill persists across your session, shaping how Claude responds to related requests.
This guide explains what skills are, how they work, and why they matter for AI-powered development.
The Problem Skills Solve
Prompt Repetition
Every developer hits this pattern:
Day 1: "Can you review this code for security issues?"
Day 2: "Review this for security vulnerabilities please"
Day 3: "Check this code for security problems, focus on input validation"
Day 4: "Security review: look for injection, XSS, auth issues"
Four days, four different prompts, four inconsistent results. The LLM does not remember what you meant by "security review" yesterday. Each prompt starts from zero.
Inconsistent Results
Without standardized instructions, outputs vary:
Monday's code review:
The code looks fine. You might want to add some error handling.
Tuesday's code review:
## Security Analysis
### Critical Issues
1. SQL Injection vulnerability at line 45...
### High Priority
2. Missing input validation in processUser()...
Same request, dramatically different depth and format. The difference is not the code; it is how you phrased the prompt that day.
Lost Knowledge
Teams develop expertise through trial and error:
- "Add 'be specific about line numbers' for better reviews"
- "Include 'explain your reasoning' for more thorough analysis"
- "Mention 'consider edge cases' for better testing"
This knowledge lives in Slack messages, personal notes, and memory. When someone leaves, the knowledge leaves too.
What Skills Are
Definition
A skill is a markdown file containing instructions that Claude loads at the start of a session and maintains throughout. Skills live in ~/.claude/skills/ and automatically activate based on context or explicit loading.
Anatomy of a Skill
# TypeScript Code Review
You are a TypeScript expert reviewing code for quality and correctness.
## Review Criteria
When reviewing TypeScript code, evaluate:
### Type Safety
- Proper use of TypeScript types
- Avoiding `any` type without justification
- Null safety with optional chaining and nullish coalescing
- Generic type usage where appropriate
### Code Quality
- Clear naming conventions
- Appropriate function sizes
- Single responsibility principle
- DRY (Don't Repeat Yourself)
### Error Handling
- Try-catch for async operations
- Proper error typing
- User-friendly error messages
- Error boundary patterns
## Output Format
Structure your reviews as:
1. **Summary** - One paragraph overall assessment
2. **Critical Issues** - Must fix before merge
3. **Improvements** - Should consider
4. **Suggestions** - Nice to have
5. **Positive Notes** - What was done well
For each issue:
- File and line number
- Code snippet
- Explanation
- Suggested fix
How Skills Work
When you start Claude Code with a skill loaded:
- Loading: Claude reads the skill markdown at session start
- Context Integration: Skill instructions become part of Claude's system context
- Persistence: Instructions remain active throughout the session
- Automatic Application: Relevant requests trigger skill-informed responses
The skill is not re-read for each prompt. It shapes Claude's behavior for the entire session.
Skills vs. Prompts
| Aspect | Prompt | Skill |
|---|---|---|
| Lifespan | Single request | Entire session |
| Storage | Typed each time | File in ~/.claude/skills/ |
| Consistency | Varies by phrasing | Standardized |
| Shareability | Copy-paste | Version controlled |
| Complexity | Usually brief | Can be comprehensive |
When to Use Each
Use prompts when:
- One-off, unique request
- Experimenting with approaches
- Quick questions
Use skills when:
- Task will repeat
- Consistency matters
- Multiple people need the same behavior
- Instructions are complex
Skill Properties
Persistent
Skills stay active. You load them once, and they shape all related interactions until you explicitly unload them or end the session.
Load skill → Work for hours → Skill still active
Contrast with prompts that only affect the immediate response.
Composable
Skills can work together. Load multiple skills for multi-faceted tasks:
Load: typescript-expert + security-review + documentation
Result: Reviews consider TypeScript patterns, security issues, AND documentation quality
Each skill contributes its expertise without interfering with others.
Portable
Skills are files. They move between:
- Projects (copy to new repo's
.claude/skills/) - Team members (commit to shared repository)
- Machines (sync via dotfiles)
- Organizations (publish to skill marketplace)
Zero Dependencies
Skills are pure markdown. They need:
- No installation
- No compilation
- No runtime
- No API keys
Place the file in the right directory, and it works.
What Skills Contain
Domain Knowledge
Information Claude needs to know about your specific domain:
## Our API Structure
- All endpoints return JSON with { data, error, meta }
- Errors include { code, message, details }
- Authentication uses Bearer tokens in Authorization header
- Rate limits are in X-RateLimit-* headers
Claude does not know your API structure by default. This skill teaches it.
Process Instructions
How to approach specific tasks:
## Code Review Process
1. First, run the code mentally - trace execution paths
2. Check for obvious bugs and logic errors
3. Evaluate code structure and organization
4. Assess naming and readability
5. Look for edge cases and error handling
6. Consider performance implications
7. Review test coverage
8. Provide actionable feedback
This ensures reviews follow a consistent methodology.
Output Formats
How responses should be structured:
## Review Output Format
### Summary
One paragraph overview
### Issues Found
#### Critical
| Issue | Location | Description | Fix |
|-------|----------|-------------|-----|
#### Moderate
...
### Recommendations
Bulleted list of improvements
### Praise
What was done well
Standardized output makes reviews easier to parse and act on.
Constraints
What Claude should and should not do:
## Constraints
### Do
- Be specific with line numbers
- Explain reasoning
- Provide example fixes
- Acknowledge good patterns
### Do Not
- Nitpick style if linter will catch it
- Suggest rewrites that change functionality
- Be condescending
- Ignore context from PR description
Guardrails keep Claude focused and appropriate.
Skill Categories
Code Quality Skills
# Code Quality Standards
Evaluate code against these standards:
## Readability
- Self-documenting names
- Appropriate comments for complex logic
- Consistent formatting
- Clear control flow
## Maintainability
- Modular design
- Low coupling, high cohesion
- Clear interfaces
- Appropriate abstraction levels
...
Domain Expert Skills
# Healthcare Data Compliance
When working with healthcare data, ensure:
## HIPAA Compliance
- No PHI in logs
- Encryption at rest and in transit
- Access controls documented
- Audit trails maintained
## Data Handling
- Minimum necessary principle
- De-identification when possible
- Secure transmission protocols
- Retention policy compliance
...
Workflow Skills
# Git Commit Workflow
When creating commits:
## Commit Message Format
type(scope): subject
body (optional)
footer (optional)
## Types
- feat: New feature
- fix: Bug fix
- docs: Documentation
- refactor: Code restructuring
- test: Test additions
- chore: Maintenance
...
Output Format Skills
# API Documentation Format
Document APIs using this structure:
## Endpoint Documentation
### [METHOD] /path
**Description:** What this endpoint does
**Authentication:** Required/Optional
**Request:**
\`\`\`json
{
"field": "type - description"
}
\`\`\`
**Response:**
\`\`\`json
{
"field": "type - description"
}
\`\`\`
**Errors:**
| Code | Message | Meaning |
|------|---------|---------|
...
Creating Your First Skill
Step 1: Identify the Need
What task do you repeat? What instructions do you keep retyping?
Example: "I keep asking Claude to review my Python code for our team's style."
Step 2: Document What Works
Write down the instructions that get good results:
Review Python code for:
- PEP 8 compliance
- Our team's naming conventions (snake_case for functions, PascalCase for classes)
- Proper type hints
- Docstrings in Google format
- No magic numbers
- Error handling patterns
Step 3: Structure as a Skill
# Python Code Review
You are reviewing Python code for our team.
## Style Requirements
### PEP 8
Follow PEP 8 with these additions:
- Line length: 100 characters
- Import grouping: stdlib, third-party, local
### Naming
- Functions: snake_case
- Classes: PascalCase
- Constants: UPPER_SNAKE_CASE
- Private members: _leading_underscore
### Type Hints
All public functions require type hints:
\`\`\`python
def process_user(user_id: int, options: dict[str, Any] | None = None) -> User:
\`\`\`
### Documentation
Use Google-style docstrings:
\`\`\`python
def process_data(input: list[int]) -> list[int]:
"""Process and transform input data.
Args:
input: List of integers to process
Returns:
Transformed list of integers
Raises:
ValueError: If input is empty
"""
\`\`\`
## Review Output
For each issue:
1. Line number
2. Current code
3. Problem
4. Suggested fix
Step 4: Save and Test
# Save the skill
mkdir -p ~/.claude/skills
vim ~/.claude/skills/python-review.md
# Test it
claude
> Load skill: python-review
> Review this code: [paste code]
Step 5: Iterate
Based on results, refine the skill. Add examples. Clarify ambiguities. Remove instructions that do not help.
Skill Best Practices
Be Specific
Vague:
Review code for quality issues.
Specific:
Review code for:
- Null pointer potential
- Resource leaks
- Race conditions
- Error handling gaps
- Security vulnerabilities (injection, XSS)
Provide Examples
## Good Example
\`\`\`python
def get_user(user_id: int) -> User | None:
"""Retrieve user by ID."""
try:
return db.users.get(user_id)
except DatabaseError as e:
logger.error(f"Failed to get user {user_id}: {e}")
return None
\`\`\`
## Bad Example
\`\`\`python
def getUser(id):
return db.users.get(id)
\`\`\`
Examples clarify expectations better than descriptions.
Structure Logically
# Skill Name
## Overview
Brief description of what this skill does.
## When to Use
Situations where this skill applies.
## Core Instructions
The main behavioral guidance.
## Output Format
How responses should be structured.
## Examples
Demonstrations of correct behavior.
## Constraints
What to avoid or limitations to respect.
Keep Focused
One skill, one purpose. If you find yourself adding unrelated instructions, split into multiple skills.
Too broad:
# Everything Skill
- Code review
- Documentation
- Testing
- Deployment
- Database design
Focused:
# Code Review Skill
Everything about reviewing code.
Summary
Skills transform how you work with AI. Instead of crafting prompts from scratch each time, you build reusable packages of instructions that:
- Persist across your entire session
- Standardize outputs for consistency
- Share easily with teams and projects
- Compose together for complex tasks
- Require no dependencies or setup
Start with tasks you repeat often. Document what works. Package into skills. Iterate based on results. Soon you will have a library of capabilities that make you faster and more consistent with every AI interaction.
Ready to understand how skills compare to other AI tools? Continue to Skills vs Commands vs Agents for a detailed comparison.