Complete Guide to Creating Claude Skills

October 21, 2025 · View on GitHub

What Are Skills?
Core Principles
Skill Architecture
6-Step Creation Process
Planning Your Skill
Implementation Guide
Best Practices
Real-World Example
Common Patterns
Troubleshooting

Skills are modular, self-contained packages that extend Claude's capabilities by providing specialized knowledge, workflows, and tools. They transform Claude from a general-purpose assistant into a specialized expert equipped with procedural knowledge and domain expertise.

What Skills Provide

Specialized Workflows - Multi-step procedures for specific domains
Tool Integrations - Instructions for working with specific file formats or APIs
Domain Expertise - Company-specific knowledge, schemas, and business logic
Bundled Resources - Scripts, references, and assets for complex repetitive tasks

Types of Skills You Can Create

API Integration Skills - Connect to external services (like our Spotify skill)
Document Processing - Work with DOCX, PDF, XLSX files
Code Generation - Templates and boilerplate for specific frameworks
Business Logic - Company processes, policies, and workflows
Data Analysis - Database schemas, query templates
Specialized Tools - Domain-specific utilities and helpers
Brand Guidelines - Assets, templates, and styling rules
Learning Materials - Structured educational content

Core Principles

1. Concise is Key 🎯

The context window is shared across:

System prompt
Conversation history
Other skills' metadata
User request
Your skill content

Rule: Only add context Claude doesn't already have. Challenge every sentence: "Does Claude really need this?"

Good Practice: Prefer concise examples over verbose explanations.

# ❌ Bad (Too verbose)
The Spotify API is a web service provided by Spotify that allows 
developers to access music data and control playback through HTTP 
requests. OAuth 2.0 is an authorization protocol...

# ✅ Good (Concise)
Use SpotifyClient with OAuth 2.0 credentials. Token auto-refreshes.

2. Set Appropriate Degrees of Freedom 🛣️

Match specificity to task complexity:

High Freedom (Text-based instructions)

Use when: Multiple approaches are valid
Example: "Create a blog post" - many valid styles
Token cost: Low (guidance only)

# Blog Post Guide
Consider your audience, tone, and structure.
Format with headers, examples, and clear sections.

Medium Freedom (Pseudocode with parameters)

Use when: Preferred pattern exists but variation is OK
Example: "Process user data" - structure matters but implementation varies
Token cost: Medium

def process_data(input_file, **options):
    # Template showing structure
    load_data()
    transform_data(**options)
    save_results()

Low Freedom (Specific scripts, few parameters)

Use when: Operations are fragile or must be consistent
Example: "Rotate PDF by 90 degrees" - single best way
Token cost: Higher but necessary

# Exact script to be executed
def rotate_pdf(input_path, degrees, output_path):
    # Precise implementation

Analogy: A narrow bridge with cliffs needs specific guardrails (low freedom), an open field allows many routes (high freedom).

3. Context Window Efficiency 💾

Skills use Progressive Disclosure - load content as needed:

Level 1: Metadata (~100 words) - Always loaded
- Skill name and description
- Used for skill selection
Level 2: SKILL.md (~5k words) - Loaded when skill triggers
- Main usage guide
- Common patterns and examples
- References to deeper content
Level 3: Resources (Unlimited) - Loaded on-demand
- Scripts can execute without loading
- References loaded only when needed
- Assets used directly in output

4. Single Source of Truth

Information should live in ONE place:

✅ SKILL.md: Essential workflows and quick examples
✅ references/api_guide.md: Detailed API documentation
✅ scripts/process.py: Reusable code implementation
✅ assets/template.docx: Output templates

❌ DON'T: Duplicate same info in multiple files

Skill Architecture

Directory Structure

skill-name/
├── SKILL.md                    # Required: Main documentation
├── scripts/                    # Optional: Executable code
│   ├── main_script.py
│   └── helper_script.py
├── references/                 # Optional: Reference documentation
│   ├── api_reference.md
│   └── schema.md
└── assets/                     # Optional: Output templates
    ├── template.docx
    └── logo.png

What Each Component Does

SKILL.md (Required)

Contains:

YAML frontmatter (name, description)
Main usage guide
Quick start examples
Links to detailed resources

Size: <5,000 words (< 500 lines) Purpose: Quick reference and navigation

Example YAML Frontmatter:

---
name: spotify-api
description: Connect to Spotify API and manage playlists, search music, 
control playback, and create intelligent playlists by artist, theme, 
lyrics, or specific songs. Handles OAuth authentication and provides 
40+ methods for playlist management, search, user data, and playback control.
---

