What Are Claude Skills?

A skill is a folder containing instructions that teach Claude how to handle specific tasks or workflows. Instead of re-explaining your preferences, processes, and domain expertise in every conversation, skills let you teach Claude once and benefit every time.

Skills are powerful when you have repeatable workflows: generating frontend designs from specs, conducting research with consistent methodology, creating documents that follow your team's style guide, or orchestrating multi-step processes. They work well with Claude's built-in capabilities like code execution and document creation.

In Claude, skills are the capabilities and tools that agents can access to accomplish their work. They form part of the agent framework and enable agents to perform specialised operations within their domain.

Skills available to agents include:

File and code manipulation
Terminal execution
Testing and validation
Web fetching and searching
Code analysis and exploration
Debugging and diagnostics

Rather than being invoked directly by the user, skills are automatically selected and used by agents as needed to complete assigned tasks. When you dispatch an agent to accomplish something, it determines which skills are appropriate and uses them autonomously.

Core Design Principles

Progressive Disclosure

Skills use a three-level system to minimise token usage while maintaining specialised expertise:

First level (YAML frontmatter): Always loaded in Claude's system prompt. Provides just enough information for Claude to know when each skill should be used without loading all of it into context.
Second level (SKILL.md body): Loaded when Claude thinks the skill is relevant to the current task. Contains the full instructions and guidance.
Third level (Linked files in references/): Additional files Claude can navigate only as needed. Keeps the main file focused while allowing deep reference material.

This means you can keep SKILL.md concise and move detailed documentation to references/ — Claude will find it when it's needed.

Composability and Portability

Claude can load multiple skills simultaneously. A well-designed skill works alongside others rather than assuming it's the only capability available.

Skills work identically across Claude.ai, Claude Code, and the API. Create a skill once and it works across all surfaces without modification, provided the environment supports any dependencies the skill requires.

Technical Requirements

File Structure

your-skill-name/
├── SKILL.md          # Required — main skill file
├── scripts/          # Optional — executable code (Python, Bash, etc.)
├── references/       # Optional — documentation loaded as needed
└── assets/           # Optional — templates, fonts, icons used in output

Critical rules:

SKILL.md must be exactly SKILL.md (case-sensitive — skill.md and SKILL.MD will not work)
The skill folder must use kebab-case: my-skill-name not My Skill Name or my_skill_name
Do not include a README.md inside the skill folder. All documentation goes in SKILL.md or references/. When distributing via GitHub, add a repo-level README for human visitors, not inside the skill folder.

YAML Frontmatter

The YAML frontmatter is how Claude decides whether to load your skill. It must appear at the top of SKILL.md between --- delimiters.

Minimal required format:

---
name: your-skill-name
description: What it does. Use when user asks to [specific phrases].
---

All available fields:

---
name: skill-name                        # Required: kebab-case, matches folder name
description: What it does and when.    # Required: WHAT + WHEN, under 1024 chars
license: MIT                           # Optional: for open-source skills
allowed-tools: "Bash(python:*) WebFetch"  # Optional: restrict tool access
compatibility: Requires Python 3.10+   # Optional: environment requirements, 1-500 chars
metadata:                              # Optional: custom key-value pairs
  author: Your Name
  version: 1.0.0
  mcp-server: your-service
  category: productivity
  tags: [automation, workflow]
  documentation: https://example.com/docs
  support: [email protected]
---

Security restrictions:

No XML angle brackets (< or >) anywhere in the frontmatter — these appear in Claude's system prompt and could inject instructions
Skills cannot use "claude" or "anthropic" as a name prefix (reserved)
YAML is parsed safely, so code execution in frontmatter is not possible

Writing Effective Descriptions

The description field is the most important part of the frontmatter. It determines whether Claude loads the skill at the right moment.

Formula: [What it does] + [When to use it] + [Key capabilities]

Good examples:

# Specific and actionable with trigger phrases
description: Analyzes Figma design files and generates developer handoff documentation.
  Use when user uploads .fig files, asks for "design specs", "component documentation",
  or "design-to-code handoff".

# Includes concrete trigger words users would say
description: Manages Linear project workflows including sprint planning, task creation,
  and status tracking. Use when user mentions "sprint", "Linear tasks", "project planning",
  or asks to "create tickets".

Bad examples:

