---
title: "Building Skills for Claude — Complete Guide"
aliases: [claude-skills, skill-creation, SKILL.md guide]
tags: [claude-code, anthropic, skills, mcp, workflow-automation, ai-tooling]
sources: [raw/file_EE003DA9-270B-4159-A329-C89962F85415.pdf]
created: 2026-05-06
updated: 2026-05-06
---

# Building Skills for Claude — Complete Guide

A **skill** is a folder containing a `SKILL.md` file (plus optional scripts, references, and assets) that teaches Claude how to handle a specific task or workflow consistently — without re-explaining it every session. This is Anthropic's official guide, published alongside the Agent Skills open standard.

## What Is a Skill?

A skill folder contains:

| File/Dir | Required | Purpose |
|---|---|---|
| `SKILL.md` | Yes | Markdown instructions with YAML frontmatter |
| `scripts/` | No | Executable code (Python, Bash, etc.) |
| `references/` | No | Docs loaded on demand |
| `assets/` | No | Templates, fonts, icons for output |

Skills use **progressive disclosure** — a three-level loading system:
- **Level 1 (YAML frontmatter):** Always in Claude's system prompt. Just enough to decide when to load the skill.
- **Level 2 (SKILL.md body):** Loaded when Claude deems the skill relevant. Full instructions.
- **Level 3 (Linked files):** Additional files Claude navigates only as needed.

This minimizes token usage while keeping specialized expertise available.

## Core Design Principles

**Composability** — Skills work alongside each other. Don't assume exclusivity.

**Portability** — Skills work identically across Claude.ai, Claude Code, and API. One skill, all surfaces.

**MCP + Skills = Kitchen Analogy:**
- MCP provides the professional kitchen (tools, data access)
- Skills provide the recipes (step-by-step workflows, best practices)

## Planning: Use Cases First

Before writing any `SKILL.md`, define 2–3 concrete use cases:

```
Use Case: Project Sprint Planning
Trigger: "help me plan this sprint" / "create sprint tasks"
Steps:
  1. Fetch project status from Linear (via MCP)
  2. Analyze team velocity
  3. Suggest prioritization
  4. Create tasks with labels and estimates
Result: Fully planned sprint with tasks created
```

### Three Common Categories

**Category 1 — Document & Asset Creation:** Consistent output (docs, code, designs). Uses embedded style guides, templates, quality checklists. No external tools required.

**Category 2 — Workflow Automation:** Multi-step processes with consistent methodology. May coordinate multiple MCP servers. Uses step-by-step flows with validation gates.

**Category 3 — MCP Enhancement:** Workflow guidance layered on top of MCP tool access. Embeds domain expertise. Coordinates multiple MCP calls in sequence.

## Technical Requirements

### File and Folder Naming
- Folder: `kebab-case` only — `notion-project-setup` ✅, `Notion Project Setup` ❌
- Main file: exactly `SKILL.md` (case-sensitive — `skill.md` fails)
- No `README.md` inside the skill folder (use `SKILL.md` or `references/`)

### YAML Frontmatter

Minimal required format:

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

**`name`** — kebab-case, no spaces, no capitals, matches folder name.

**`description`** — the most important field. Must include BOTH what it does AND when to use it. Under 1024 characters. No XML angle brackets. Include trigger phrases users would actually say.

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

Good example:
```yaml
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:
```yaml
description: Helps with projects.          # Too vague
description: Creates documentation systems. # Missing triggers
```

Optional fields: `license`, `compatibility` (1–500 chars), `metadata` (author, version, mcp-server, etc.).

**Security:** Forbidden in frontmatter — XML angle brackets `< >`, and names prefixed with "claude" or "anthropic" (reserved). Frontmatter appears in Claude's system prompt — malicious content could inject instructions.

## Writing Effective Instructions

Recommended `SKILL.md` body structure:

```markdown
# Skill Name

## Instructions

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

## Examples

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

## Troubleshooting

