How to Create Claude Code Skills: The Complete Guide from Anthropic

Learn how to build professional Claude Code Skills from scratch using Anthropic's official patterns and best practices. Transform Claude from a general-purpose assistant into a specialized powerhouse for your workflows.

About the Author: I'm James Bennett, Lead Engineer at WebSearchAPI.ai, where I architect the core retrieval engine enabling LLMs and AI agents to access real-time, structured web data with over 99.9% uptime and sub-second query latency. With a background in distributed systems and search technologies, I've reduced AI hallucination rates by 45% through advanced ranking and content extraction pipelines for RAG systems. My expertise includes AI infrastructure, search technologies, large-scale data integration, and API architecture for real-time AI applications.

Credentials: B.Sc. Computer Science (University of Cambridge), M.Sc. Artificial Intelligence Systems (Imperial College London), Google Cloud Certified Professional Cloud Architect, AWS Certified Solutions Architect, Microsoft Azure AI Engineer, Certified Kubernetes Administrator, TensorFlow Developer Certificate.

Introduction: Why Skills Matter for Claude Code

Last week, I found myself repeatedly explaining to Claude how to format API documentation for our internal tools. Every conversation, the same setup. The same instructions. The same context-building before I could actually get work done.

Then I discovered Claude Code Skills—and everything changed.

Skills are Anthropic's answer to the problem of repetitive context-setting. Instead of treating Claude as a blank slate every time, you can package your expertise, workflows, and domain knowledge into reusable modules that Claude automatically discovers and applies when relevant.

📊 Stats Alert:

Claude Code has attracted 115,000 developers and processes 195 million lines of code weekly, according to PPC Land. With an estimated annualized revenue of $130 million, it represents one of the fastest-growing developer tools in the AI coding market.

According to Google's 2025 DORA Report, 90% of developers now use AI coding assistants, with 65% reporting heavy reliance on these tools. In 2025, 41% of all code is AI-generated or AI-assisted—making the ability to customize and extend AI capabilities more valuable than ever.

In this guide, I'll walk you through Anthropic's official skill-creator methodology—covering everything from core design principles to production deployment patterns.

🎯 Goal: Master the complete skill creation process: understand the architecture, apply core principles, and build production-ready skills that transform how you work with Claude.

Skills vs Sub-Agents vs MCP: Understanding the Differences

Before diving into skills, it's important to understand how they compare to other Claude Code extension mechanisms:

💡 When to Use Each:

• Skills: When you need Claude to follow specific procedures, use domain knowledge, or execute deterministic scripts repeatedly
• Sub-Agents: When you need to parallelize work, delegate complex research, or isolate task context
• MCP: When you need to interact with external systems, APIs, or real-time data sources

Skills are the simplest way to extend Claude's capabilities without external infrastructure—making them ideal for packaging team knowledge and workflows.

What Are Claude Code Skills?

The Core Concept

Skills are modular, self-contained packages that extend Claude's capabilities by providing specialized knowledge, workflows, and tools. Think of them as "onboarding guides" for specific domains or tasks—they transform Claude from a general-purpose agent into a specialized agent equipped with procedural knowledge that no model can fully possess.

According to Anthropic's official skills repository, skills are designed to teach Claude how to complete specific objectives repeatedly—whether that's applying brand guidelines to documents, executing organizational workflows, or automating personal processes.

💡 Expert Insight:

The fundamental innovation of Skills is efficiency. Instead of spending tokens on repeated instructions, you package expertise once and let Claude activate it automatically when relevant. It's the difference between training someone every day versus hiring an expert who already knows the job.

What Skills Provide

Key Characteristics

Core Design Principles

Before diving into implementation, understand the three principles that separate effective skills from bloated ones.

Principle 1: Concise is Key

The context window is a public good. Skills share it with everything else Claude needs: system prompt, conversation history, other skills' metadata, and the actual user request.

