write-a-skill

---
name: write-a-skill
description: Use when creating new agent skills with proper structure, progressive disclosure, and bundled resources.
category: Engineering
version: 1.0.0
tools: []
---

# Writing Skills

Derived from Matt Pocock's write-a-skill methodology (MIT). Author skills with concise instructions, progressive disclosure, and bundled utility scripts.

## Process

1. **Gather requirements:**
   - What task/domain does the skill cover?
   - What specific use cases should it handle?
   - Does it need executable scripts or just instructions?
   - Any reference materials to include?

2. **Draft the skill** with concise instructions and any required utility scripts or reference files.

3. **Review with user** and iterate until it covers their use cases and is clear.

## Skill Structure

```
skill-name/
├── SKILL.md           # Main instructions (required)
├── REFERENCE.md       # Detailed docs (if needed)
├── EXAMPLES.md        # Usage examples (if needed)
└── scripts/           # Utility scripts (if needed)
    └── helper.js
```

## Description Requirements

The description is the only thing an agent sees when deciding which skill to load. Give the agent just enough info to know: (1) what capability this skill provides, (2) when/why to trigger it (specific keywords, contexts, file types).

**Format:** Max 1024 chars, third person, first sentence = what it does, second sentence = "Use when [specific triggers]"

**Good example:** "Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when user mentions PDFs, forms, or document extraction."

## When to Add Scripts

Add utility scripts when: operation is deterministic (validation, formatting), same code would be generated repeatedly, or errors need explicit handling.

## When to Split Files

Split into separate files when: SKILL.md exceeds 100 lines, content has distinct domains, or advanced features are rarely needed.

## Review Checklist

After drafting, verify: Description includes triggers ("Use when..."), SKILL.md under 100 lines, no time-sensitive info, consistent terminology, concrete examples included, references one level deep.