Claude Skills — Persistent Instructions for Workflows

Claude Skills

TL;DR: Skills are folders containing instructions that teach Claude how to handle specific tasks. Unlike prompts that disappear after each conversation, Skills persist — teach Claude once, benefit every time. Build a functional skill in 15-30 minutes.

What Is a Skill?

A skill is a folder containing:

File	Required?	Purpose
`SKILL.md`	✅ Required	Instructions in Markdown with YAML frontmatter
`scripts/`	Optional	Executable code (Python, Bash, etc.)
`references/`	Optional	Documentation loaded as needed
`assets/`	Optional	Templates, fonts, icons for output

Key insight: Skills are powerful for repeatable workflows — generating designs from specs, research with consistent methodology, documents following your style guide, or multi-step processes.

Skills vs. MCP: The Kitchen Analogy

MCP (Connectivity)	Skills (Knowledge)
The professional kitchen	The recipes
Access to tools, ingredients, equipment	Step-by-step instructions
Connects Claude to your service	Teaches Claude how to use it effectively
What Claude can do	How Claude should do it

Together: Users accomplish complex tasks without figuring out every step themselves.

Core Design Principles

1. Progressive Disclosure (Three Levels)

Skills minimize token usage while maintaining expertise:

Level	What Loads	When
1. YAML frontmatter	Always in system prompt	Every conversation
2. SKILL.md body	When skill seems relevant	On-demand
3. Linked files	When Claude navigates to them	As needed

2. Composability

Claude can load multiple skills simultaneously. Design skills to work alongside others.

3. Portability

Skills work identically across Claude.ai, Claude Code, and API. Create once, works everywhere.

Three Skill Categories

Category 1: Document & Asset Creation

Use for: Creating consistent, high-quality outputs (documents, presentations, designs, code).

Example: frontend-design skill — “Create distinctive, production-grade frontend interfaces.”

Key techniques:

Embedded style guides and brand standards
Template structures for consistent output
Quality checklists before finalizing
Uses Claude’s built-in capabilities (no external tools)

Category 2: Workflow Automation

Use for: Multi-step processes that benefit from consistent methodology.

Example: skill-creator skill — “Interactive guide for creating new skills.”

Key techniques:

Step-by-step workflow with validation gates
Templates for common structures
Built-in review and improvement suggestions
Iterative refinement loops

Category 3: MCP Enhancement

Use for: Adding workflow guidance to MCP tool access.

Example: sentry-code-review skill — “Analyzes and fixes bugs in PRs using Sentry’s error monitoring via MCP.”

Key techniques:

Coordinates multiple MCP calls in sequence
Embeds domain expertise
Provides context users would otherwise need to specify
Error handling for common MCP issues

Technical Requirements

File Structure

your-skill-name/
├── SKILL.md              # Required
├── scripts/              # Optional
│   ├── process_data.py
│   └── validate.sh
├── references/           # Optional
│   ├── api-guide.md
│   └── examples/
└── assets/               # Optional
    └── report-template.md

Critical Naming Rules

Rule	Correct	Wrong
File name	`SKILL.md`	`skill.md`, `SKILL.MD`
Folder name	`notion-project-setup`	`Notion Project Setup`, `notion_project_setup`
No README.md	Inside skill folder	Put docs in SKILL.md or references/

YAML Frontmatter

Minimal required format:

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

Field requirements:

Field	Required	Notes
`name`	✅	kebab-case, must match folder name
`description`	✅	MUST include what AND when, under 1024 chars
`license`	Optional	MIT, Apache-2.0, etc.
`compatibility`	Optional	Environment requirements (1-500 chars)
`metadata`	Optional	author, version, mcp-server, etc.

Security restrictions:

No XML angle brackets (< >) — they appear in system prompts
No “claude” or “anthropic” in skill names (reserved)

Writing Effective Descriptions

The description field determines when Claude loads your skill.

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

Good Examples

# Specific and actionable
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 trigger phrases
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".

# Clear value proposition
description: End-to-end customer onboarding workflow for PayFlow.
Handles account creation, payment setup, and subscription management.
Use when user says "onboard new customer", "set up subscription",
or "create PayFlow account".

Bad Examples

# Too vague
description: Helps with projects.

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

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

Workflow Patterns

Pattern 1: Sequential Workflow Orchestration

Use when: Multi-step processes in 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)

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

Use when: Output quality improves with iteration.

### Initial Draft
1. Fetch data via MCP
2. Generate first draft report

### Quality Check
1. Run validation script: `scripts/check_report.py`
2. Identify issues

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

Pattern 4: Context-Aware Tool Selection

