Skip to main content

Agent Skills - Dynamic Instructions for Claude

Key Point: Skills are folders of instructions, scripts, and resources that Claude loads dynamically to improve performance on specialized tasks. They teach Claude how to complete specific tasks in a repeatable way, from company branding to technical workflows to personal automation.

🚀 Quick Start​

Basic Skill Structure​

---
name: my-skill-name
description: A clear description of what this skill does and when to use it
---

# My Skill Name

[Add your instructions here that Claude will follow when this skill is active]

## Examples
- Example usage 1
- Example usage 2

## Guidelines
- Guideline 1
- Guideline 2

Creating Your First Skill​

  1. Create a folder for your skill (e.g., my-skill/)
  2. Add SKILL.md file with frontmatter and instructions
  3. Upload to Claude or register in Claude Code
  4. Use the skill by mentioning it in conversations

🎯 What Are Skills?​

Skills are specialized instruction sets that:

  • Enhance Claude's capabilities for specific tasks
  • Provide consistent behavior across similar tasks
  • Include context and examples for better performance
  • Can reference external resources like scripts, templates, and data files
  • Work across platforms (Claude.ai, Claude Code, API)

Why Use Skills?​

  • ✅ Consistency: Same quality results every time
  • ✅ Efficiency: No need to repeat instructions
  • ✅ Scalability: Share across teams and projects
  • ✅ Specialization: Domain-specific expertise
  • ✅ Composability: Combine multiple skills for complex tasks

📚 Skill Categories​

1. Creative & Design Skills​

Art & Illustration​

---
name: pixel-art-designer
description: Create detailed pixel art designs with character sheets and animations
---

# Pixel Art Designer

When creating pixel art:
1. Define grid size and color palette
2. Focus on clear silhouettes
3. Use dithering for shading
4. Maintain consistent pixel density

Music Composition​

---
name: music-composer
description: Compose original music in ABC notation format
---

# Music Composer

Generate music compositions in ABC notation:
- Use proper header fields (X, T, M, L, K)
- Follow standard notation conventions
- Include chord symbols where appropriate

2. Development & Technical Skills​

Testing & QA​

---
name: web-app-tester
description: Systematically test web applications for bugs and issues
---

# Web App Tester

Testing methodology:
1. Functional testing (forms, navigation, interactions)
2. UI/UX testing (layout, responsiveness, accessibility)
3. Performance testing (load times, resource usage)
4. Security testing (XSS, CSRF, SQL injection)

MCP Server Generation​

---
name: mcp-server-generator
description: Generate Model Context Protocol server implementations
---

# MCP Server Generator

Create MCP servers with:
- Tool definitions following MCP spec
- Resource endpoints for data access
- Prompt templates for common tasks
- Error handling and validation

3. Enterprise & Communication Skills​

Brand Communications​

---
name: brand-voice
description: Create content following company brand guidelines
---

# Brand Voice

Follow these brand guidelines:
- Tone: Professional yet approachable
- Voice: Clear, concise, action-oriented
- Avoid: Jargon, passive voice, corporate speak
- Use: Active voice, specific examples, customer benefits

Documentation​

---
name: technical-writer
description: Create clear, structured technical documentation
---

# Technical Writer

Documentation structure:
1. Overview and purpose
2. Prerequisites and requirements
3. Step-by-step instructions
4. Code examples with explanations
5. Troubleshooting common issues

4. Document Skills (Production-Grade)​

PDF Skills​

  • Extract: Extract text, tables, and metadata from PDFs
  • Create: Generate PDFs with proper formatting
  • Analyze: Analyze PDF structure and content
  • Form Fields: Extract and process PDF form data

Word Documents (DOCX)​

  • Create: Generate formatted Word documents
  • Edit: Modify existing documents while preserving formatting
  • Templates: Use and populate document templates
  • Styles: Apply consistent styling and formatting

Presentations (PPTX)​

  • Create: Build presentation decks with slides
  • Format: Apply themes and consistent design
  • Content: Add text, images, charts, and tables
  • Export: Generate presentation files

Spreadsheets (XLSX)​

  • Create: Generate Excel workbooks with formulas
  • Analyze: Process and analyze spreadsheet data
  • Format: Apply conditional formatting and styles
  • Charts: Create data visualizations

🔧 Creating Custom Skills​

Skill Anatomy​

my-skill/
├── SKILL.md           # Main skill definition (required)
├── examples/          # Example inputs/outputs
│   ├── example1.md
│   └── example2.md
├── templates/         # Reusable templates
│   └── template.json
├── scripts/          # Helper scripts
│   └── helper.py
└── resources/        # Additional resources
    └── data.csv

