I Read Anthropic's Internal Guide on Building Claude Skills. Here's Everything You Need to Know.

Published: at 02:31 PM
(Ruqaiya Beguwala) ★★★★★

This article summarizes Anthropic’s internal guide on building skills for Claude, covering essential aspects from skill structure to testing and distribution.

What is a Skill?

A skill is essentially a folder containing a SKILL.md file (required) and optional subfolders for scripts, references, and assets. This folder is zipped and uploaded to Claude, enabling it to perform specific workflows.

Three-Level Loading System

Skills load in three levels:

  1. YAML Frontmatter: Always present, used to determine skill relevance.
  2. SKILL.md Body: Loaded when the skill is deemed applicable, containing the main instructions.
  3. Linked Files (references/): Loaded only when needed, providing deep documentation and edge-case guides.

The frontmatter description is crucial for triggering the skill.

Writing the SKILL.md File

The SKILL.md file consists of:

  • YAML Frontmatter: Includes name (kebab-case) and description (what the skill does and when to use it). Optional fields like license, author, version, and mcp-server can be added.
  • Instructions Body: Written in Markdown, providing step-by-step instructions, examples, and troubleshooting tips.

Example:

---
name: your-skill-name
description: What it does and when to use it.
---

# Skill Name

## Step 1: First thing
Clear explanation. What to do, what success looks like.

## Step 2: Next thing
...
## Examples
User says: "Set up a new project"
Actions:
1.  Fetch existing projects via MCP
2.  Create new project with provided parameters
Result: Project created with confirmation link
## Troubleshooting
Error: Connection refused
Cause: MCP server isn't running
Solution: Settings > Extensions > [Service] > Reconnect

Skill Categories

Anthropic identifies three main use cases:

  1. Document and Asset Creation: Generating consistent outputs (documents, code, designs).
  2. Workflow Automation: Multi-step processes with consistent methodology.
  3. MCP Enhancement: Workflow guidance layered on top of an existing MCP server connection.

Skills + MCP

Skills provide the “recipes” for using MCP (which provides the “kitchen”). Skills enable consistent workflows and embed domain expertise.

Five patterns for MCP-enhanced skills:

  1. Sequential workflow orchestration
  2. Multi-MCP coordination
  3. Iterative refinement
  4. Context-aware tool selection
  5. Domain-specific intelligence

Testing Your Skill

Testing involves:

  • Triggering Tests: Ensuring the skill loads when it should.
  • Functional Tests: Verifying correct output.
  • Performance Comparison: Comparing performance with and without the skill.

Debugging tip: Ask Claude when it would use the skill to identify gaps in the description.

Common Failures and Fixes

  • Skill won’t upload: Naming issues (e.g., incorrect case for SKILL.md).
  • Skill doesn’t trigger: Vague description or missing trigger phrases.
  • Skill triggers too much: Lack of negative triggers or specific scope.
  • MCP calls fail: MCP connection issues.
  • Claude ignores instructions: Instructions are too long, critical steps are buried, or language is ambiguous.
  • Context feels slow: Keep SKILL.md under 5,000 words and limit the number of enabled skills.

Distributing Your Skill

Distribution involves hosting the skill on GitHub with a clear README and adding it to MCP documentation. Organization admins can deploy skills workspace-wide.

Checklist

  • Identify concrete use cases and needed tools.
  • Use kebab-case folder name and exact SKILL.md spelling.
  • Include both “what” and “when” in the description.
  • Provide clear, specific instructions with error handling and examples.
  • Test triggering and workflow.
  • Monitor for under/over-triggering and iterate based on feedback.

Key Takeaway

The description field is critical for determining when Claude loads the skill. Get it right first.

Read the original article