Use when: Same outcome, different tools depending on context.

### 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

Pattern 5: Domain-Specific Intelligence

Use when: Adding specialized knowledge beyond tool access.

### 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

Testing and Iteration

Three Testing Areas

1. Triggering tests: Does skill load at the right times?

✅ Triggers on obvious tasks
✅ Triggers on paraphrased requests
❌ Doesn’t trigger on unrelated topics

2. Functional tests: Does it produce correct outputs?

Valid outputs generated
API calls succeed
Error handling works

3. Performance comparison: Does it improve results?

Without skill:
- 15 back-and-forth messages
- 3 failed API calls
- 12,000 tokens consumed

With skill:
- 2 clarifying questions only
- 0 failed API calls
- 6,000 tokens consumed

Using skill-creator

The skill-creator skill (built into Claude.ai) helps you:

Generate skills from natural language descriptions
Produce properly formatted SKILL.md
Flag common issues
Suggest test cases

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

Troubleshooting

Skill Won’t Upload

Error	Cause	Solution
”Could not find SKILL.md”	Wrong file name	Rename to exactly `SKILL.md`
”Invalid frontmatter”	YAML formatting	Check `---` delimiters, quote closure
”Invalid skill name”	Spaces or capitals	Use `kebab-case` only

Skill Doesn’t Trigger

Fix: Revise description field.

Is it too generic? (“Helps with projects” won’t work)
Does it include trigger phrases users would actually say?
Does it mention relevant file types?

Debug: Ask Claude: “When would you use the [skill name] skill?”

Skill Triggers Too Often

Solutions:

Add negative triggers: “Do NOT use for simple data exploration”
Be more specific: “PDF legal documents” not “documents”
Clarify scope: “PayFlow payment processing for e-commerce”

Instructions Not Followed

Common causes:

Instructions too verbose — use bullet points, numbered lists
Instructions buried — put critical info at top
Ambiguous language — be specific about validation steps

Distribution

Current Model (2026)

Individual users:

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

Organization-level:

Admins deploy workspace-wide
Automatic updates
Centralized management

Skills via API

For programmatic use:

/v1/skills endpoint for management
Add to Messages API via container.skills parameter
Works with Claude Agent SDK

Use Case	Best Surface
End users interacting directly	Claude.ai / Claude Code
Manual testing during development	Claude.ai / Claude Code
Production deployments at scale	API
Automated pipelines and agents	API

Quick Checklist

Before you start:

Identified 2-3 concrete use cases
Tools identified (built-in or MCP)
Planned folder structure

During development:

Folder named in kebab-case
SKILL.md file exists (exact spelling)
YAML frontmatter has --- delimiters
Description includes WHAT and WHEN
No XML tags anywhere
Error handling included

Before upload:

Tested triggering on obvious tasks
Verified doesn’t trigger on unrelated topics
Compressed as .zip file

Key Takeaways

Skills persist instructions across sessions — teach once, benefit always
Three levels: frontmatter (always loaded) → body (on-demand) → references (as needed)
Description field is critical — must include what AND when
MCP provides tools, Skills provide workflows
Build a functional skill in 15-30 minutes using skill-creator

tools/claude-cowork — Desktop agent that uses Skills
tools/mcp — Protocol for connecting to systems (Skills add workflows on top)
tools/claude-managed-agents — Server-side agent infrastructure
automation/departmental-ai-guide — Skills by department

Sources

The Complete Guide to Building Skills for Claude — Anthropic (2026)
Agent Skills Open Standard — GitHub
Skills API Documentation — Anthropic Docs

Claude Skills — Persistent Instructions for Workflows

Claude Skills

What Is a Skill?

Skills vs. MCP: The Kitchen Analogy

Core Design Principles

1. Progressive Disclosure (Three Levels)

2. Composability

3. Portability

Three Skill Categories

Category 1: Document & Asset Creation

Category 2: Workflow Automation

Category 3: MCP Enhancement

Technical Requirements

File Structure

Critical Naming Rules

YAML Frontmatter

Writing Effective Descriptions

Good Examples

Bad Examples

Workflow Patterns

Pattern 1: Sequential Workflow Orchestration

Pattern 2: Multi-MCP Coordination

Pattern 3: Iterative Refinement

Pattern 4: Context-Aware Tool Selection

Pattern 5: Domain-Specific Intelligence

Testing and Iteration

Three Testing Areas

Using skill-creator

Troubleshooting

Skill Won’t Upload

Skill Doesn’t Trigger

Skill Triggers Too Often

Instructions Not Followed

Distribution

Current Model (2026)

Skills via API

Quick Checklist

Key Takeaways

Related

Sources