skill-writer

name	skill-writer
description	Creates effective SKILL.md agent skills following best practices. Use when the user asks to create a skill, write a SKILL.md, or needs help authoring agent instructions.

Skill Writing

Quick Start

Every skill needs a SKILL.md file with YAML frontmatter and markdown body:

---
name: task-name
description: What it does and when to use it (third person, specific)
---

# Task Name (display heading may use title case)

[Concise instructions here]

Core Workflow

Copy and track your progress:

Skill Creation:
- [ ] Step 1: Identify the reusable pattern
- [ ] Step 2: Draft concise instructions
- [ ] Step 3: Add metadata (name, description)
- [ ] Step 4: Test with target model(s)
- [ ] Step 5: Iterate based on usage

Step 1: Identify the reusable pattern

What context do you repeatedly provide? What procedural knowledge is needed?

Step 2: Draft concise instructions

Start minimal. The target agent already has general reasoning ability - only add domain knowledge, workflow constraints, and tool-specific details it would not otherwise know.

Challenge each piece of information:

• Does the agent really need this explanation?
• Can I assume the target model knows this?
• Does this paragraph justify its token cost?

Step 3: Add metadata

Write description in third person, including:

• What the skill does
• When to use it (key terms and triggers)

description: Extract text from PDFs, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.

Step 4: Test with target agent(s) and model(s)

• Fast/compact model: Does it provide enough guidance?
• Default coding model: Is it clear and efficient?
• High-reasoning model: Does it avoid over-explaining?

Step 5: Iterate based on usage

Observe how the agent uses the skill. Watch for:

• Unexpected exploration paths
• Missed connections
• Overreliance on certain sections
• Ignored content

Set Appropriate Degrees of Freedom

Match specificity to task fragility:

High freedom (text instructions): Multiple approaches valid, context-dependent Medium freedom (pseudocode/templates): Preferred pattern exists, variation acceptable Low freedom (exact scripts): Operations fragile, consistency critical

Progressive Disclosure

Keep SKILL.md body under 500 lines. Split into separate files:

# SKILL.md

## Quick start
[Basic usage here]

## Advanced features
**Form filling**: See [FORMS.md](FORMS.md)
**API reference**: See [REFERENCE.md](REFERENCE.md)

Important:

• Keep references one level deep from SKILL.md
• Use forward slashes in paths (not backslashes)
• Add table of contents for files >100 lines

Common Patterns

Workflow pattern (complex tasks):

## Workflow
Copy this checklist:
- [ ] Step 1: Do first thing
- [ ] Step 2: Do second thing
[Detailed steps below]

Feedback loop (quality-critical):

1. Create output
2. Validate: `python scripts/validate.py`
3. If validation fails, fix and repeat
4. Only proceed when validation passes

Template pattern (consistent output):

ALWAYS use this exact structure:
[Template here]

Anti-Patterns to Avoid

❌ Windows-style paths (scripts\\helper.py) ✓ Unix-style paths (scripts/helper.py)

❌ Too many options ("You can use X, or Y, or Z...") ✓ Provide default with escape hatch ("Use X. For special case, use Y instead.")

❌ Time-sensitive info ("Before August 2025...") ✓ Use "Current method" and "Old patterns" sections

❌ Inconsistent terminology (mix "field", "box", "element") ✓ Choose one term, use consistently

❌ Deeply nested references (SKILL.md → advanced.md → details.md) ✓ One level deep (SKILL.md → details.md)

For Skills with Code

Utility scripts: Provide pre-made scripts rather than having the agent write them

• More reliable than generated code
• Save tokens and time
• Ensure consistency

Package dependencies: List required packages and verify availability

Visual analysis: Convert to images for the agent to analyze layouts

Verifiable outputs: Create plan files that get validated before execution

Quick Reference

Frontmatter name: Use the lowercase hyphenated directory slug (processing-pdfs, analyzing-data).

Display heading: Use natural title case and gerund wording when helpful (# Processing PDFs).

Description: Third person, specific, includes when to use

File limit: Keep SKILL.md under 500 lines

Structure: YAML frontmatter + markdown body

Testing: Test with all target models

Conciseness: Assume the target agent can infer common knowledge; only add what's needed