SKILL.md Format​

---
name: skill-name
description: Clear description of what this skill does and when to use it
version: 1.0.0
author: Your Name
tags: [tag1, tag2, tag3]
---

# Skill Name

Brief overview of the skill's purpose.

## When to Use This Skill

- Use case 1
- Use case 2
- Use case 3

## Instructions

Detailed step-by-step instructions that Claude will follow.

### Step 1: Initial Action
What Claude should do first.

### Step 2: Processing
How to process the information.

### Step 3: Output
How to format and deliver the result.

## Examples

### Example 1: Basic Usage
**Input:**

Example input here


**Output:**

Example output here


### Example 2: Advanced Usage
**Input:**

More complex input


**Output:**

Expected complex output


## Guidelines

- Important guideline 1
- Important guideline 2
- Important guideline 3

## Error Handling

How to handle common errors or edge cases.

## Resources

Links to additional resources, templates, or documentation.

Best Practices for Skill Creation​

  1. Clear Scope: Define exactly what the skill does
  2. Specific Instructions: Be explicit about steps and expectations
  3. Include Examples: Show both input and expected output
  4. Error Handling: Address common failure cases
  5. Consistent Format: Use standard markdown structure
  6. Version Control: Track changes and improvements
  7. Documentation: Explain usage and limitations

💡 Real-World Skill Examples​

Example 1: Code Review Skill​

---
name: code-reviewer
description: Perform systematic code reviews following best practices
---

# Code Reviewer

## Review Checklist

### 1. Code Quality
- [ ] Follows language-specific style guidelines
- [ ] Consistent naming conventions
- [ ] Proper error handling
- [ ] Adequate logging

### 2. Performance
- [ ] Efficient algorithms and data structures
- [ ] No obvious performance bottlenecks
- [ ] Proper resource management

### 3. Security
- [ ] Input validation
- [ ] No SQL injection vulnerabilities
- [ ] Proper authentication/authorization
- [ ] Sensitive data handling

### 4. Testing
- [ ] Adequate test coverage
- [ ] Edge cases covered
- [ ] Integration tests where needed

## Review Output Format

**Summary**: [One-line summary of changes]

**Strengths**:
- [Positive aspects]

**Issues Found**:
- **Critical**: [Issues that must be fixed]
- **Major**: [Important improvements]
- **Minor**: [Nice-to-have improvements]

**Recommendations**:
- [Specific actionable suggestions]

Example 2: API Documentation Generator​

---
name: api-doc-generator
description: Generate comprehensive API documentation from code
---

# API Documentation Generator

## Documentation Structure

For each endpoint, include:

### Endpoint Information
- **Method**: GET, POST, PUT, DELETE, etc.
- **Path**: /api/v1/resource
- **Description**: What this endpoint does

### Request

**Headers:**
```json
{
  "Authorization": "Bearer {token}",
  "Content-Type": "application/json"
}

Parameters:

NameTypeRequiredDescription
idstringYesResource identifier

Body:

{
  "field": "value"
}

Response​

Success (200):

{
  "status": "success",
  "data": {}
}

Error (400):

{
  "status": "error",
  "message": "Error description"
}

Example Usage​

curl -X POST https://api.example.com/v1/resource \
  -H "Authorization: Bearer token" \
  -H "Content-Type: application/json" \
  -d '{"field": "value"}'

Notes​

  • Additional implementation details
  • Known limitations
  • Related endpoints

### Example 3: Data Analysis Skill

```markdown
---
name: data-analyzer
description: Perform comprehensive data analysis with visualizations
---

# Data Analyzer

## Analysis Workflow

### 1. Data Understanding
- Examine data structure and types
- Check for missing values
- Identify data quality issues
- Understand data distributions

### 2. Exploratory Analysis
- Summary statistics
- Correlation analysis
- Outlier detection
- Pattern identification

### 3. Visualization
- Distribution plots for numerical data
- Bar charts for categorical data
- Correlation heatmaps
- Time series plots where applicable

### 4. Insights & Recommendations
- Key findings from the analysis
- Data quality observations
- Recommendations for next steps

## Output Format

**Data Overview**
- Rows: [count]
- Columns: [count]
- Data types: [summary]
- Missing values: [summary]

**Key Findings**
1. [Finding 1 with supporting evidence]
2. [Finding 2 with supporting evidence]
3. [Finding 3 with supporting evidence]