# Too vague
description: Helps with projects.

# Missing trigger conditions
description: Creates sophisticated multi-page documentation systems.

# Too technical, no user-facing triggers
description: Implements the Project entity model with hierarchical relationships.

Debugging tip: Ask Claude "When would you use the [skill name] skill?" — Claude will quote the description back. If what it says doesn't match when you want the skill to activate, that's what to fix.

Writing the Main Instructions

After the frontmatter, write the instructions in Markdown. Keep SKILL.md focused on core instructions. Move detailed reference material to references/ and link to it.

Recommended structure:

---
name: your-skill
description: [...]
---

# Your Skill Name

## Instructions

### Step 1: [First Major Step]
Clear explanation of what happens.

### Step 2: [Second Major Step]
...

## Examples

### Example 1: [Common scenario]
User says: "..."
Actions:
1. ...
2. ...
Result: ...

## Troubleshooting

### Error: [Common error message]
Cause: [Why it happens]
Solution: [How to fix]

Best practices for instructions:

Be specific and actionable. "Run python scripts/validate.py --input {filename}" beats "Validate the data before proceeding."
Put critical instructions at the top. Use ## Important or ## Critical headers. Repeat key points if needed.
Reference bundled resources clearly: "Before writing queries, consult references/api-patterns.md for rate limiting guidance."
Include error handling for common failure modes.
For critical validations, consider a script in scripts/ rather than relying on prose instructions. Code is deterministic; language interpretation is not.

Skills and MCP

If you have an MCP server that connects Claude to your service, skills add the knowledge layer on top.

Think of it like a professional kitchen:

MCP provides the kitchen: access to tools, ingredients, and equipment.
Skills provide the recipes: step-by-step instructions on how to create something valuable.

MCP (Connectivity)	Skills (Knowledge)
Connects Claude to your service	Teaches Claude how to use it effectively
Provides real-time data access	Captures workflows and best practices
What Claude can do	How Claude should do it

Without skills, users connect your MCP but don't know what to do next. They ask support questions, prompt Claude differently each time, and get inconsistent results. With skills, pre-built workflows activate automatically when needed.

Three Common Use Case Categories

Category 1: Document and Asset Creation

Creating consistent, high-quality output: documents, presentations, apps, designs, code.

