Creating Agent Skills

Quick Start

my-skill/
├── SKILL.md          # Required: metadata + instructions
├── scripts/          # Optional: executable code
├── references/       # Optional: detailed docs
└── assets/           # Optional: templates, resources

SKILL.md Structure

---
name: skill-name          # lowercase, hyphens only, max 64 chars
description: What it does and when to use it.  # max 1024 chars
---

# Skill Title

Brief intro and "Use this skill when..." statement.

## Quick Start
[Most common use case with example]

## Core Features
[Main capabilities organized by task]

## Support Files
[Links to reference files for detailed info]

Naming Conventions

• processing-pdfs

  (preferred)

• analyzing-data

  (preferred)

• pdf-processor

  (acceptable)

• Lowercase letters, numbers, hyphens only
• No consecutive hyphens (

  --

  )
• Cannot start/end with hyphen
• Max 64 characters

Writing Descriptions

1. What it does (actions/capabilities)
2. When to use it (triggers/contexts)

description: Extracts text and tables from PDF files, fills forms, merges documents. Use when working with PDF files or when user mentions PDFs, forms, or document extraction.

description: Helps with PDFs.  # Too vague

Progressive Disclosure

1. Metadata (~100 tokens): Loaded at startup for all skills
2. SKILL.md body (<5000 tokens): Loaded when skill activates
3. Reference files: Loaded only when needed

## Detailed Topics

**Form filling**: See [FORMS.md](references/FORMS.md)
**API reference**: See [REFERENCE.md](references/REFERENCE.md)
**Examples**: See [EXAMPLES.md](references/EXAMPLES.md)

Key Principles

1. Be concise: Claude is smart; only add context it doesn't have
2. Test with all models: What works for Opus may need detail for Haiku
3. Use workflows: Break complex tasks into clear, sequential steps
4. Include feedback loops: Validate → fix → repeat for quality
5. Avoid time-sensitive info: Use "old patterns" sections instead

Checklist

• Name uses lowercase/hyphens, matches directory name
• Description explains what AND when
• SKILL.md under 500 lines
• Reference files for detailed content
• Examples are concrete, not abstract
• Tested with real usage scenarios

Resources

• Agent Skills Specification
• Best Practices
• Example Skills