Default assumption: Claude is already very smart. Only add context Claude doesn't already have.

Challenge each piece of information:

• "Does Claude really need this explanation?"
• "Does this paragraph justify its token cost?"

📌 Pro Tip:

Prefer concise examples over verbose explanations. A single well-crafted example communicates more than paragraphs of description—and costs fewer tokens.

Principle 2: Set Appropriate Degrees of Freedom

Match the level of specificity to the task's fragility and variability:

💡 Expert Insight:

Think of Claude as exploring a path: a narrow bridge with cliffs needs specific guardrails (low freedom), while an open field allows many routes (high freedom). Match your skill's guidance to the terrain.

Principle 3: Progressive Disclosure

Skills use a three-level loading system to manage context efficiently:

Level 1 - Metadata (Always Loaded)

• Name and description in YAML frontmatter
• ~100 tokens per skill
• Enables discovery without consuming context

Level 2 - SKILL.md Body (When Triggered)

• Main instructions and procedures
• Target under 500 lines / 5k tokens
• Loaded when Claude determines skill is relevant

Level 3 - Bundled Resources (As Needed)

• Scripts, references, assets
• Unlimited capacity
• Scripts can execute without loading into context

⚠️ Warning: Keep SKILL.md body to essentials and under 500 lines. If approaching this limit, split content into separate reference files. This prevents context bloat while maintaining capability.

Anatomy of a Skill

Required Structure

Every skill follows this structure:

skill-name/
├── SKILL.md (required)
│   ├── YAML frontmatter metadata (required)
│   │   ├── name: (required)
│   │   └── description: (required)
│   └── Markdown instructions (required)
└── Bundled Resources (optional)
    ├── scripts/     - Executable code
    ├── references/  - Documentation for context
    └── assets/      - Files for output (templates, etc.)

SKILL.md Format

---
name: your-skill-name
description: What this skill does and when to use it. Include trigger contexts, file types, task types, and keywords users might mention.
---
 
# Your Skill Name
 
[Instructions section]
Clear, step-by-step guidance for Claude.
 
[Examples section]
Concrete input/output examples.

Frontmatter Requirements

⚠️ Critical: The description field is the primary triggering mechanism. Include both what the skill does AND specific triggers/contexts for when to use it. The body is only loaded after triggering—putting "When to Use" sections in the body is ineffective.

Bundled Resources

Scripts (scripts/)

Executable code (Python/Bash/etc.) for tasks requiring deterministic reliability.

When to include:

• Same code being rewritten repeatedly
• Deterministic reliability needed
• Complex operations prone to errors

Benefits:

• Token efficient
• Deterministic results
• Can execute without loading into context

# Example: scripts/rotate_pdf.py
#!/usr/bin/env python3
"""Rotate PDF pages by specified degrees."""
 
import argparse
from pypdf import PdfReader, PdfWriter
 
def rotate_pdf(input_path, output_path, degrees):
    reader = PdfReader(input_path)
    writer = PdfWriter()
 
    for page in reader.pages:
        page.rotate(degrees)
        writer.add_page(page)
 
    with open(output_path, "wb") as f:
        writer.write(f)
 
if __name__ == "__main__":
    parser = argparse.ArgumentParser()
    parser.add_argument("input", help="Input PDF path")
    parser.add_argument("output", help="Output PDF path")
    parser.add_argument("--degrees", type=int, default=90)
    args = parser.parse_args()
    rotate_pdf(args.input, args.output, args.degrees)

References (references/)

Documentation loaded as needed into context.

When to include:

• Database schemas
• API documentation
• Domain knowledge
• Company policies
• Detailed workflow guides

Best practice: If files are large (>10k words), include grep search patterns in SKILL.md.

📌 Pro Tip:

Information should live in either SKILL.md or references—not both. Keep only essential procedural instructions in SKILL.md; move detailed reference material to references files. This keeps SKILL.md lean while making information discoverable.

