Claude Skills: The New AI Agent Capabilities

Introduction

Claude Skills are modular capabilities that extend Claude's functionality with specialized instructions, metadata, and optional resources (scripts, templates) that Claude uses automatically when relevant. Skills transform general-purpose agents into specialists by providing domain-specific expertise, workflows, and best practices that eliminate the need to repeatedly provide the same guidance across multiple conversations.

Key Benefits:

• Specialize Claude: Tailor capabilities for domain-specific tasks
• Reduce repetition: Create once, use automatically across conversations
• Compose capabilities: Combine Skills to build complex workflows
• Progressive disclosure: Only loads what's needed, when needed

Real Results from Implementation:

• Novo Nordisk: Clinical documentation time reduced from 10 weeks to 10 minutes, effectively halving review cycles
• Norges Bank: Saved 213,000 hours with 20% productivity gain across 9,000 portfolio companies
• SK Telecom: Enhanced customer service quality by 34% through Claude deployment
• Enterprise Teams: Significant reduction in prompt engineering overhead through specialized Skills

What You'll Learn:

• What Claude Skills are and how they work with progressive disclosure
• How to use pre-built Skills and create custom ones
• The three levels of Skill content loading (metadata, instructions, resources)
• Step-by-step technical implementation guide
• Best practices for Skill development and deployment

Pro-Tip: Claude Skills implement context engineering principles through progressive disclosure. For building complex agent workflows, see our AI agent orchestration guide and Model Context Protocol guide for standardized tool integration.

1. What Are Claude Skills? The Fundamentals

1.1 The Core Concept

Claude Skills are modular capabilities that extend Claude's functionality. Each Skill packages instructions, metadata, and optional resources (scripts, templates) that Claude uses automatically when relevant. Skills are reusable, filesystem-based resources that provide Claude with domain-specific expertise: workflows, context, and best practices.

Key Characteristics:

• Filesystem-based: Skills exist as directories on a virtual machine with filesystem access
• Progressive disclosure: Claude loads information in stages as needed, not all at once
• Automatic discovery: Claude scans available Skills and loads only what's needed
• Composable: Multiple Skills work together seamlessly
• Portable: Same Skill works across Claude.ai, Claude Code, and API

Pre-built Agent Skills from Anthropic:

• PowerPoint (pptx): Create presentations, edit slides, analyze presentation content
• Excel (xlsx): Create spreadsheets, analyze data, generate reports with charts
• Word (docx): Create documents, edit content, format text
• PDF (pdf): Generate formatted PDF documents and reports

Custom Skills:

• You or your organization create these for specialized workflows and domain-specific tasks.
• Examples: Apply brand style guidelines, generate communications, structure meeting notes, create tasks in company tools, execute company-specific data analysis, automate personal workflows.

1.2 How Skills Work: Three Levels of Content Loading

Figure 1: The Agent + Skills + Computer Architecture. This diagram illustrates how an AI agent is configured with skills and interacts with a virtual machine's file system to execute specialized tasks.

Skills leverage Claude's VM environment with filesystem access, enabling progressive disclosure. Claude loads information in stages as needed, rather than consuming context upfront.

Level 1: Metadata (Always Loaded)

• Content: YAML frontmatter with name and description
• When: Always at startup (~100 tokens per Skill)
• Purpose: Discovery information for Claude to know when to use each Skill

Level 2: Instructions (Loaded When Triggered)

• Content: Main body of SKILL.md with procedural knowledge
• When: When Skill is triggered (under 5k tokens)
• Purpose: Workflows, best practices, and guidance

Level 3: Resources and Code (Loaded As Needed)

• Content: Additional files, scripts, templates, examples
• When: As needed (effectively unlimited)
• Purpose: Executable scripts, reference materials, bundled content

Progressive disclosure ensures only relevant content occupies the context window at any given time. This is a core principle of context engineering that optimizes token usage and improves performance.

Example: PDF Processing Skill Loading

1. Startup: System prompt includes: "PDF Processing - Extract text and tables from PDF files, fill forms, merge documents"
2. User request: "Extract the text from this PDF and summarize it"
3. Claude invokes: bash: read pdf-skill/SKILL.md → Instructions loaded into context
4. Claude determines: Form filling not needed, so FORMS.md is not read
5. Claude executes: Uses instructions from SKILL.md to complete the task

1.3 Where Skills Work

Skills are available across Claude's agent products:

Claude API:

• Supports both pre-built Agent Skills and custom Skills
• Requires three beta headers: code-execution-2025-08-25, skills-2025-10-02, files-api-2025-04-14
• Use pre-built Skills by referencing their skill_id (e.g., pptx, xlsx)
• Create and upload custom Skills via /v1/skills endpoints
• Custom Skills are shared organization-wide