### Error: [Common error message]
Cause: ...
Solution: ...
```

**Best practices:**
- Be specific and actionable — show exact commands with expected output
- Include error handling for common MCP issues (auth, connection, tool names)
- Reference bundled files explicitly: `consult references/api-patterns.md for rate limiting guidance`
- Keep `SKILL.md` under 5,000 words; move detailed docs to `references/`
- For critical validations, bundle a script — code is deterministic; language instructions aren't

## Testing and Iteration

Three testing levels: manual in Claude.ai (fastest), scripted in Claude Code, programmatic via API.

**Pro tip:** Iterate on a single challenging task until Claude succeeds, then extract that approach into the skill.

### Three Test Areas

**1. Triggering tests** — Does the skill load at the right times?
- Should trigger on obvious tasks and paraphrased requests
- Should NOT trigger on unrelated queries

**2. Functional tests** — Does the skill produce correct outputs?
- Valid output generated, API calls succeed, edge cases covered

**3. Performance comparison** — Does the skill improve on baseline?
- Target: 90% auto-trigger rate, fewer back-and-forth messages, lower token consumption

### Iteration Signals

| Signal | Fix |
|---|---|
| Skill never loads (undertriggering) | Add trigger phrases, more specificity |
| Skill loads for everything (overtriggering) | Add negative triggers, clarify scope |
| Inconsistent execution | Improve instructions, add error handling |

The `skill-creator` skill (built into Claude.ai and downloadable for Claude Code) can generate, review, and suggest improvements to skills.

## Distribution

### Individual Users
1. Download skill folder → zip it → upload via Settings > Capabilities > Skills
2. Or place in Claude Code skills directory

### Organization-Level
Admins can deploy skills workspace-wide (available since December 2025) with automatic updates and centralized management.

### Via API
- `/v1/skills` endpoint for listing and managing skills
- Add to Messages API requests via `container.skills` parameter
- Requires Code Execution Tool beta
- Works with the Claude Agent SDK

### Publishing Pattern
Host on GitHub (public repo, README for humans, separate from the skill folder itself). Link from your MCP documentation. Provide a quick-start installation guide.

**Positioning:** Focus on outcomes, not features. "Sets up complete project workspaces in seconds" beats "a folder containing YAML frontmatter."

## Common Patterns

**Pattern 1 — Sequential workflow orchestration:** Explicit step ordering with dependencies and validation gates. Use for multi-step processes that must run in order.

**Pattern 2 — Multi-MCP coordination:** Phases with clear handoffs between services. Pass data between MCPs, validate before advancing.

**Pattern 3 — Iterative refinement:** Draft → quality check → refinement loop → finalization. Use when output quality improves with iteration.

**Pattern 4 — Context-aware tool selection:** Decision tree picks the right tool based on file type, size, or context. Explain choices to the user.

**Pattern 5 — Domain-specific intelligence:** Embed compliance rules, domain expertise, or governance logic directly in the workflow. Compliance runs before action.

## Key Takeaways

- A skill is a `SKILL.md` file in a named folder — the description field is the single most important thing to get right; it must say both what the skill does and when to use it with actual trigger phrases
- Progressive disclosure (frontmatter → body → linked files) keeps token costs low while maintaining rich behavior
- Skills complement MCP: MCP gives Claude access, skills give Claude knowledge of how to use that access effectively
- Test triggering first (does it load when it should?), then functional correctness, then compare against baseline
- Keep `SKILL.md` under 5,000 words; move bulk documentation to `references/`; for critical validations, use bundled scripts over language instructions
- The `skill-creator` skill bootstraps first drafts and reviews existing ones in 15–30 minutes

## Key Wikilinks

- [[wiki/claude-code/skills|skills]] — Claude Code's skills system: creation, storage scopes, frontmatter, invocation, subagent execution
- [[wiki/claude-code/mcp-integration|mcp-integration]] — MCP setup and tool access that skills build workflows on top of
- [[wiki/claude-code/custom-subagents|custom-subagents]] — Custom subagents which use similar frontmatter conventions to skills
- [[wiki/claude-code/create-plugins|create-plugins]] — Plugin authoring, which bundles skills as distributable packages