Assets (assets/)

Files not loaded into context but used in output.

When to include:

• Templates (PowerPoint, documents)
• Brand assets (logos, images)
• Boilerplate code
• Fonts

Benefits: Separates output resources from documentation, enables Claude to use files without loading them.

What NOT to Include

A skill should only contain essential files. Do NOT create:

• README.md
• INSTALLATION_GUIDE.md
• QUICK_REFERENCE.md
• CHANGELOG.md

The skill should contain only what an AI agent needs to do the job—not auxiliary context about creation, setup procedures, or user-facing documentation.

The Six-Step Skill Creation Process

Step 1: Understand with Concrete Examples

Skip only when usage patterns are already clearly understood.

To create an effective skill, gather concrete examples of how it will be used. Ask questions like:

• "What functionality should this skill support?"
• "Can you give examples of how this skill would be used?"
• "What would a user say that should trigger this skill?"

💡 Expert Insight:

Don't overwhelm users with questions. Start with the most important ones and follow up as needed. Conclude when you have a clear sense of the functionality the skill should support.

Example for an image-editor skill:

• User might say: "Remove the red-eye from this image"
• User might say: "Rotate this image 90 degrees"
• User might say: "Resize this photo to 800x600"

Step 2: Plan Reusable Contents

Analyze each example by:

1. Considering how to execute the example from scratch
2. Identifying what scripts, references, and assets would help when executing repeatedly

Example Analysis:

Step 3: Initialize the Skill

When creating from scratch, use Anthropic's initialization script:

scripts/init_skill.py <skill-name> --path <output-directory>

The script:

• Creates the skill directory at specified path
• Generates SKILL.md template with proper frontmatter
• Creates example resource directories
• Adds example files that can be customized or deleted

Manual initialization alternative:

mkdir -p my-skill/{scripts,references,assets}
touch my-skill/SKILL.md

Step 4: Edit the Skill

Remember: you're creating this for another instance of Claude to use. Include information that would be beneficial and non-obvious.

Start with Reusable Contents

Implement the scripts, references, and assets identified in Step 2.

Important: Test all scripts by actually running them. If there are many similar scripts, test a representative sample to ensure they work.

Delete any example files not needed for the skill.

Write the SKILL.md

Writing guideline: Always use imperative/infinitive form.

Frontmatter example:

---
name: docx-processor
description: Comprehensive document creation, editing, and analysis with support for tracked changes, comments, formatting preservation, and text extraction. Use when Claude needs to work with professional documents (.docx files) for: (1) Creating new documents, (2) Modifying or editing content, (3) Working with tracked changes, (4) Adding comments, or any other document tasks.
---

Body structure:

# Skill Name
 
## Getting Started
[Essential first steps]
 
## Core Workflows
[Step-by-step procedures]
 
## Extended Capabilities
- **Feature A**: See [FEATURE_A.md](references/feature_a.md)
- **Feature B**: See [FEATURE_B.md](references/feature_b.md)
 
## Examples
[Concrete input/output pairs]

Step 5: Package the Skill

Once development is complete, package into a distributable .skill file:

scripts/package_skill.py <path/to/skill-folder>

Optional output directory:

scripts/package_skill.py <path/to/skill-folder> ./dist

The packaging script:

1. Validates the skill automatically:

   • YAML frontmatter format and required fields
   • Naming conventions and directory structure
   • Description completeness and quality
   • File organization and resource references

2. Packages if validation passes, creating a .skill file (zip format)

If validation fails, fix errors and run again.

Step 6: Iterate Based on Usage

Skills improve through real-world usage:

1. Use the skill on real tasks
2. Notice struggles or inefficiencies
3. Identify updates needed to SKILL.md or resources
4. Implement changes and test again

📌 Pro Tip:

Iteration often happens right after using the skill, with fresh context of how it performed. Capture improvement ideas immediately while they're vivid.

