Claude Skills

Claude Skills (also referred to as Agent Skills) are modular capabilities developed by Anthropic for the Claude platform that package repeatable workflows, instructions, reference materials, and optional executable scripts into discoverable components that Claude can automatically load when relevant to a task. Introduced on October 16, 2025, Skills transform Claude from a general-purpose AI assistant into a specialized agent for specific workflows while maintaining efficiency through progressive disclosure of context.

Skills work across Claude apps, Claude Code, and the Claude Developer Platform (API), enabling users to create consistent, specialized behaviors without prompt overhead. Anthropic also publishes a public repository of example skills and the engineering design pattern underpinning the Skills system.

Overview

A Skill is a directory-based package that contains:

• A required SKILL.md file with YAML frontmatter (name and description) and Markdown instructions
• Optional supporting reference files (templates, brand assets, additional documentation)
• Optional executable scripts that Claude can run when code is more reliable or efficient than pure text generation

Claude uses a progressive disclosure mechanism to manage Skills efficiently: it preloads only lightweight metadata (name and description) for all installed skills at session start; when a user request suggests a skill is relevant, Claude reads the full SKILL.md and any linked files; if appropriate, it may execute bundled scripts within its code execution environment.

Architecture and Design

Progressive Disclosure

The core design principle behind Claude Skills is progressive disclosure, which operates on three levels:

Level	Content	Token Usage	When Loaded
1. Metadata	Name and description from YAML frontmatter	~30-50 tokens per skill	At session start
2. Core Instructions	Full SKILL.md file content	Variable (hundreds to thousands)	When skill is triggered
3. Additional Resources	Referenced files, scripts, templates	As needed	Only when specifically required

This architecture ensures that Claude's context window remains efficient, as skills that aren't relevant to the current task don't consume tokens beyond their minimal metadata.

File Structure

A minimal SKILL.md uses YAML frontmatter and Markdown content:

---
name: pdf-processing
description: Extract text, fill forms, and merge PDFs. Use when working with PDF files or forms.
version: 1.0.0
---
# PDF Processing

## Instructions
[Detailed instructions for the skill]

## Examples
[Usage examples]

Key Characteristics

Characteristic	Description
Composable	Multiple skills can stack and work together seamlessly; Claude autonomously identifies and coordinates the set of relevant skills.
Portable	The same skill format works across Claude apps, Claude Code, and the API—"build once, use everywhere."
Efficient	Progressive disclosure keeps context use minimal until needed; reduces prompt bloat and token consumption.
Powerful	Skills may include executable code for deterministic operations (for example PDF form extraction) inside Claude's sandboxed container.
Secure	Skills operate in isolated environments with no data persistence between sessions.

Availability and Access

Skills were announced publicly on October 16, 2025. Availability varies by platform:

Platform	Availability	Requirements
Claude.ai apps	Pro, Max, Team, Enterprise plans	Code execution and file creation enabled
Claude Code	All users with Claude Code access	Installed via plugins or filesystem
Claude API	All API users	Code Execution Tool beta enabled
Claude Agent SDK	All SDK users	Standard SDK requirements

For Team and Enterprise users, administrators must first enable Skills organization-wide before individual members can use them.

Built-in Skills

Anthropic provides built-in document Skills that Claude can invoke automatically when appropriate:

Document Processing Skills

skill_id	Capability	Description
docx	Word documents	Creates, edits, and analyzes Microsoft Word documents with support for tracked changes, comments, and formatting preservation
xlsx	Excel spreadsheets	Generates Microsoft Excel spreadsheets with formulas, data analysis, and visualization capabilities
pptx	PowerPoint presentations	Creates Microsoft PowerPoint presentations with layouts, templates, and automated slide generation
pdf	PDF manipulation	Comprehensive PDF handling including form filling, text extraction, merging, and splitting

Example Skills Repository

Anthropic's GitHub repository includes diverse example Skills:

Category	Skill Name	Description
Creative & Design	algorithmic-art	Generates art using p5.js with seeded randomness and particle systems
	canvas-design	Creates visual art in PNG and PDF formats using design philosophies
	slack-gif-creator	Produces animated GIFs optimized for Slack's size constraints
Development & Technical	artifacts-builder	Builds HTML artifacts using React and Tailwind CSS
	mcp-server	Guides creation of MCP servers for API integration
	webapp-testing	Tests web applications using Playwright
Enterprise & Communication	brand-guidelines	Applies brand colors, typography, and organizational standards
	internal-comms	Writes internal communications like reports and newsletters
	theme-factory	Styles artifacts with professional themes
Meta Skills	skill-creator	Interactive guidance for creating new Skills
	template-skill	Basic template for starting new Skills

Technical Implementation

Code Execution Environment

Skills operate within Claude's sandboxed code execution environment, which provides:

• Filesystem access for reading skill content
• Ability to execute scripts and commands
• Network isolation with configurable access controls
• No data persistence between sessions
• Pre-installed libraries and packages

The Code Execution Tool beta must be enabled for Skills to function.

API Integration

The API supports both Anthropic-managed and custom Skills through:

Requirement	Details
Beta headers	code-execution-2025-08-25, skills-2025-10-02, files-api-2025-04-14
Endpoints	/v1/skills for management; Messages API for execution
Skill specification	List in container.skills with type, skill_id, and optional version
File outputs	Generated files include file_id for download via Files API
Per-request limit	Maximum 8 Skills per request
Upload size limit	Under 8 MB for custom skills