Claude Code:

• Supports only Custom Skills
• Skills are filesystem-based and don't require API uploads
• Create Skills as directories with SKILL.md files
• Claude discovers and uses them automatically

Claude.ai:

• Supports both pre-built Agent Skills and custom Skills
• Pre-built Skills work behind the scenes automatically
• Custom Skills: Upload as zip files through Settings > Features
• Available on Pro, Max, Team, and Enterprise plans with code execution enabled
• Custom Skills are individual to each user (not shared organization-wide)

2. The Business Case: Why Skills Matter

2.1 Cost Efficiency of Executable Code

💰 Cost Impact: Skills can reduce operational costs by 100-1000x for deterministic operations through executable code instead of token generation.

The Token Generation Problem:

• Sorting 10,000 items: Token generation costs $2.50, takes 30 seconds
• Code execution: Costs $0.001, takes 0.1 seconds
• Cost difference: 2,500x more expensive using tokens

Real-World Cost Analysis:

When to Use Executable Code:

• Deterministic operations: Sorting, calculations, data validation
• Repetitive tasks: Form processing, file conversions
• API integrations: Database queries, external service calls
• Consistency requirements: Brand compliance, formatting standards

2.2 ROI for Businesses

Enterprise Success Stories:

• Novo Nordisk: Clinical documentation reduced from 10 weeks to 10 minutes, halving review cycles
• Norges Bank: Saved 213,000 hours with 20% productivity gain across 9,000 portfolio companies
• SK Telecom: Enhanced customer service quality by 34% through Claude deployment
• ROI: Significant return on Skills implementation across multiple industries

Investment Analysis:

Monthly Value Delivery:

• Time Savings: $5,000-15,000 (automated workflows)
• Cost Reduction: $2,000-8,000 (executable code efficiency)
• Quality Improvement: $3,000-10,000 (consistent outputs)
• Total Monthly Value: $10,000-33,000

2.3 Skills Marketplace Opportunity

Market Size Analysis:

• Target Users: Pro, Max, Team, Enterprise subscribers
• Anthropic Valuation: $60 billion, reflecting strong enterprise AI demand
• Revenue Growth: Anthropic's annualized revenue reached $875 million, primarily from business clients
• Skills Revenue Potential: $50-500/month per Skill
• Creator Revenue: 50-500 customers per Skill = $2,500-250,000 monthly

High-Value Skill Categories:

3. How to Use Skills (For Users)

3.1 Getting Started with Skills

Skills are available as a feature preview for users on Pro, Max, Team, and Enterprise plans, requiring code execution to be enabled. They are also available in beta for Claude Code users and for all API users using the code execution tool.

To Get Started:

• For Pre-built Agent Skills: These are already working behind the scenes on Claude.ai and via the Claude API. Claude uses them automatically without requiring any setup.
• For Custom Skills on Claude.ai: Upload your own Skills as zip files through Settings > Features. Available on Pro, Max, Team, and Enterprise plans with code execution enabled.
• For Custom Skills in Claude Code: Create Skills as directories with SKILL.md files. Claude discovers and uses them automatically. These are filesystem-based and do not require API uploads.
• For Custom Skills via Claude API: Specify the relevant skill_id in the container parameter along with the code execution tool. Custom Skills are shared organization-wide.

Prerequisites for API Users: Using Skills via the API requires three beta headers:

• code-execution-2025-08-25 - Skills run in the code execution container
• skills-2025-10-02 - Enables Skills functionality
• files-api-2025-04-14 - Required for uploading/downloading files to/from the container

3.2 Real-World Use Cases

Skills provide specialized capabilities for tasks like document creation, data analysis, and domain-specific work that requires supplementing Claude's general knowledge. They help capture your company's workflows, best practices, and institutional knowledge for Claude to use consistently across your team.

Potential Custom Skill Workflows:

• Apply brand style guidelines to documents and presentations.
• Generate communications following company email templates.
• Structure meeting notes with company-specific formats.
• Create tasks in company tools (JIRA, Asana, Linear) following team conventions.
• Execute company-specific data analysis workflows.
• Automate personal workflows and customize Claude to match your work style.

3.3 Comparing Skills to other Claude Capabilities

Skills vs. Projects:

• Projects provide static background knowledge always loaded when you start chats within them.
• Skills provide specialized procedures that activate dynamically when needed and work everywhere across Claude.

Skills vs. MCP (Model Context Protocol):