Progressive Disclosure Patterns

Pattern 1: High-Level Guide with References

# PDF Processing
 
## Quickstart
Extract text with pdfplumber:
[code example]
 
## Additional Capabilities
- **Form filling**: See [FORMS.md](references/forms.md)
- **API reference**: See [REFERENCE.md](references/reference.md)
- **Examples**: See [EXAMPLES.md](references/examples.md)

Claude loads reference files only when needed.

Pattern 2: Domain-Specific Organization

For skills with multiple domains, organize by domain:

bigquery-skill/
├── SKILL.md (overview and navigation)
└── references/
    ├── finance.md (revenue, billing metrics)
    ├── sales.md (opportunities, pipeline)
    ├── product.md (API usage, features)
    └── marketing.md (campaigns, attribution)

When user asks about sales metrics, Claude only reads sales.md.

Pattern 3: Framework/Variant Organization

For skills supporting multiple frameworks:

cloud-deploy/
├── SKILL.md (workflow + provider selection)
└── references/
    ├── aws.md (AWS deployment patterns)
    ├── gcp.md (GCP deployment patterns)
    └── azure.md (Azure deployment patterns)

When user chooses AWS, Claude only reads aws.md.

Pattern 4: Conditional Details

Show basic content, link to advanced:

# DOCX Processing
 
## Creating Documents
Use docx-js for new documents. See [DOCX-JS.md](references/docx-js.md).
 
## Editing Documents
For simple edits, modify the XML directly.
 
**For tracked changes**: See [REDLINING.md](references/redlining.md)
**For OOXML details**: See [OOXML.md](references/ooxml.md)

Important Guidelines

• Avoid deeply nested references - Keep references one level deep from SKILL.md
• Structure longer files - For files >100 lines, include a table of contents at top

Workflow Patterns

Sequential Workflows

For complex multi-step tasks, break work into distinct steps with upfront overview:

## Filling a PDF Form
 
This process involves 5 steps:
1. Analyze the form structure
2. Create field mapping
3. Validate the mapping
4. Fill the form
5. Verify the output
 
### Step 1: Analyze the Form
[Detailed instructions]
 
### Step 2: Create Field Mapping
[Detailed instructions]
...

Conditional Workflows

For tasks with decision branches:

## Document Processing
 
First, determine the task type:
- **Creating new document**: Go to Section A
- **Editing existing document**: Go to Section B
- **Converting format**: Go to Section C
 
### Section A: Creating New Documents
[Specific steps for creation]
 
### Section B: Editing Existing Documents
[Specific steps for editing]
...

Output Patterns

Template Pattern (Strict)

For scenarios demanding precision:

## Report Format
 
ALWAYS use this exact structure:
 
### Executive Summary
[2-3 sentences summarizing findings]
 
### Key Findings
1. [Finding with supporting data]
2. [Finding with supporting data]
 
### Recommendations
- [Actionable recommendation]
- [Actionable recommendation]

Template Pattern (Flexible)

When adaptation adds value:

## Analysis Format
 
Use this suggested structure, adjusting as needed:
 
- **Overview**: Context and scope
- **Analysis**: Key observations
- **Insights**: Patterns and implications
- **Next Steps**: Recommended actions
 
Use your best judgment on section depth and detail.

Examples Pattern

For stylistic consistency, include input/output pairs:

## Commit Message Examples
 
**Input**: Added user authentication
**Output**: feat(auth): implement JWT-based user authentication
 
**Input**: Fixed bug in payment processing
**Output**: fix(payments): resolve race condition in checkout flow
 
**Input**: Updated dependencies
**Output**: chore(deps): bump axios to 1.6.0, update lodash

💡 Expert Insight:

Examples help Claude understand desired style and detail more clearly than descriptions alone. When output quality depends on stylistic consistency, invest in good examples.

Real-World Skill Examples

Example 1: API Documentation Skill

