Skill Authoring

Skill Authoring

Build effective Skills that Claude can discover and use.

Quick Start

# Initialize a new skill
python .claude/skills/skill-authoring/scripts/init_skill.py my-skill-name

# Validate a skill
python .claude/skills/skill-authoring/scripts/quick_validate.py .claude/skills/my-skill/

# Package for distribution
python .claude/skills/skill-authoring/scripts/package_skill.py .claude/skills/my-skill/

Skill Structure

my-skill/
├── SKILL.md              # Required: instructions + YAML frontmatter
├── scripts/              # Optional: executable code (not loaded into context)
├── references/           # Optional: documentation (loaded when needed)
└── assets/               # Optional: output templates, images

YAML Frontmatter

---
name: my-skill-name
description: Does X for Y. Use when working with Y or when user mentions X.
---

Rules:

• name: lowercase, hyphens, max 64 chars, no "anthropic"/"claude"
• description: max 1024 chars, third person, include WHAT + WHEN triggers

Three-Level Loading

Core Principles

1. Be Concise

Claude is smart. Only add what Claude doesn't know.

# BAD: 150 tokens explaining what PDFs are
# GOOD: 50 tokens with just the code
import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
    text = pdf.pages[0].extract_text()

2. Match Freedom to Fragility

3. Progressive Disclosure

Keep SKILL.md < 500 lines. Split details into references/:

## Quick start
[Core instructions]

## Advanced
See [references/advanced.md](references/advanced.md)

4. One-Level Deep References

# GOOD: flat
SKILL.md -> references/api.md
SKILL.md -> references/examples.md

# BAD: nested
SKILL.md -> advanced.md -> details.md -> info

Output Patterns

See references/output-patterns.md for:

• Template Pattern (strict vs flexible)
• Examples Pattern (input/output pairs)

Workflow Patterns

See references/workflows.md for:

• Sequential workflows
• Conditional workflows
• Feedback loops

Scripts

Execute, don't load:

Run: `python scripts/analyze.py input.pdf`

Handle errors explicitly:

def process(path):
    try:
        return open(path).read()
    except FileNotFoundError:
        print(f"Creating {path}")
        return ""

Anti-Patterns

Validation Checklist

• name: lowercase, hyphens, max 64 chars
• description: WHAT + WHEN, third person
• SKILL.md < 500 lines
• References 1 level deep
• Scripts handle errors
• No Windows paths