Writing Skills

Process

• Task/domain, use cases, scripts vs. instructions, ref.
• Draft SKILL.md; split extra files past 55 lines; add scripts for deterministic ops.
• Review with the user; iterate.

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

SKILL.md Template

---
name: skill-name
description: Brief description of capability. Use when [specific triggers].
---

# Skill Name

## Quick start

[Minimal working example]

## Workflows

[Step-by-step processes with checklists for complex tasks]

## Advanced features

[Link to separate files: See [REFERENCE.md](REFERENCE.md)]

Description

Third person; what it does, then "Use when [triggers]"; ≤240 chars.

Good:

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.

Bad: Helps with documents. — indistinguishable from others.

Review Checklist

• Description includes triggers ("Use when...") and is ≤240 chars
• SKILL.md body is ≤55 lines
• No time-sensitive info
• Consistent terminology
• Concrete examples included
• References one level deep