Best Practices for SKILL.md:

Start with overview (1-2 sentences)
Provide quick start with code
Show common workflows
Reference deeper docs
Use examples liberally
Keep it navigable

Scripts Folder (Optional)

For: Reusable, deterministic code that gets executed

When to Use:

Code that's written repeatedly
Complex operations needing reliability
Performance-critical tasks
Encapsulated logic

Example:

# scripts/spotify_client.py
class SpotifyClient:
    def __init__(self, credentials):
        self.credentials = credentials
    
    def get_user_playlists(self, limit=50):
        # Implementation
        pass

Benefits:

Token efficient (execute without loading)
Maintains consistency
Easier to version and update
Can be tested independently

References Folder (Optional)

For: Documentation to reference while working

When to Use:

API endpoint documentation
Database schemas
Detailed workflow guides
Company policies
Data structures

Example:

references/
├── api_reference.md       # All endpoints
├── authentication.md      # OAuth setup
└── data_schemas.md        # Table structures

Design Pattern:

# Main SKILL.md
Quick start section...

## Advanced Usage
See references/advanced_guide.md

## API Reference
See references/api_endpoints.md

Assets Folder (Optional)

For: Files used in output (NOT loaded to context)

When to Use:

Templates (DOCX, PPTX)
Images and logos
Fonts
Boilerplate code
Sample documents

Example:

assets/
├── slides_template.pptx
├── logo.png
└── frontend_boilerplate/
    ├── index.html
    └── style.css

Benefits:

Claude can use without loading into context
Faster processing
Large files stay out of context window

What NOT to Include

Don't add extraneous files:

❌ README.md (use SKILL.md)
❌ INSTALLATION_GUIDE.md (put in SKILL.md)
❌ CHANGELOG.md (not for Claude)
❌ TODO.md (internal notes)
❌ Duplicate documentation
❌ Unnecessary helper files

6-Step Creation Process

Step 1: Understand the Skill with Concrete Examples

Goal: Crystal clear understanding of what the skill does

Questions to Ask:

Scope: What functionality should this skill support?
- Example: "Spotify skill: Create playlists, search music, control playback"
Use Cases: What would users say?
- "Create a playlist of The Beatles songs"
- "Build a chill evening playlist"
- "What's currently playing?"
Variations: What different ways will users need it?
- "Create playlists by artist, theme, lyrics, or specific songs"
Constraints: What are the limits?
- "Spotify API rate limits: 429,400 requests per 30 minutes"

Example Exercise for Spotify:

Use Case	Trigger	Required Knowledge
Create artist playlist	"Make Beatles playlist"	Search API, artist top tracks, playlist creation
Create mood playlist	"Build chill playlist"	Search with keywords, track filtering
Control playback	"Play next song"	Device management, playback API
Get recommendations	"Suggest songs like..."	Recommendations engine, seed parameters

Output: Written list of 5-10 concrete use cases

Step 2: Plan Reusable Skill Contents

Goal: Identify what resources you'll need

For Each Use Case, Ask:

"How would I do this from scratch?"
"What code would I write repeatedly?"
"What reference material would help?"
"What templates or assets would I need?"

Spotify Example Analysis:

Use Case	Reusable Content Needed
Create artist playlist	spotify_client.py (search artists), (get top tracks), (create playlist)
Create mood playlist	spotify_client.py (search with keywords), playlist_creator.py (intelligent creation)
Control playback	spotify_client.py (playback methods)
All	authentication_guide.md, api_reference.md

Output: Plan for scripts, references, and assets

Scripts:
  - spotify_client.py (40+ API methods)
  - playlist_creator.py (intelligent creation)

References:
  - authentication_guide.md (OAuth setup)
  - api_reference.md (endpoints)

Assets:
  - None needed

Step 3: Initialize the Skill

Goal: Create the skill directory structure

Command:

python3 /mnt/skills/examples/skill-creator/scripts/init_skill.py <skill-name> --path <output-directory>

Example:

python3 /mnt/skills/examples/skill-creator/scripts/init_skill.py spotify-api --path /home/claude/skills

What It Creates:

spotify-api/
├── SKILL.md (template with TODO)
├── scripts/
│   └── example.py (delete if not needed)
├── references/
│   └── api_reference.md (template)
└── assets/
    └── example_asset.txt (delete if not needed)

Next Steps:

Review generated files
Delete unused templates
Plan implementation