Key techniques: embedded style guides, template structures for consistent output, quality checklists before finalising, no external tools required (uses Claude's built-in capabilities).

Example: A frontend-design skill that generates production-grade interfaces with embedded style guides and brand standards.

Category 2: Workflow Automation

Multi-step processes that benefit from consistent methodology, often coordinating across multiple MCP servers.

Key techniques: step-by-step workflow with validation gates, templates for common structures, built-in review and improvement suggestions, iterative refinement loops.

Example: A sprint planning skill that fetches current project status from Linear, analyses team velocity, suggests task prioritisation, and creates the tasks.

Category 3: MCP Enhancement

Workflow guidance to enhance the tool access an MCP server provides.

Key techniques: coordinates multiple MCP calls in sequence, embeds domain expertise, provides context users would otherwise need to specify, error handling for common MCP failures.

Example: A Sentry code review skill that automatically analyses and fixes detected bugs in GitHub pull requests using Sentry's error monitoring data.

Creating Custom Skills for Your Projects

You can define custom skills in your .claude/skills/ directory to capture reusable guidance, conventions, and frameworks that multiple agents can reference. Unlike agents (which define workflows), skills define reference material: the "what" rather than the "how".

What Skills Should Contain

Reusable guidelines — Anything that applies across multiple contexts or agents

Platform-specific style guides (how to write for X vs LinkedIn vs blogs)
Domain expertise (architectural patterns, security practices, performance guidelines)
Brand frameworks (voice, messaging, positioning principles)
Specialised conventions (naming schemes, coding standards for a specific technology)

Examples and templates — Concrete demonstrations of principles in action

Sample posts showing good hook techniques
Code snippets demonstrating architectural patterns
Real-world examples of the principle in practice

Decision frameworks — Guidance on when to choose one approach over another

When to use one technology vs another
How to evaluate trade-offs
Questions to ask when making decisions

What Skills Should NOT Contain

Workflow or process steps — That belongs in agents. Skills don't define how to do things; agents do.

Tool-specific instructions — How to use a particular tool (git, npm, etc.) goes in CLAUDE.md, not skills.

One-off guidance — If something applies to only one agent, put it in that agent's definition instead.

Example: Content Creation Skills

Paulund uses several interrelated skills for content creation:

Platform style guides (blog-style-guide.md, x-style-guide.md, linkedin-style-guide.md):

Format requirements (word count, character limits, structure)
Tone and voice principles
Examples of strong posts/articles
Specific do's and don'ts for each platform

Specialised expertise (technical-writing-principles.md):

How to explain complex AI and engineering concepts
Writing philosophy: clarity, narrative, actionable insights
Specialisation guidance for tutorials vs opinion pieces
Tone principles for technical authority

Brand frameworks (professional-brand-guidelines.md):

Four brand pillars with descriptions
Content principles (hook, voice, formatting, engagement)
Platform-specific guidance on post types

General reference (content-from-sources.md):

How to turn podcast notes into posts
How to expand a quick thought into a full article
Techniques for mining different content sources

These skills are referenced by agents (tech-article-writer, linkedin-content-drafter, x-content-drafter). Each agent has a focused workflow; the skills provide the standards they apply.

Organising Skills Hierarchically

For larger projects, organise skills in subdirectories:

.claude/skills/
├── social-content/
│   ├── SKILL.md                           # Overview of the entire skill
│   └── references/
│       ├── blog-style-guide.md            # Platform guide
│       ├── technical-writing-principles.md # Specialized expertise
│       ├── professional-brand-guidelines.md # Brand framework
│       └── content-from-sources.md        # General reference
│
├── api-development/
│   ├── SKILL.md
│   └── references/
│       ├── rest-api-patterns.md
│       ├── security-best-practices.md
│       └── performance-guidelines.md

Each subdirectory becomes a skill that agents can reference. The SKILL.md file provides an overview; references/ contains the detailed guidance.

Five Workflow Patterns

These patterns come from skills created by early adopters and internal teams. They represent common approaches that work well, not prescriptive templates.

Pattern 1: Sequential Workflow Orchestration

Use when users need multi-step processes in a specific order.

## Workflow: Onboard New Customer

### Step 1: Create Account
Call MCP tool: `create_customer`
Parameters: name, email, company

### Step 2: Setup Payment
Call MCP tool: `setup_payment_method`
Wait for: payment method verification

### Step 3: Create Subscription
Call MCP tool: `create_subscription`
Parameters: plan_id, customer_id (from Step 1)

### Step 4: Send Welcome Email
Call MCP tool: `send_email`
Template: welcome_email_template

Key techniques: explicit step ordering, dependencies between steps, validation at each stage, rollback instructions for failures.

Pattern 2: Multi-MCP Coordination

Use when workflows span multiple services.

### Phase 1: Design Export (Figma MCP)
1. Export design assets from Figma
2. Generate design specifications

### Phase 2: Asset Storage (Drive MCP)
1. Create project folder in Drive
2. Upload all assets

### Phase 3: Task Creation (Linear MCP)
1. Create development tasks
2. Attach asset links to tasks

### Phase 4: Notification (Slack MCP)
1. Post handoff summary to #engineering

Key techniques: clear phase separation, data passing between MCPs, validation before moving to next phase, centralised error handling.

Pattern 3: Iterative Refinement

Use when output quality improves with iteration.

### Initial Draft
1. Fetch data via MCP
2. Generate first draft
3. Save to temporary file

### Quality Check
1. Run validation script: `scripts/check_report.py`
2. Identify issues (missing sections, formatting errors, data issues)

### Refinement Loop
1. Address each identified issue
2. Regenerate affected sections
3. Re-validate
4. Repeat until quality threshold met

### Finalization
1. Apply final formatting
2. Generate summary
3. Save final version

Key techniques: explicit quality criteria, validation scripts, clear stopping conditions.

Pattern 4: Context-Aware Tool Selection

Use when the same outcome requires different tools depending on context.

## Smart File Storage

### Decision Tree
1. Check file type and size
2. Determine best storage location:
   - Large files (>10MB): Use cloud storage MCP
   - Collaborative docs: Use Notion/Docs MCP
   - Code files: Use GitHub MCP
   - Temporary files: Use local storage

### Execute Storage
Based on decision:
- Call appropriate MCP tool
- Apply service-specific metadata
- Generate access link

### Provide Context to User
Explain why that storage was chosen

Key techniques: clear decision criteria, fallback options, transparency about choices.

Pattern 5: Domain-Specific Intelligence

Use when your skill adds specialised knowledge beyond tool access.

## Payment Processing with Compliance

### Before Processing (Compliance Check)
1. Fetch transaction details via MCP
2. Apply compliance rules:
   - Check sanctions lists
   - Verify jurisdiction allowances
   - Assess risk level
3. Document compliance decision

### Processing
IF compliance passed:
- Call payment processing MCP tool
- Apply appropriate fraud checks
- Process transaction
ELSE:
- Flag for review
- Create compliance case

### Audit Trail
- Log all compliance checks
- Record processing decisions
- Generate audit report

Key techniques: domain expertise embedded in logic, compliance before action, comprehensive documentation.

Testing and Iteration

Skills can be tested at varying levels of rigor depending on your needs. Manual testing in Claude.ai is fast with no setup. Scripted testing in Claude Code allows repeatable validation. Programmatic testing via the skills API suits systematic evaluation suites.

Three Testing Areas

1. Triggering tests

Goal: ensure your skill loads at the right times.

Run 10-20 test queries that should trigger your skill. Track how many times it loads automatically vs. requires explicit invocation. Target: 90% automatic triggering on relevant queries.

Example test suite:

Should trigger:
- "Help me set up a new ProjectHub workspace"
- "I need to create a project in ProjectHub"
- "Initialize a ProjectHub project for Q4 planning"

Should NOT trigger:
- "What's the weather in San Francisco?"
- "Help me write Python code"
- "Create a spreadsheet" (unless your skill handles sheets)

2. Functional tests

Goal: verify the skill produces correct outputs.

Test cases:

Valid outputs generated
API calls succeed
Error handling works
Edge cases covered

Example:

Test: Create project with 5 tasks
Given: Project name "Q4 Planning", 5 task descriptions
When: Skill executes workflow
Then:
- Project created in ProjectHub
- 5 tasks created with correct properties
- All tasks linked to project
- No API errors

3. Performance comparison

Goal: prove the skill improves results vs. baseline.

Compare the same task with and without the skill. Track token consumption, number of tool calls, back-and-forth messages, and failed API calls.

Example:

	Without skill	With skill
Messages	15 back-and-forth	2 clarifying questions
Failed API calls	3	0
Tokens consumed	12,000	6,000

Iteration Signals

Undertriggering (skill doesn't load when it should):

Users manually enabling it
Support questions about when to use it

Solution: add more detail and specific keywords to the description, including technical terms users might say.

Overtriggering (skill loads for irrelevant queries):

Users disabling it
Confusion about purpose

Solution: add negative triggers (Do NOT use for simple data exploration — use data-viz skill instead), be more specific about scope.

Instructions not followed:

Too verbose — move detailed reference to references/
Critical instructions buried — put them at the top with ## Critical headers
Ambiguous language — replace vague phrases with concrete steps
Model "laziness" — add "Take your time to do this thoroughly. Quality is more important than speed. Do not skip validation steps." (Note: this works better in user prompts than in SKILL.md)

Pro tip: Iterate on a single challenging task until Claude succeeds, then extract the winning approach into a skill. This provides faster signal than writing and testing a broad skill from scratch.

Using the skill-creator Skill

The skill-creator skill (available in Claude.ai and Claude Code) can help you build and iterate on skills. If you know your top 2-3 workflows, you can build and test a functional skill in 15-30 minutes.

Generate skills from natural language descriptions
Produce properly formatted SKILL.md with frontmatter
Suggest trigger phrases and structure
Flag common issues (vague descriptions, missing triggers, structural problems)
Identify potential over/under-triggering risks

Usage: "Use the skill-creator skill to help me build a skill for [your use case]"

Distribution and Sharing

For Individual Users

Download the skill folder
Zip the folder
Upload to Claude.ai via Settings > Capabilities > Skills
Or place directly in the Claude Code skills directory

For Organisations

Admins can deploy skills workspace-wide with automatic updates and centralised management (available from December 2025).

Via the API

For programmatic use cases — applications, agents, automated workflows:

/v1/skills endpoint for listing and managing skills
Add skills to Messages API requests via the container.skills parameter
Version control and management through the Claude Console
Works with the Claude Agent SDK

Note: skills in the API require the Code Execution Tool beta.

When to use API vs. Claude.ai:

Use Case	Best Surface
End users interacting with skills directly	Claude.ai / Claude Code
Manual testing and iteration during development	Claude.ai / Claude Code
Individual, ad-hoc workflows	Claude.ai / Claude Code
Applications using skills programmatically	API
Production deployments at scale	API
Automated pipelines and agent systems	API

Skills as an Open Standard

Anthropic has published Agent Skills as an open standard. Like MCP, the intent is that the same skill works whether you're using Claude or other AI platforms. Authors can note platform-specific requirements in the compatibility field.

Hosting and Distribution Recommendations

Host on GitHub with a public repo, clear README (for human visitors, separate from the skill folder), and example usage with screenshots
Add a section to your MCP documentation linking to the skill and explaining why using both together is valuable
Provide a quick-start installation guide

When positioning your skill, focus on outcomes not features:

Good: "The ProjectHub skill enables teams to set up complete project workspaces in seconds — including pages, databases, and templates — instead of spending 30 minutes on manual setup."

Bad: "The ProjectHub skill is a folder containing YAML frontmatter and Markdown instructions that calls our MCP server tools."

Troubleshooting

Skill won't upload

"Could not find SKILL.md in uploaded folder" Rename the file to exactly SKILL.md (case-sensitive). Verify with ls -la.

"Invalid frontmatter" Check for missing --- delimiters or unclosed quotes:

# Wrong — missing delimiters
name: my-skill
description: Does things

# Wrong — unclosed quotes
name: my-skill
description: "Does things

# Correct
---
name: my-skill
description: Does things
---

"Invalid skill name" Name has spaces or capitals. Use my-skill-name not My Skill Name.

Skill doesn't trigger

The description is too generic or missing trigger phrases. Quick checklist:

Is it too vague? ("Helps with projects" won't work)
Does it include phrases users would actually say?
Does it mention relevant file types if applicable?

Fix: revise the description using the WHAT + WHEN formula and add specific trigger phrases.

Skill triggers too often

Add negative triggers, be more specific, or clarify scope:

# Too broad
description: Processes documents

# More specific with negative trigger
description: Processes PDF legal documents for contract review. Do NOT use for
  general document editing or non-legal documents.

Instructions not followed

Common causes:

Instructions too verbose — use bullet points, move detail to references/
Critical instructions buried — put them at the top with ## Critical headers
Ambiguous language — replace "validate things properly" with "CRITICAL: Before calling create_project, verify project name is non-empty and start date is not in the past"

MCP connection issues

Checklist:

Verify MCP server is connected (Claude.ai: Settings > Extensions — should show "Connected")
Check API keys are valid and not expired, with proper permissions/scopes
Test MCP independently — ask Claude to call the MCP directly without the skill. If that fails, the issue is the MCP, not the skill.
Verify tool names in the skill match the MCP server documentation exactly (case-sensitive)

Large context issues

Symptoms: skill seems slow or responses are degraded.

Solutions:

Keep SKILL.md under 5,000 words — move detailed docs to references/
Avoid having more than 20-50 skills enabled simultaneously
Consider skill "packs" for related capabilities to enable selectively

Pre-flight Checklist

Use this before and after upload.

Before you start:

Identified 2-3 concrete use cases
Tools identified (built-in or MCP)
Reviewed example skills from the skills library

During development:

Folder named in kebab-case
SKILL.md file exists (exact spelling)
YAML frontmatter has --- delimiters
name field: kebab-case, no spaces, no capitals
description includes WHAT and WHEN to use it
No XML tags (< >) anywhere in frontmatter
Instructions are clear and actionable
Error handling included
Examples provided
Detailed documentation moved to references/ and linked

Before upload:

Tested triggering on obvious tasks
Tested triggering on paraphrased requests
Verified doesn't trigger on unrelated topics
Functional tests pass
Tool integration works (if applicable)

After upload:

Test in real conversations
Monitor for under/over-triggering
Collect user feedback
Iterate on description and instructions
Update version in metadata

Learn How to Create Claude Skills

Here is a helpful guide on creating Claude skills from scratch: Guide To Agent Skills