skill-authoring

# Creating Agent Skills

## What Is a Skill

A folder with a `SKILL.md` file containing YAML frontmatter and markdown instructions.

```
skill-name/
├── SKILL.md           # Required
├── references/        # Optional: detailed docs
├── scripts/           # Optional: executable code
└── assets/            # Optional: templates, data
```

## SKILL.md Format

```yaml
---
name: skill-name
description: What this does and when to use it.
---

# Instructions

[Markdown body with instructions]
```

### Required Fields

| Field | Constraints |
|-------|-------------|
| `name` | 1-64 chars, lowercase, hyphens ok, must match folder name |
| `description` | 1-1024 chars, third person, include "when to use" |

### Optional Fields

- `license` - License name or reference
- `compatibility` - Environment requirements
- `metadata` - Key-value pairs (author, version)
- `allowed-tools` - Pre-approved tools (experimental)

## Core Principles

### Be Concise

Claude already knows most things. Only add what it doesn't have.

```markdown
# Good (~50 tokens)
## Extract PDF text
Use pdfplumber:
import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
    text = pdf.pages[0].extract_text()

# Bad (~150 tokens)
## Extract PDF text
PDF files are a common format containing text...
To extract text, you'll need a library...
We recommend pdfplumber because...
```

### Set Degrees of Freedom

Match specificity to task fragility:

- **High freedom** (text instructions): Multiple valid approaches, context-dependent
- **Medium freedom** (templates/pseudocode): Preferred pattern exists, some variation ok
- **Low freedom** (exact scripts): Fragile operations, consistency critical

### 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

Keep SKILL.md under 500 lines. Move details to `references/`.

### Naming

Lowercase, hyphens ok, 1-64 chars. Must match