Step 4: Edit the Skill

Goal: Implement and document the skill

4a. Implement Reusable Resources

Start with Scripts:

Create each script from your plan
Test thoroughly
Add comprehensive docstrings
Include error handling

Example (spotify_client.py):

class SpotifyClient:
    """Authenticated Spotify Web API client."""
    
    def __init__(self, client_id: str, client_secret: str):
        """Initialize with credentials."""
        self.client_id = client_id
        self.client_secret = client_secret
    
    def get_user_playlists(self, limit: int = 50) -> List[Dict]:
        """Get user's playlists.
        
        Args:
            limit: Number of playlists (max 50)
            
        Returns:
            List of playlist objects
        """
        # Implementation with error handling

Create References:

Organize by topic
Include examples
Add tables/structures
Use clear headers

Prepare Assets:

Gather templates
Ensure they're production-ready
Test in actual output

4b. Write SKILL.md

Structure Template:

---
name: skill-name
description: What it does and when to use it. Include specific keywords.
---

# Skill Title

## Overview
1-2 sentences explaining what it enables.

## Core Capabilities
List 5-10 main features.

## Quick Start
Code example with minimal setup.

## Common Workflows
3-5 workflow sections with examples.

## Advanced Features
Link to reference files for deep dives.

## References
- `references/guide1.md` - For X
- `references/guide2.md` - For Y

Writing Guidelines:

Use imperative form ("Do this", not "You can do this")
Lead with benefits
Provide working code examples
Link to detailed resources
Keep body <5,000 words

Description Best Practices:

Be specific (not "work with APIs" but "connect to Spotify API")
Include key terms (helps skill selection)
Mention when to use it
Include main features

❌ Bad: "API integration skill for music"

✅ Good: "Connect to Spotify API and manage playlists, search music, 
control playback, and create intelligent playlists by artist, theme, 
lyrics, or specific songs. Handles OAuth authentication and provides 
40+ methods for playlist management."

Step 5: Package the Skill

Goal: Create distributable .skill file

Command:

python3 /mnt/skills/examples/skill-creator/scripts/package_skill.py <path/to/skill-folder>

Optional Output Directory:

python3 /mnt/skills/examples/skill-creator/scripts/package_skill.py <path/to/skill-folder> ./dist

What Happens:

Validates the skill:
- YAML frontmatter format
- Required fields present
- Description quality
- File organization
Packages into .skill file (ZIP with .skill extension)
Preserves directory structure

If Validation Fails:

Fix reported errors
Re-run packaging
Check for:
- Missing YAML fields
- Invalid skill names
- Poor descriptions
- Broken references

Step 6: Iterate Based on Usage

Goal: Improve based on real-world usage

Iteration Cycle:

Use the skill on actual tasks
Observe what works and what doesn't
Identify needed improvements
Update SKILL.md or resources
Test changes
Repackage if needed

Common Improvements:

Clearer examples
Better error handling
Additional methods
More reference material
Better organization

Planning Your Skill

Define Your Skill Clearly

Answer These Questions:

What problem does it solve?
- Example: "Manage Spotify playlists and playback programmatically"
Who will use it?
- Example: "Users who need music automation"
What are the main operations?
- Example: "Create playlists, search music, control playback"
What knowledge is needed?
- Example: "OAuth setup, Spotify API basics"
What are the constraints?
- Example: "Rate limits, API quotas"

Create a Feature Matrix

Feature               | Scope | Complexity | Priority
---------------------|-------|------------|----------
Create playlist       | High  | Medium     | 1
Add tracks           | High  | Low        | 2
Search music         | High  | Medium     | 3
Control playback     | Medium| Medium     | 4
User recommendations | Low   | High       | 5

Identify Your Resources

Resource Type	Items	Purpose
Scripts	spotify_client.py	Core API operations
	playlist_creator.py	High-level utilities
References	api_reference.md	Endpoint documentation
	authentication.md	OAuth setup
Assets	None	N/A

Design Your Documentation

SKILL.md
├── Overview
├── Core Capabilities
├── Quick Start
├── Common Workflows
│   ├── Create Playlist by Artist
│   ├── Create Themed Playlist
│   └── Control Playback
└── References
    ├── API Reference
    └── Authentication Guide

Implementation Guide

1. Set Up Your Development Environment

# Create skill directory
mkdir -p ~/skills/my-skill/scripts
mkdir -p ~/skills/my-skill/references
mkdir -p ~/skills/my-skill/assets

