Vadym Samoilenko 89daf8b484 vault backup: 2026-05-06 21:34:34

2026-05-06 21:34:34 +01:00

9 KiB

Raw Blame History

title

aliases

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:

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

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:

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:

# 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

Download skill folder → zip it → upload via Settings > Capabilities > Skills
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 — Claude Code's skills system: creation, storage scopes, frontmatter, invocation, subagent execution
wiki/claude-code/mcp-integration — MCP setup and tool access that skills build workflows on top of
wiki/claude-code/custom-subagents — Custom subagents which use similar frontmatter conventions to skills
wiki/claude-code/create-plugins — Plugin authoring, which bundles skills as distributable packages

9 KiB Raw Blame History Unescape Escape