• MCP connects Claude to external services and data sources.
• Skills provide procedural knowledge - instructions for how to complete specific tasks or workflows.
• You can use both together: MCP connections give Claude access to tools, while Skills teach Claude how to use those tools effectively.

Skills vs. Custom Instructions:

• Custom Instructions apply broadly to all your conversations.
• Skills are task-specific and only load when relevant, making them better for specialized workflows.

3.4 Example Workflows

Financial Report Workflow:

1. User: "Create a quarterly financial report with charts"
2. Claude loads: Excel Skill + Brand Guidelines Skill + Data Visualization Skill
3. Result: Professional report with embedded charts following company standards

Presentation Workflow:

1. User: "Draft a presentation following our brand guidelines"
2. Claude loads: PowerPoint Skill + Brand Guidelines Skill + Content Skill
3. Result: Branded presentation with consistent formatting and messaging

Data Processing Workflow:

1. User: "Process these forms and extract data"
2. Claude loads: PDF Processing Skill + Data Validation Skill + Export Skill
3. Result: Clean, validated data exported in required format

4. How to Create Skills (For Developers/Creators)

4.1 Quick Start Guide

💡 Pro Tip: Skills use progressive disclosure - only load what's needed, when needed. This keeps context costs low while providing comprehensive capabilities.

5-Minute Setup:

1. Create directory with SKILL.md file
2. Add YAML frontmatter (name + description)
3. Write clear instructions for Claude to follow
4. Test with Claude to ensure proper triggering

4.2 Skill Structure and Requirements

Every Skill requires a SKILL.md file with YAML frontmatter:

---
name: Your Skill Name
description: Brief description of what this Skill does and when to use it
---

# Your Skill Name

## Instructions
[Clear, step-by-step guidance for Claude to follow]

## Examples
[Concrete examples of using this Skill]

Required Fields:

• name: 64 characters maximum
• description: 1024 characters maximum (should include both what the Skill does and when Claude should use it)

Optional Components:

• Scripts: Executable code (Python, JavaScript, etc.) for deterministic operations
• Resources: Reference files, templates, examples, documentation
• Additional markdown files: FORMS.md, REFERENCE.md for specialized guidance

Skill Directory Structure:

Figure 2: The recommended folder structure for a Claude Skill, illustrating the placement of instructions, resources, and executable code.

my-skill/
├── SKILL.md (main instructions)
├── FORMS.md (form-filling guide)
├── REFERENCE.md (detailed API reference)
└── scripts/
    └── process_data.py (utility script)

4.3 Three Skill Types with Examples

Choose Your Type:

Type 1: Instruction-Only Skills

---
name: "Writing Style Guide"
description: "Apply consistent writing style and tone to all content"
---

# Writing Style Guide

## Voice and Tone
- Professional but approachable
- Clear and concise
- Action-oriented language

## Style Guidelines
- Use active voice
- Short sentences (15-20 words)
- Bullet points for lists
- Bold for emphasis

Type 2: Hybrid Skills (Instructions + Resources)

---
name: "Legal Document Generator"
description: "Generate legal documents following company templates and requirements"
---

# Legal Document Generator

## Templates Available
- Contract templates (employment, vendor, client)
- Legal notices and disclaimers
- Compliance documentation

## Requirements
- All documents must include required clauses
- Follow company legal standards
- Include proper disclaimers

Type 3: Executable Skills (Code + Instructions)

# data_processor.py
import pandas as pd
import numpy as np

def process_financial_data(file_path):
    """Process financial data and generate reports"""
    df = pd.read_csv(file_path)
    
    # Clean data
    df = df.dropna()
    df['amount'] = pd.to_numeric(df['amount'])
    
    # Generate summary
    summary = {
        'total_revenue': df['amount'].sum(),
        'average_transaction': df['amount'].mean(),
        'transaction_count': len(df)
    }
    
    return summary

💡 When to Use: Deterministic operations like data processing, calculations, file conversions Cost Savings: Executable code can be orders of magnitude cheaper than token generation for deterministic operations

Note: Code examples in this article use Python for clarity. The concepts apply to any language. For implementation guidance in TypeScript/JavaScript, refer to our Production-Ready AI Agent Architecture guide.

4.4 Using skill-creator

🚀 Quick Start: Use the built-in skill-creator to generate your first Skill in minutes, not hours.

Interactive Skill Creation Process:

1. Enable skill-creator: Available in Claude's built-in Skills
2. Describe your workflow: Claude asks about your specific needs
3. Generate structure: Creates folder structure and SKILL.md
4. Bundle resources: Automatically includes necessary files
5. Test and iterate: Refine based on real-world usage

Example skill-creator Session:

Claude: "What workflow would you like to automate with a Skill?"