# Initialize with script
python3 /mnt/skills/examples/skill-creator/scripts/init_skill.py my-skill --path ~/skills

2. Implement Scripts

Best Practices:

# ✅ Good: Clear, documented, tested

class MyClient:
    """Client for external service."""
    
    def __init__(self, api_key: str):
        """Initialize with credentials.
        
        Args:
            api_key: Authentication key
            
        Raises:
            ValueError: If api_key is empty
        """
        if not api_key:
            raise ValueError("API key required")
        self.api_key = api_key
    
    def fetch_data(self, resource_id: str) -> Dict:
        """Fetch data for resource.
        
        Args:
            resource_id: ID of resource
            
        Returns:
            Dictionary with resource data
            
        Raises:
            requests.HTTPError: If request fails
        """
        try:
            response = requests.get(
                f"https://api.example.com/{resource_id}",
                headers={"Authorization": f"Bearer {self.api_key}"}
            )
            response.raise_for_status()
            return response.json()
        except requests.exceptions.RequestException as e:
            raise ValueError(f"Failed to fetch data: {e}")

# Test your implementation
if __name__ == "__main__":
    client = MyClient(api_key="test_key")
    data = client.fetch_data("resource_123")
    print(data)

3. Create Reference Documentation

Structure:

# API Reference

