SKILL_CREATION_GUIDE.md

Complete Guide to Creating Claude Skills

Table of Contents

1. What Are Skills?
2. Core Principles
3. Skill Architecture
4. 6-Step Creation Process
5. Planning Your Skill
6. Implementation Guide
7. Best Practices
8. Real-World Example
9. Common Patterns
10. Troubleshooting

---

What Are Skills?

Definition

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

1. Specialized Workflows - Multi-step procedures for specific domains
2. Tool Integrations - Instructions for working with specific file formats or APIs
3. Domain Expertise - Company-specific knowledge, schemas, and business logic
4. 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:

1. Level 1: Metadata (~100 words) - Always loaded

   • Skill name and description
   • Used for skill selection

2. Level 2: SKILL.md (~5k words) - Loaded when skill triggers

   • Main usage guide
   • Common patterns and examples
   • References to deeper content

3. 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:

1. Scope: What functionality should this skill support?

   • Example: "Spotify skill: Create playlists, search music, control playback"

2. Use Cases: What would users say?

   • "Create a playlist of The Beatles songs"
   • "Build a chill evening playlist"
   • "What's currently playing?"

3. Variations: What different ways will users need it?

   • "Create playlists by artist, theme, lyrics, or specific songs"

4. 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:

1. "How would I do this from scratch?"
2. "What code would I write repeatedly?"
3. "What reference material would help?"
4. "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:

1. Create each script from your plan
2. Test thoroughly
3. Add comprehensive docstrings
4. 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:

1. Organize by topic
2. Include examples
3. Add tables/structures
4. Use clear headers

Prepare Assets:

1. Gather templates
2. Ensure they're production-ready
3. 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:

1. Validates the skill:

   • YAML frontmatter format
   • Required fields present
   • Description quality
   • File organization

2. Packages into .skill file (ZIP with .skill extension)

3. 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:

1. Use the skill on actual tasks
2. Observe what works and what doesn't
3. Identify needed improvements
4. Update SKILL.md or resources
5. Test changes
6. 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:

1. What problem does it solve?

   • Example: "Manage Spotify playlists and playback programmatically"

2. Who will use it?

   • Example: "Users who need music automation"

3. What are the main operations?

   • Example: "Create playlists, search music, control playback"

4. What knowledge is needed?

   • Example: "OAuth setup, Spotify API basics"

5. 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

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

❌ DON'T

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

Performance Tips

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

Security Tips

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

---

Real-World Example

Creating a Spotify Playlist Generator Skill

Let's walk through creating the Spotify skill step-by-step:

Step 1: Understand (Requirements)

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

Packaging Phase

• Remove unused template files
• Run package_skill.py
• Fix any validation errors
• Verify .skill file contents
• Test unpacking and usage

Documentation Phase

• Create overview document
• Write quick start guide
• Include troubleshooting
• Add real-world examples
• Document all assumptions

Deployment Phase

• Share .skill file with users
• Gather feedback
• Plan iterations
• Version control (v1.0, v1.1, etc.)
• Update based on usage

---

Conclusion

Creating effective skills involves:

1. Understanding your use cases clearly
2. Planning what resources you'll need
3. Initializing with the proper structure
4. Implementing quality code and documentation
5. Packaging into a distributable format
6. 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! 🚀