**Visualizations**
[Description of charts/graphs created]

**Recommendations**
- [Actionable recommendation 1]
- [Actionable recommendation 2]

🔌 Integration Methods​

Claude.ai (Web Interface)​

  1. Access Skills: Available to paid plans automatically
  2. Upload Custom Skills:
    • Go to Settings → Skills
    • Upload your skill folder
    • Activate the skill
  3. Use Skills: Mention skill name in conversations

Claude Code​

# Add Anthropic's skill marketplace
/plugin marketplace add anthropics/skills

# Browse and install
/plugin
# Select: Browse and install plugins
# Select: anthropic-agent-skills
# Choose skill set: document-skills or example-skills

# Or install directly
/plugin install document-skills@anthropic-agent-skills
/plugin install example-skills@anthropic-agent-skills

# Use in conversation
"Use the PDF skill to extract form fields from file.pdf"

Claude API​

import anthropic

client = anthropic.Anthropic(api_key="your-api-key")

# Upload custom skill
with open('my-skill/SKILL.md', 'r') as f:
    skill_content = f.read()

# Use skill in conversation
response = client.messages.create(
    model="claude-3-5-sonnet-20241022",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "Use the code-reviewer skill to review this code: ..."
        }
    ],
    system=[
        {
            "type": "text",
            "text": skill_content
        }
    ]
)

Skills API Quickstart​

// Node.js example
const Anthropic = require('@anthropic-ai/sdk');
const fs = require('fs');

const client = new Anthropic({
  apiKey: process.env.ANTHROPIC_API_KEY,
});

// Load skill
const skill = fs.readFileSync('./my-skill/SKILL.md', 'utf8');

// Use skill
const message = await client.messages.create({
  model: 'claude-3-5-sonnet-20241022',
  max_tokens: 1024,
  system: [{ type: 'text', text: skill }],
  messages: [
    {
      role: 'user',
      content: 'Apply this skill to the following task: ...'
    }
  ]
});

console.log(message.content);

🎓 Advanced Skill Patterns​

Multi-Step Workflows​

---
name: research-workflow
description: Comprehensive research and analysis workflow
---

# Research Workflow

## Phase 1: Information Gathering
1. Identify key search terms
2. Gather sources from multiple channels
3. Verify source credibility
4. Extract relevant information

## Phase 2: Analysis
1. Categorize information by theme
2. Identify patterns and trends
3. Cross-reference sources
4. Note conflicting information

## Phase 3: Synthesis
1. Create structured outline
2. Develop key arguments
3. Support with evidence
4. Address counterarguments

## Phase 4: Documentation
1. Write executive summary
2. Detail findings with citations
3. Include visualizations
4. Provide recommendations

Conditional Logic​

---
name: adaptive-helper
description: Adapt responses based on user expertise level
---

# Adaptive Helper

## Determine User Level

Ask: "What's your experience level with this topic?"

- **Beginner**: Use simple language, more examples
- **Intermediate**: Balanced explanation with technical terms
- **Expert**: Technical details, advanced concepts

## Response Format by Level

### For Beginners:
1. Start with basic concepts
2. Use analogies and metaphors
3. Provide step-by-step guidance
4. Include lots of examples

### For Intermediate:
1. Brief concept review
2. Focus on practical application
3. Introduce advanced techniques
4. Reference best practices

### For Experts:
1. Skip basics
2. Discuss edge cases
3. Explore optimizations
4. Compare approaches

Resource Integration​

---
name: template-generator
description: Generate documents using predefined templates
---

# Template Generator

## Available Templates

Reference these template files:
- `templates/report.md`: Standard report format
- `templates/proposal.md`: Business proposal format
- `templates/memo.md`: Internal memo format

## Template Usage

1. **Select appropriate template** based on document type
2. **Load template content** from resources
3. **Parse template variables** (marked with {{variable}})
4. **Populate with user data**
5. **Format and validate** output

## Template Variables

Standard variables across templates:
- `{{date}}`: Current date
- `{{author}}`: Document author
- `{{title}}`: Document title
- `{{company}}`: Company name
- `{{content}}`: Main content

## Example Usage

Input:
```json
{
  "template": "report",
  "title": "Q4 Sales Analysis",
  "author": "John Doe",
  "content": "Sales increased by 25%..."
}

Output: Formatted report using report.md template


## 📊 Skill Performance Tips

### 1. Clear Instructions
```markdown
❌ Bad: "Make it better"
✅ Good: "Improve code readability by: 1) Adding descriptive variable names, 2) Breaking complex functions into smaller ones, 3) Adding inline comments for complex logic"