User: "I need to generate financial reports that follow our company's branding and include specific charts and calculations."

Claude: "I'll create a Financial Report Skill for you. Let me ask a few questions:
1. What's your company's primary brand color?
2. What types of charts do you typically include?
3. What financial calculations are most important?"

Benefits of skill-creator:

• No manual file editing required
• Automatic folder structure generation
• Resource bundling for complex workflows
• Best practices built-in

4.5 Testing, Quality Assurance, and Iteration

Testing Checklist:

• Description triggers correctly with relevant prompts
• Tested with Haiku, Sonnet, and Opus models
• Real usage scenarios work as expected
• Team feedback incorporated (if applicable)

Quality Standards:

• SKILL.md under 500 lines for optimal performance
• No time-sensitive information (or in "old patterns" section)
• Consistent terminology throughout
• Concrete examples, not abstract

Common Issues and Solutions:

• Skill not triggering: Improve description clarity and specificity
• Wrong context: Add more specific use cases to description
• Performance issues: Optimize code and reduce resource usage
• Integration problems: Check dependencies and API connections

Advanced Testing:

• Observe how Claude navigates Skills during execution
• Create at least three evaluations for different scenarios
• Test with real usage patterns from your workflow
• Gather feedback from team members who will use the Skill

4.6 Security and Best Practices

⚠️ Security Warning: Skills provide Claude with new capabilities through instructions and code. Only use Skills from trusted sources.

Security Guidelines:

• Use only trusted sources (those you created yourself or obtained from Anthropic)
• Audit thoroughly: Review all files bundled in the Skill: SKILL.md, scripts, images, and other resources
• Look for unusual patterns: Unexpected network calls, file access patterns, or operations that don't match the Skill's stated purpose
• External sources are risky: Skills that fetch data from external URLs pose particular risk
• Tool misuse: Malicious Skills can invoke tools (file operations, bash commands, code execution) in harmful ways
• Data exposure: Skills with access to sensitive data could be designed to leak information to external systems

Authoring Best Practices:

Concise is Key:

• Skills share context with system prompts and conversation history
• Challenge every piece of information: "Does Claude really need this?"
• Default assumption: Claude is already smart - only add context it doesn't have

Appropriate Degrees of Freedom:

• High freedom (text instructions): Multiple valid approaches, context-dependent decisions
• Medium freedom (pseudocode): Preferred patterns with some variation
• Low freedom (specific scripts): Fragile operations requiring exact sequences

Model Testing:

• Test with all models you plan to use (Haiku, Sonnet, Opus)
• What works for Opus might need more detail for Haiku
• Aim for instructions that work well across all models

Naming Conventions:

• Use gerund form (verb + -ing): "Processing PDFs", "Analyzing spreadsheets"
• Be descriptive and consistent
• Examples: "Managing databases", "Testing code", "Writing documentation"

4.7 Distribution and Advanced Implementation

Distribution Channels:

Cross-Surface Availability:

• Custom Skills do not sync across surfaces
• Skills uploaded to Claude.ai must be separately uploaded to the API
• Skills uploaded via the API are not available on Claude.ai
• Claude Code Skills are filesystem-based and separate from both Claude.ai and API

Advanced Implementation Techniques:

Skills with Executable Code:

• Solve, don't punt: Provide utility scripts instead of asking Claude to generate code
• Visual analysis: Use image analysis for complex layouts and structures
• Verifiable outputs: Create intermediate files that can be validated before execution
• Package dependencies: List required packages and verify availability

MCP Tool References:

• Use fully qualified tool names: ServerName:tool_name
• Avoid "tool not found" errors
• Example: BigQuery:bigquery_schema instead of just bigquery_schema

Runtime Environment Constraints:

• No network access: Skills cannot make external API calls or access the internet
• No runtime package installation: Only pre-installed packages are available
• Pre-configured dependencies only: Check the code execution tool documentation for available packages

5. Strategic Context and Implementation Roadmap

5.1 Why "Skills" vs "Sub-Agents"

The Sub-Agent Problem:

• Coordination overhead: Multiple agents need to communicate and coordinate
• Token costs: Each agent interaction requires token consumption
• Complexity: Managing agent relationships and dependencies
• Reliability: Agent coordination can fail or create conflicts

The Skills Solution:

• Single intelligent agent: One Claude that uses specialized tools
• Automatic coordination: Skills work together seamlessly
• Cost efficiency: Executable code vs agent communication
• Simplicity: Upload Skills, let Claude handle the rest

Strategic Insight: Skills represent Anthropic's evolution from the "teams of sub-agents" concept (marketed in Claude Code) to the more practical "agent + tools" paradigm. This reflects learning from real-world usage where coordination complexity outweighed benefits.

