The Complete Guide to Building a Skill

What is a Skill?

A skill is a folder containing:

• 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 used in output

Core Design Principles

Progressive Disclosure

Skills use a three-level system:

• First level (YAML frontmatter): Always loaded in Claude's system prompt. Provides just enough information for Claude to know when each skill should be used without loading all of it into context.
• Second level (SKILL.md body): Loaded when Claude thinks the skill is relevant to the current task. Contains the full instructions and guidance.
• Third level (Linked files): Additional files bundled within the skill directory that Claude can choose to navigate and discover only as needed.

Composability

Claude can load multiple skills simultaneously. Your skill should work well alongside others, not assume it's the only capability available.

Portability

Skills work identically across Claude.ai, Claude Code, and API. Create a skill once and it works across all surfaces without modification, provided the environment supports any dependencies the skill requires.

Technical Requirements

File Structure

your-skill-name/
├── SKILL.md              # Required - main skill file
├── scripts/              # Optional - executable code
│   ├── process_data.py
│   └── validate.sh
├── references/           # Optional - documentation
│   ├── api-guide.md
│   └── examples/
└── assets/               # Optional - templates, etc.
    └── report-template.md

Critical Rules

SKILL.md naming:

• Must be exactly SKILL.md (case-sensitive)
• No variations accepted (SKILL.MD, skill.md, etc.)

Skill folder naming:

• Use kebab-case: notion-project-setup
• No spaces: Notion Project Setup
• No underscores: notion_project_setup
• No capitals: NotionProjectSetup

No README.md:

• Don't include README.md inside your skill folder
• All documentation goes in SKILL.md or references/
• When distributing via GitHub, you'll still want a repo-level README for human users (outside the skill folder)

YAML Frontmatter

The YAML frontmatter is how Claude decides whether to load your skill. Get this right.

Minimal Required Format

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

Required Fields

name (required):

• kebab-case only
• No spaces or capitals
• Should match folder name

description (required):

• MUST include BOTH:
  • What the skill does
  • When to use it (trigger conditions)
• Under 1024 characters
• No XML tags
• Include specific tasks users might say

Optional Fields

• license: MIT, Apache-2.0
• compatibility: Environment requirements (up to 500 characters)
• metadata: Custom key-value pairs (author, version, mcp-server)

Examples of Good Descriptions

# Good - specific and actionable
description: Analyzes Figma design files and generates developer
  handoff documentation. Use when user uploads .fig files, asks
  for "design specs" or "design-to-code handoff".

# Good - includes trigger phrases
description: Manages Linear project workflows including sprint
  planning, task creation, and status tracking. Use when user
  mentions "sprint", "Linear tasks", or "project planning".

# Bad - too vague
description: Helps with projects.

# Bad - missing triggers
description: Creates sophisticated documentation systems.

Security Restrictions

Forbidden in frontmatter:

• XML angle brackets (< or >)
• Skills with "claude" or "anthropic" in name (reserved)

Writing Effective Instructions

Recommended Structure

---
name: your-skill
description: [...]
---

# Your Skill Name

## Instructions

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

Example:
python scripts/fetch_data.py --project-id PROJECT_ID
Expected output: [describe what success looks like]

## Examples

### Example 1: [common scenario]
User says: "Set up a new marketing campaign"
Actions:
1. Fetch existing campaigns via MCP
2. Create new campaign with provided parameters
Result: Campaign created with confirmation link

## Troubleshooting

### Error: [Common error message]
**Cause:** [Why it happens]
**Solution:** [How to fix]

Best Practices

Be Specific and Actionable:

# Good
Run \`python scripts/validate.py --input {filename}\` to check data format.
If validation fails, common issues include:
- Missing required fields (add them to the CSV)
- Invalid date formats (use YYYY-MM-DD)

# Bad
Validate the data before proceeding.

Include Error Handling:

## Common Issues

### MCP Connection Failed
If you see "Connection refused":
1. Verify MCP server is running
2. Confirm API key is valid
3. Try reconnecting

Use Progressive Disclosure:

Keep SKILL.md focused on core instructions. Move detailed documentation to references/ and link to it.

Common Skill Use Case Categories

Category 1: Document & Asset Creation

Used for creating consistent, high-quality output: documents, presentations, apps, designs, code.

• Embedded style guides and brand standards
• Template structures for consistent output
• Quality checklists before finalizing

Category 2: Workflow Automation

Used for multi-step processes with consistent methodology.

• Step-by-step workflow with validation gates
• Templates for common structures
• Iterative refinement loops

Category 3: MCP Enhancement

Used for workflow guidance to enhance the tool access an MCP server provides.

• Coordinates multiple MCP calls in sequence
• Embeds domain expertise
• Error handling for common MCP issues

Define Success Criteria

Quantitative Metrics

• Skill triggers on 90% of relevant queries
• Completes workflow in X tool calls
• 0 failed API calls per workflow

Qualitative Metrics

• Users don't need to prompt Claude about next steps
• Workflows complete without user correction
• Consistent results across sessions

Submit to the Platform

Once the skill is ready, submit it for security review and publication on Skills IL.