---
name: api-documenter
description: Generate and maintain API documentation from code. Use when documenting REST APIs, generating OpenAPI specs, creating SDK documentation, or maintaining API reference guides. Triggers on requests involving API docs, endpoint documentation, or Swagger/OpenAPI.
---
 
# API Documentation Skill
 
Generate comprehensive API documentation from source code and specifications.
 
## Usage
 
For OpenAPI generation:
python scripts/generate_openapi.py --input ./routes --output api-spec.yaml
 
## Documentation Templates
 
### Endpoint Documentation
  ## [METHOD] /path/to/endpoint
 
  **Description**: What this endpoint does
 
  **Authentication**: Required/Optional
 
  **Parameters**:
  | Name | Type | Required | Description |
  |------|------|----------|-------------|
 
  **Response**: { "example": "response" }
 
## Extra Features
- **SDK generation**: See [SDK.md](references/sdk.md)
- **Versioning**: See [VERSIONING.md](references/versioning.md)

Example 2: Database Migration Skill

---
name: db-migrator
description: Create and manage database migrations for PostgreSQL, MySQL, and SQLite. Use when generating migrations, handling schema changes, managing rollbacks, or working with ORMs like Prisma or TypeORM. Triggers on migration requests, schema changes, or database versioning.
---
 
# Database Migration Skill
 
Create safe, reversible database migrations.
 
## Workflow
 
1. Analyze current schema
2. Determine required changes
3. Generate migration files
4. Validate migration safety
5. Provide rollback strategy
 
## Migration Safety Checks
 
Before any destructive operation:
- Verify no data loss
- Check foreign key constraints
- Estimate lock duration
- Prepare rollback script
 
## Framework-Specific Guides
- **Prisma**: See [PRISMA.md](references/prisma.md)
- **TypeORM**: See [TYPEORM.md](references/typeorm.md)
- **Raw SQL**: See [RAW_SQL.md](references/raw_sql.md)

Example 3: Code Review Skill

---
name: code-reviewer
description: Perform comprehensive code reviews focusing on security, performance, and maintainability. Use when reviewing pull requests, auditing code quality, checking for vulnerabilities, or ensuring best practices. Triggers on review requests, PR analysis, or security audits.
---
 
# Code Review Skill
 
Systematic code review with security, performance, and quality focus.
 
## Review Checklist
 
### Security (Critical)
- [ ] SQL injection vulnerabilities
- [ ] XSS attack vectors
- [ ] Hardcoded secrets/credentials
- [ ] Authentication bypass risks
- [ ] Input validation gaps
 
### Performance
- [ ] N+1 query patterns
- [ ] Memory leak potential
- [ ] Inefficient algorithms
- [ ] Missing indexes
 
### Quality
- [ ] DRY violations
- [ ] Dead code
- [ ] Complex functions (>50 lines)
- [ ] Missing error handling
 
## Output Format
 

[SEVERITY] Issue title Location: file:line Problem: What's wrong Impact: Why it matters Fix: How to resolve

## Language-Specific Guides
- **JavaScript/TypeScript**: See [JS.md](references/js.md)
- **Python**: See [PYTHON.md](references/python.md)
- **Go**: See [GO.md](references/go.md)

Storing and Sharing Skills

Personal Skills

Available across all your projects:

~/.claude/skills/skill-name/SKILL.md

Project Skills

Shared with team via git:

.claude/skills/skill-name/SKILL.md

Installing from Marketplace

Register the Anthropic skills repository as a plugin:

/plugin marketplace add anthropics/skills

Then browse and install specific skill sets:

/plugin install document-skills@anthropic-agent-skills

Once installed, skills activate automatically when you mention relevant tasks.

Production Considerations

Validation Checklist

Before deploying a skill:

• YAML frontmatter is valid
• Description includes what AND when
• All scripts tested and working
• References properly linked from SKILL.md
• No duplicate information between SKILL.md and references
• Total SKILL.md under 500 lines
• No extraneous documentation files

