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:

1. Loading: Claude reads the skill markdown at session start
2. Context Integration: Skill instructions become part of Claude's system context
3. Persistence: Instructions remain active throughout the session
4. 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

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.