Example API usage:

{
  "container": {
    "skills": [
      {"type": "anthropic", "skill_id": "xlsx", "version": "1.0.0"},
      {"type": "custom", "skill_id": "brand-guidelines", "version": "latest"}
    ]
  }
}

Claude Code Integration

In Claude Code, Skills are discovered from:

• **Personal Skills**: ~/.claude/skills/
• **Project Skills**: .claude/skills/ (in the repository)
• **Plugin-bundled Skills**: via Claude Code plugins/marketplaces

Creating Custom Skills

There are two primary paths for creating custom Skills:

Manual Creation

1. Create a folder with the skill name (lowercase, hyphens, max 64 characters) 2. Add SKILL.md with YAML frontmatter and Markdown instructions 3. Include optional scripts, templates, or reference files 4. Upload as ZIP file (Claude apps) or place in appropriate directory (Claude Code/API)

Conversational Creation

1. Enable the built-in skill-creator Skill in Settings 2. Describe the desired workflow to Claude 3. Claude generates properly structured Skill folder 4. Test and iterate on the generated skill

Enterprise Adoption

Several major organizations have implemented Claude Skills for production workflows:

Rakuten

Rakuten, the Japanese e-commerce giant, uses Skills to transform finance operations. According to Yusuke Kaji, General Manager of AI at Rakuten: "Skills streamline our management accounting and finance workflows. Claude processes multiple spreadsheets, catches critical anomalies, and generates reports using our procedures. What once took a day, we can now accomplish in an hour."

Box

Box leverages Skills to make corporate content repositories more actionable. Yashodha Bhavnani, Head of AI at Box, stated: "Skills teaches Claude how to work with Box content. Users can transform stored files into PowerPoint presentations, Excel spreadsheets, and Word documents that follow their organization's standards—saving hours of effort."

Notion

Notion integrated Skills to provide more predictable results and reduce prompt complexity. The company reports that Skills enable Claude to work seamlessly with Notion, taking users "from questions to action faster" with "less prompt wrangling on complex tasks."

Canva

Canva uses Skills to streamline design workflows and maintain brand consistency across generated content.

Security and Privacy

Sandboxing Architecture

Claude Skills operate within a comprehensive sandboxing system that provides:

• Filesystem isolation: Restricted access to specified directories only
• Network isolation: Controlled access through proxy servers with domain allowlists
• Process isolation: Prevention of system-level modifications
• No persistence: Data doesn't persist between sessions

Security Best Practices

Organizations implementing Skills should follow these guidelines:

• Only install Skills from trusted sources
• Audit skill contents before deployment
• Review code dependencies and bundled resources
• Implement least-privilege access controls
• Monitor skill execution logs
• Avoid skills with prompt injection risks or data exfiltration attempts

Custom Skills uploaded in apps are private to the individual account; sharing requires separate uploads or API deployment.

Comparison with Related Technologies

Skills vs. Model Context Protocol (MCP)

While both Claude Skills and the Model Context Protocol aim to extend AI capabilities, they differ significantly:

Aspect	Claude Skills	Model Context Protocol
Architecture	Markdown files with optional scripts	Full protocol specification with servers
Token efficiency	30-50 tokens until loaded	Thousands to tens of thousands
Complexity	Simple folder structure	Requires API design knowledge
Primary function	Teaching HOW to perform tasks	Connecting TO external systems
Portability	Cross-platform by default	Vendor-neutral but complex
Use case	Procedural knowledge and workflows	External service integration

Developer and AI researcher Simon Willison noted that Skills "might be a bigger deal than MCP," citing their simplicity and effectiveness.

Skills vs. Other Claude Features

• Vs. Projects: Projects provide static context bounded to specific chats, while Skills are dynamic and available everywhere.
• Vs. Custom Instructions: Custom instructions apply broadly, whereas Skills are task-specific and load on-demand.
• Vs. Regular Prompting: Skills reduce repetition by packaging complex workflows that would otherwise require extensive prompting.

Best Practices

Development Guidelines

• Write specific, clear descriptions (max 1024 characters) that specify what the Skill does and when to use it
• Focus each skill on a single capability or workflow
• Test skills with various prompts to ensure reliable activation
• Version skills appropriately for updates
• Document examples and edge cases in the SKILL.md file

Troubleshooting

Common issues and solutions:

• Non-activation: Check description clarity and YAML syntax
• Incorrect behavior: Review instructions and examples
• Performance issues: Optimize scripts and reduce file sizes
• Access problems: Verify enablement settings and permissions

Future Development

Anthropic has announced plans for several enhancements:

• Simplified skill creation workflows
• Enterprise-wide deployment capabilities
• Ability for agents to create, edit, and evaluate Skills autonomously
• Integration with external tools and Model Context Protocol servers
• Community marketplace for sharing Skills
• Enhanced versioning and rollback capabilities

Timeline

Date	Milestone	Source
October 16, 2025	Public announcement of Agent Skills; availability across Claude apps, Claude Code, and API
October 2025	Launch of public GitHub repository with example Skills
October 2025	Integration announced with enterprise partners (Box, Notion, Canva, Rakuten)

See Also

• Claude (AI)
• Claude Code
• Claude API
• Model Context Protocol
• Anthropic
• AI agents
• Large language models
• Prompt engineering
• Function calling
• Tool Use (AI)