5.2 Skills vs Model Context Protocol (MCP)

Complementary Technologies:

• MCP: Communication protocol for AI-tool interactions
• Skills: Portable packages with instructions, code, and resources
• Together: MCP enables communication, Skills provide the capabilities

When to Use Each:

• MCP: When you need real-time tool integration
• Skills: When you want portable, reusable capability packages
• Both: For comprehensive AI agent systems

5.3 Early Adopter Success Stories

Enterprise AI Adoption:

• Anthropic Growth: Enterprise customer base expanded from under 1,000 to over 300,000 in two years
• Global Expansion: Anthropic tripling international workforce and opening new offices
• Market Share: Strong performance in coding and business use cases driving international expansion
• Revenue Growth: $875 million annualized revenue primarily from business clients

5.4 30-Day Quick Start Plan

Week 1: Foundation Setup

• Days 1-2: Enable Skills in Settings, explore built-in Anthropic Skills
• Days 3-4: Test Skills with your common workflows
• Days 5-7: Identify 2-3 high-value use cases for custom Skills
• Goal: Understand Skills capabilities and identify opportunities

Week 2: Use Case Development

• Days 8-10: Map current workflows that could benefit from Skills
• Days 11-12: Research existing Skills in anthropics/skills repository
• Days 13-14: Plan your first custom Skill development
• Goal: Clear roadmap for Skills implementation

Week 3: Custom Skill Creation

• Days 15-17: Use skill-creator to build your first custom Skill
• Days 18-19: Test and refine the Skill with real workflows
• Days 20-21: Gather feedback and iterate on Skill performance
• Goal: Working custom Skill that improves your workflows

Week 4: Deployment and Optimization

• Days 22-24: Deploy Skills to your team or organization
• Days 25-26: Monitor usage and measure performance improvements
• Days 27-28: Plan additional Skills and long-term strategy
• Goal: Measurable ROI from Skills implementation

5.5 Building a Skills Business

Market Opportunity:

• Growing user base: Pro, Max, Team, Enterprise subscribers
• Increasing demand: Specialized workflows and automation needs
• Revenue potential: $50-500/month per Skill
• Scalability: Build once, sell to multiple customers

Pricing Strategies:

• Per-user pricing: $50-200/month per user
• Per-organization: $500-2,000/month per organization
• One-time purchase: $1,000-5,000 for enterprise Skills
• Freemium model: Basic free, premium features paid

High-Value Skill Categories:

• Industry-specific: Legal, finance, healthcare, manufacturing
• Compliance: Regulatory requirements, audit trails, documentation
• Enterprise workflows: HR, finance, operations, customer service
• Developer tools: Code generation, testing, deployment, documentation

Distribution Channels:

• GitHub marketplace: Open source Skills with premium support
• Direct sales: Enterprise customers and large organizations
• Partner channels: Integration with existing software platforms
• Future Anthropic marketplace: Official Skills marketplace (coming)

Conclusion

Claude Skills represent the evolution from generic AI to specialized expertise, delivering up to 90% faster task completion and creating significant marketplace opportunities. The most successful implementations focus on executable code for deterministic operations, automatic skill invocation, and seamless workflow integration.

Key Success Factors:

• Start with high-value use cases: Focus on workflows that save significant time
• Leverage executable code: Use Skills for deterministic operations where code beats tokens
• Measure everything: Track time savings, cost reductions, and quality improvements
• Build for scale: Create Skills that work across your entire organization

The Business Impact:

• Immediate ROI: 2-4 month payback period through time savings
• Long-term value: Up to 90% faster specialized tasks with consistent quality
• Market opportunity: $50-500/month per Skill in growing marketplace
• Competitive advantage: Specialized AI capabilities that competitors lack

The Skills revolution is here. Companies that implement Claude Skills today will have a significant competitive advantage over competitors still using generic AI approaches.

Further Reading

• 25+ Disruptive AI Agent Business Ideas You Should Launch in 2025 & Beyond
• Production-Ready AI Agent Architecture: Building Scalable Systems
• Model Context Protocol (MCP): A Simple Guide to the 'USB-C' of AI Apps
• Context Engineering vs Prompt Engineering: The 2025 Guide
• What are Skills?
• Using Skills in Claude
• How to create custom Skills
• Introducing Agent Skills
• The Key Components of a Production-Ready AI Agent Architecture
• 10 Best Practices for Reliable AI Agent Systems
• Research AI Agent in Action: Autonomous Agent with Tool Calling
• Google Gemini CLI vs Claude CLI: Exploring the Latest AI Developer Tools