Security Best Practices

⚠️ Warning: Always audit skills before using them, especially from external sources. Check for unexpected network calls, file modifications, or data exfiltration patterns.

Environment Variables:

• Never hardcode API keys or secrets in skills
• Reference environment variables: $API_KEY
• Document required variables in SKILL.md

Tool Restrictions:

• Use allowed-tools in frontmatter when appropriate
• Restrict to read-only tools for sensitive operations

Performance Optimization

Token Efficiency:

• Minimize SKILL.md size
• Use references for detailed content
• Provide examples instead of explanations

Loading Optimization:

• Structure references by domain
• Include table of contents in large files
• Use clear file naming for quick discovery

Frequently Asked Questions

What is a Claude Code Skill?

A skill is a modular package containing instructions, scripts, and resources that Claude can discover and load dynamically. It transforms Claude from a general-purpose assistant into a specialized agent for specific tasks.

How does Claude discover my skill?

Claude reads skill metadata (name and description) at startup. When a request matches the description, Claude loads the full SKILL.md and follows its instructions. This is called "progressive disclosure."

Where should I store my skills?

Personal skills go in ~/.claude/skills/ for cross-project use. Project skills go in .claude/skills/ to share with team members via git.

What's the difference between skills and slash commands?

Slash commands are user-invoked (/command) and execute immediately. Skills are model-invoked—Claude automatically discovers and uses them based on context. Skills are better for complex, multi-step capabilities.

How do I restrict what tools a skill can use?

Add allowed-tools to your YAML frontmatter. For example: allowed-tools: Bash, Read, Grep prevents file modifications while allowing read operations.

What should I put in the description field?

Include both WHAT the skill does and WHEN to use it. Add trigger contexts, file types, task types, and keywords users might mention. This is the primary mechanism for skill discovery.

How long should SKILL.md be?

Keep it under 500 lines. If approaching this limit, split content into reference files. Link to them clearly from SKILL.md so Claude knows they exist.

Can skills include executable code?

Yes. Put scripts in the scripts/ directory. These can be Python, Bash, or any executable. Scripts provide deterministic reliability and can execute without loading into context.

How do I debug a skill that isn't working?

Check that YAML frontmatter is valid, description includes relevant trigger words, and the file is in the correct location. Ask Claude "What skills are available?" to verify discovery.

Can I share skills with my team?

Yes. Store skills in .claude/skills/ within your project and commit to git. Team members who clone the repository automatically have access.

Related Resources

• Anthropic Skills Repository - Official skills collection and examples
• Anthropic Agent Skills Blog - Deep dive into skill architecture
• Claude Code Documentation - Official Claude Code docs
• Web Search Agent Skills Guide - Build web search skills with WebSearchAPI.ai
• WebSearchAPI.ai Documentation - API reference for web search integration

Conclusion: Building Your Skill Library

Claude Code Skills represent a fundamental shift in how we work with AI assistants. Instead of starting from scratch every conversation, you can package your expertise into reusable modules that compound in value over time.

Key Takeaways

For Individual Developers:

• Start with skills that automate your most repetitive tasks
• Keep SKILL.md lean—under 500 lines
• Use progressive disclosure to manage complexity
• Test scripts thoroughly before packaging

For Teams:

• Store shared skills in .claude/skills/ for git distribution
• Document skills thoroughly for team adoption
• Use allowed-tools for security-sensitive operations
• Treat skills as reusable team assets

For Production:

• Validate all skills before deployment
• Audit third-party skills for security
• Monitor skill usage patterns
• Iterate based on real-world performance

⭐ Key Takeaway: The best skills are invisible—they activate when needed and deliver exactly what's required without fanfare. Start with one skill that solves your biggest pain point, iterate based on usage, and build your library over time. The compound effect of well-crafted skills transforms your entire workflow.

Last updated: December 2025