Skills Manual

Skills Manual

How to build effective skills for AI coding agents. For the full Anthropic guide, see references/skill-builder-guide.md.

Skill Structure

your-skill-name/              # kebab-case, no spaces, no capitals, no underscores
  SKILL.md                    # Required — must be exactly this name (case-sensitive)
  references/                 # Optional — supporting docs loaded on demand
  scripts/                    # Optional — executable code
  assets/                     # Optional — templates, icons

• The main file MUST be named SKILL.md — not skill.md, SKILL.MD, or anything else
• Do NOT include README.md inside the skill folder
• Folder name must be kebab-case (e.g., notion-project-setup)

YAML Frontmatter

---
name: your-skill-name                     # Required — kebab-case, must match folder name
description: "What and when."             # Required — max 1024 chars, no < > brackets
license: MIT                              # Optional
allowed-tools: "Bash(python:*) WebFetch"  # Optional — restrict tool access
metadata:                                 # Optional
  author: Name
  version: 1.0.0
---

Security Restrictions

• No XML angle brackets (< >) in frontmatter — it appears in system prompt
• No "claude" or "anthropic" in skill names (reserved)

Writing the Description

The description is the most important field. It controls when the skill gets loaded via progressive disclosure:

1. Frontmatter (always loaded) — Claude reads the description to decide relevance
2. SKILL.md body (loaded when relevant) — full instructions
3. Linked files (loaded on demand) — references, scripts, assets

The description MUST include both:

• What the skill does
• When to use it — specific trigger phrases users would actually say

Good:

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:

description: "Helps with projects."

To debug: ask Claude "When would you use the [skill name] skill?" — it will quote the description back, revealing what's missing.

Writing Instructions

Structure

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

# Skill Name

## Instructions
Step-by-step workflow with clear actions.

## Examples
Common scenarios with expected inputs/outputs.

## Troubleshooting
Common errors, causes, and fixes.

Rules

• Lead with the most important rules
• Be specific — include commands, file paths, expected outputs
• Use numbered steps for sequential workflows, bullet points for guidelines
• Show examples of correct and incorrect usage
• Include error handling for common failures
• Reference bundled files explicitly (e.g., "see references/api-guide.md")
• Keep SKILL.md under 5,000 words — move detailed docs to references/
• Composability — assume other skills may be loaded simultaneously

Iteration Signals