2. Concrete Examples​

❌ Bad: "Format output properly"
✅ Good: 
**Example Output:**
```json
{
  "status": "success",
  "data": {
    "id": 123,
    "name": "Example"
  }
}

### 3. Error Handling
```markdown
## Error Cases

**Missing Required Field:**
- Identify which field is missing
- Explain why it's required
- Suggest how to provide it

**Invalid Format:**
- Show the invalid input
- Explain the expected format
- Provide a corrected example

4. Scope Definition​

## In Scope
- Feature A: [specific capabilities]
- Feature B: [specific capabilities]

## Out of Scope
- Feature X: Use skill-name-x instead
- Feature Y: Requires manual intervention

🛠️ Testing Your Skills​

Testing Checklist​

  1. Basic Functionality

    • Skill loads without errors
    • Instructions are clear and actionable
    • Examples work as expected

  2. Edge Cases

    • Handles missing information gracefully
    • Deals with invalid inputs
    • Responds to ambiguous requests

  3. Performance

    • Produces consistent results
    • Completes in reasonable time
    • Output quality meets standards

  4. Integration

    • Works with other skills
    • Compatible across platforms
    • Resources load correctly

Testing Script​

# test_skill.py
import anthropic
import json

def test_skill(skill_path, test_cases):
    """Test a skill with multiple test cases"""
    
    client = anthropic.Anthropic()
    
    # Load skill
    with open(f'{skill_path}/SKILL.md', 'r') as f:
        skill = f.read()
    
    results = []
    
    for test in test_cases:
        response = client.messages.create(
            model='claude-3-5-sonnet-20241022',
            max_tokens=1024,
            system=[{'type': 'text', 'text': skill}],
            messages=[{
                'role': 'user',
                'content': test['input']
            }]
        )
        
        results.append({
            'test_name': test['name'],
            'input': test['input'],
            'expected': test['expected'],
            'actual': response.content[0].text,
            'passed': check_expected(response.content[0].text, test['expected'])
        })
    
    return results

def check_expected(actual, expected):
    """Compare actual output with expected criteria"""
    # Implement your validation logic
    return True

# Example usage
test_cases = [
    {
        'name': 'Basic usage',
        'input': 'Test input 1',
        'expected': 'Expected behavior 1'
    },
    {
        'name': 'Edge case',
        'input': 'Test input 2',
        'expected': 'Expected behavior 2'
    }
]

results = test_skill('./my-skill', test_cases)
print(json.dumps(results, indent=2))

🔗 Partner Skills​

Notion Skills for Claude​

Notion has created official skills for working with Notion databases and pages:

  • Create Pages: Generate new Notion pages with formatting
  • Query Databases: Search and filter Notion databases
  • Update Content: Modify existing pages and properties
  • Template Management: Use and create Notion templates

Learn more: Notion Skills for Claude

Community Skills​

The Agent Skills ecosystem is growing with contributions from:

  • Development teams building internal workflows
  • Individual creators sharing specialized skills
  • Organizations standardizing team practices
  • Tool vendors integrating their platforms

📚 Official Resources​

🎯 Summary​

Agent Skills are essential for:

  • 🎯 Specialized Tasks: Domain-specific expertise
  • 🔄 Consistent Results: Repeatable quality
  • 📈 Scalability: Share across teams
  • 🛠️ Customization: Tailored to your needs
  • 🔗 Integration: Works across platforms

Key Advantages:

  • Simple to create (just markdown)
  • Platform-agnostic (works everywhere)
  • Composable (combine multiple skills)
  • Versioned and shareable
  • Production-ready (used by Claude internally)

Skill Categories:

  1. Creative & Design: Art, music, design workflows
  2. Development & Technical: Testing, code generation, MCP servers
  3. Enterprise & Communication: Brand voice, documentation, workflows
  4. Document Skills: PDF, DOCX, PPTX, XLSX processing

Best Practices:

  • Clear, specific instructions
  • Concrete examples
  • Error handling
  • Defined scope
  • Version control
  • Thorough testing

Bottom Line: Agent Skills transform Claude from a general assistant into a specialized expert for your specific tasks. Whether you're creating documents with brand guidelines, testing web applications, or automating complex workflows, skills provide the structured instructions and context Claude needs to deliver consistent, high-quality results. Essential for teams and individuals who want to scale AI capabilities across repeated tasks.