Skip to content
Primores AI wiki

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:

FileRequired?Purpose
SKILL.md✅ RequiredInstructions in Markdown with YAML frontmatter
scripts/OptionalExecutable code (Python, Bash, etc.)
references/OptionalDocumentation loaded as needed
assets/OptionalTemplates, 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 kitchenThe recipes
Access to tools, ingredients, equipmentStep-by-step instructions
Connects Claude to your serviceTeaches Claude how to use it effectively
What Claude can doHow 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:

LevelWhat LoadsWhen
1. YAML frontmatterAlways in system promptEvery conversation
2. SKILL.md bodyWhen skill seems relevantOn-demand
3. Linked filesWhen Claude navigates to themAs 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

RuleCorrectWrong
File nameSKILL.mdskill.md, SKILL.MD
Folder namenotion-project-setupNotion Project Setup, notion_project_setup
Keep docs in SKILL.mdSKILL.md + references/(A README.md isn’t prohibited, but put model-facing guidance in SKILL.md/references — the README won’t be loaded as context)

YAML Frontmatter

Minimal required format:

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

Field requirements:

FieldRequiredNotes
nameAPI: ✅ · Claude Code: optionalkebab-case; in Claude Code it defaults to the directory name
description✅MUST include what AND when. API hard cap 1,024 chars; Claude Code listing cap 1,536
licenseOptionalMIT, Apache-2.0, etc.
compatibilityOptionalEnvironment requirements (1-500 chars)
metadataOptionalauthor, version, mcp-server, etc.

Claude Code adds more frontmatter fields the API doesn’t: allowed-tools / disallowed-tools, disable-model-invocation, user-invocable, model, effort, context (e.g. context: fork to run the skill in a subagent), argument-hint, and hooks. In Claude Code, .claude/commands/*.md and .claude/skills/*/SKILL.md now both create a /name command and behave the same — skills are the recommended form.

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

Pattern 3: Iterative Refinement

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 (now distributed as an official plugin — /plugin install skill-creator@claude-plugins-official) helps you. Its role has expanded beyond generation into evaluation: it can benchmark a skill, run A/B comparisons, and tune the description for reliable triggering. It 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

ErrorCauseSolution
”Could not find SKILL.md”Wrong file nameRename to exactly SKILL.md
”Invalid frontmatter”YAML formattingCheck --- delimiters, quote closure
”Invalid skill name”Spaces or capitalsUse 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:

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

Instructions Not Followed

Common causes:

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

Distribution

Distribution mechanics differ by surface, and they are not unified (this is the part that changed most since this page was first written):

claude.ai — upload a zipped skill folder via Settings → Features (requires Pro/Max/Team/Enterprise with code execution enabled). Custom skills here are per-user only — they are not centrally admin-deployed and do not sync to other surfaces. (The “workspace-wide admin management” model applies to the API, not claude.ai.)

Claude Code — filesystem-based, no zip. Drop SKILL.md into ~/.claude/skills/<name>/ (personal), .claude/skills/<name>/ (project), or managed-settings/plugin scopes (enterprise). Full network access at runtime.

API — skill_id referenced in the container parameter alongside the code-execution tool; managed via the /v1/skills endpoint; requires the current beta headers (code-execution-2025-08-25, skills-2025-10-02, files-api-2025-04-14). Works with the Claude Agent SDK. Note API skills run without network access or runtime package installs — the opposite of Claude Code. Workspace-wide sharing lives here.

Plugins and marketplaces (the dominant distribution path now)

Since mid-2026, skills are commonly packaged and shipped as Claude Code plugins, installed with /plugin from marketplaces — the official claude-plugins-official and community claude-plugins-community. This is now the main way skills get distributed and updated. Example: skill-creator is installed via /plugin install skill-creator@claude-plugins-official.

Anthropic also ships pre-built first-party skills (pptx, xlsx, docx, pdf) on both the API and claude.ai. And Agent Skills are an open standard (agentskills.io) — the SKILL.md format works across multiple AI tools, not just Claude, so a well-written skill is portable.

Use CaseBest Surface
End users interacting directlyclaude.ai / Claude Code
Manual testing during developmentClaude Code (filesystem, fast iteration)
Production deployments at scaleAPI
Sharing/installing across a team or communityPlugins + marketplace

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

Sources