## Table of Contents
1. [Authentication](#authentication)
2. [Endpoints](#endpoints)
3. [Error Handling](#error-handling)

## Authentication
Explain how to authenticate...

## Endpoints
| Method | Path | Description |
|--------|------|-------------|

## Error Handling
Common errors and solutions...

4. Write SKILL.md

Template:

---
name: my-skill
description: Specific description of what skill does and when to use it.
---

# My Skill

## Overview
One or two sentences explaining what this skill enables.

## Core Capabilities

1. **Feature One** - What it does
2. **Feature Two** - What it does
3. **Feature Three** - What it does

## Quick Start

```python
from my_module import MyClient

client = MyClient(api_key="your_key")
data = client.fetch_data("resource_id")
print(data)

Common Workflows

Workflow 1: Basic Operation

# Example code
result = client.do_something()

See references/advanced_guide.md for more details.

Workflow 2: Complex Operation

# Example code
result = client.do_complex_thing(option="value")

References

references/api_reference.md - Full API documentation
references/authentication.md - Setup guide


### 5. Test and Validate

```bash
# Validate before packaging
python3 /mnt/skills/examples/skill-creator/scripts/package_skill.py ./my-skill

# Test imports
python3 -c "from my_skill.scripts.my_module import MyClient; print('Success!')"

# Run example code
python3 ./my-skill/scripts/example_test.py

6. Package and Distribute

# Create .skill file
python3 /mnt/skills/examples/skill-creator/scripts/package_skill.py ./my-skill ./dist

# Verify package
unzip -l ./dist/my-skill.skill

Best Practices

✅ DO

Keep SKILL.md concise - <5,000 words
Provide working examples - Users should copy-paste
Document assumptions - "Requires Python 3.7+"
Test scripts thoroughly - Before packaging
Use clear naming - spotify_client.py, not sc.py
Add error handling - Helpful error messages
Reference related resources - Link between docs
Update based on feedback - Iterate and improve
Use imperative language - "Create", not "You can create"
Include security info - How to handle credentials

❌ DON'T

Duplicate documentation - One source of truth
Include unnecessary files - Keep it lean
Write verbose explanations - Assume Claude is smart
Leave scripts untested - Run before packaging
Use vague names - Be specific
Hide errors - Let them surface
Create circular references - Avoid A→B→A links
Forget about rate limits - Document constraints
Hard-code credentials - Use environment variables
Over-document - Every paragraph should justify its existence

Performance Tips

Batch operations - When possible
Cache results - Reduce API calls
Lazy load resources - Load only when needed
Minimize script size - Remove dead code
Use async - For I/O-bound operations

Security Tips

Never embed secrets - Use environment variables
Validate inputs - Check all parameters
Document scopes - What permissions needed?
Handle errors gracefully - Don't expose internals
Use HTTPS - Always for APIs

Use Cases:
1. Create playlist from artist name
2. Create themed playlist (mood/genre)
3. Create playlist from lyrics
4. List user playlists
5. Add tracks to playlist
6. Control playback

Knowledge Needed:
- OAuth 2.0 authentication
- Spotify API endpoints
- Rate limits (429,400 req/30 min)
- Playlist structure
- Track metadata

Step 2: Plan Resources

Scripts:
  spotify_client.py
    - 40+ API methods
    - OAuth token management
    - Error handling
    
  playlist_creator.py
    - Intelligent creation methods
    - Track deduplication
    - Batch processing

References:
  authentication_guide.md
    - OAuth setup
    - Credential management
    - Security best practices
    
  api_reference.md
    - All endpoints
    - Response formats
    - Error codes

Step 3: Initialize

python3 init_skill.py spotify-api --path ~/skills

Step 4: Implement

Created:

spotify_client.py (20 KB, 40+ methods)
playlist_creator.py (12 KB, 6 methods)
authentication_guide.md (10 KB)
api_reference.md (9 KB)
SKILL.md (7 KB with examples)

Step 5: Package

python3 package_skill.py ~/skills/spotify-api ./dist
# Creates: spotify-api.skill (16 KB)

Step 6: Iterate

Based on user feedback:

Added more examples
Clarified authentication
Improved error messages
Added troubleshooting section

Common Patterns

Pattern 1: High-Level Guide with References

SKILL.md
├── Quick Start (code example)
└── See references/ for details
    ├── references/advanced.md
    ├── references/api.md
    └── references/setup.md

Use When: Skill has many options/frameworks

Pattern 2: Domain-Specific Organization

SKILL.md (Overview)
references/
├── finance.md (revenue, billing)
├── sales.md (opportunities)
└── support.md (tickets, cases)

Use When: Multiple distinct domains

Pattern 3: Workflow with Templates

SKILL.md (Main workflows)
scripts/
├── template.py (base template)
├── workflow1.py (variant A)
└── workflow2.py (variant B)
assets/
├── template.docx
└── example_output.pdf

Use When: Document generation or coding tasks

Pattern 4: API Client Wrapper

SKILL.md (Overview)
scripts/
├── client.py (main API wrapper)
├── auth.py (authentication)
└── utils.py (helpers)
references/
├── api_reference.md (endpoints)
└── authentication.md (setup)

Use When: Integrating external APIs

Troubleshooting

Package Validation Errors

"YAML frontmatter format invalid"

# ❌ Wrong
description This is my skill

# ✅ Correct
---
name: my-skill
description: This is my skill
---

"Required field 'description' missing"

# Must have:
---
name: my-skill
description: Clear description of what skill does
---

"Description too vague"

❌ "Document processing skill"
✅ "Create and modify Word documents (.docx) with tracked changes, 
   comments, and formatted text. Handle document creation, editing, 
   merging, and analysis."

Script Errors

ImportError when packaging

# Check imports are available
import requests  # Install if needed: pip install requests

# Use absolute imports
from spotify_client import SpotifyClient  # ✅
from .spotify_client import SpotifyClient  # ✅ (relative)

Reference links broken

# ❌ Wrong (file doesn't exist)
See references/nonexistent.md

# ✅ Correct (file exists)
See references/api_guide.md

Performance Issues

SKILL.md too large

Move detailed examples to references/
Create separate guides
Use summary tables

Scripts loading slowly

Break into smaller modules
Use lazy imports
Document execution expectations

Context Window Usage

SKILL.md exceeding 5,000 words

Total: 8,000 words → TOO LARGE

Move to references/:
- Detailed examples (3,000 words)
- Advanced options (2,000 words)
- Troubleshooting (1,000 words)

Keep in SKILL.md:
- Overview
- Quick start
- Common workflows
- Navigation

Checklist for Skill Creation

Planning Phase

Define skill scope and purpose
List 5-10 concrete use cases
Identify needed resources (scripts, refs, assets)
Plan directory structure
Research best practices for your domain

Implementation Phase

Initialize skill with init_skill.py
Create and test all scripts
Write comprehensive reference docs
Prepare assets/templates
Write clear SKILL.md
Add code examples throughout

Quality Assurance Phase

Test all scripts work correctly
Verify all references are accurate
Check YAML frontmatter is valid
Validate description quality
Test code examples from SKILL.md
Review for typos/clarity

Understanding your use cases clearly
Planning what resources you'll need
Initializing with the proper structure
Implementing quality code and documentation
Packaging into a distributable format
Iterating based on real-world feedback

By following these principles and steps, you can create skills that Claude can use effectively to accomplish specialized tasks.

Remember:

Keep it concise - Context window is valuable
Document clearly - Examples are worth a thousand words
Test thoroughly - Before packaging
Iterate continuously - Based on feedback
Follow best practices - They exist for a reason

Happy skill creating! 🚀