mp-write-a-skill

---
name: mp-write-a-skill
description: Use when authoring a new agent skill — covers structure, progressive disclosure, when to add scripts, when to split files, and the trigger-rich description format that controls whether your agent picks the skill at all.
source: https://github.com/mattpocock/skills/blob/main/skills/productivity/write-a-skill/SKILL.md
generated: 2026-05-12T18:05:27.428Z
category: concept
audience: engineers
---

## When to use

- Writing a brand-new SKILL.md from scratch with frontmatter, instructions, and trigger keywords
- Deciding whether the skill needs companion files (REFERENCE.md, EXAMPLES.md, scripts/)
- Tightening a skill's description so the agent actually loads it for the right requests
- Reviewing a draft skill against a checklist of common authorship mistakes

## Key concepts

### the description is the trigger

The description is the ONLY thing the agent sees when deciding which skill to load. It sits in the system prompt alongside every other installed skill. Two sentences: (1) what it does, (2) 'Use when [specific triggers]'. Max 1024 chars, written in third person.

### progressive disclosure

Keep SKILL.md under 100 lines. Move detail to REFERENCE.md, EXAMPLES.md, or scripts/. The agent reads SKILL.md every time the skill loads; reference files only when needed. This is the token-efficiency rule.

### scripts for deterministic work

Add a script (bash / node / python) when the operation is deterministic (validation, formatting), the same code would be regenerated repeatedly, or errors need explicit handling. Scripts save tokens AND are more reliable than regenerated code.

### split files

Split into separate files when SKILL.md exceeds 100 lines, content covers distinct domains (e.g. finance vs sales schemas), or advanced features are rarely needed. Reference files should be ONE level deep — don't nest.

### good vs bad description

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.' The bad example gives the agent no way to distinguish this from other document skills.

### draft → review → iterate

Gather requirements first (task / use cases / scripts? / reference materials?). Draft SKILL.md + companions. Then REVIEW with the user: does this cover your cases? anything missing? any section over/under-detailed? Iterate before shipping.

## API reference

```
Skill directory structure
```

Standard layout. SKILL.md is required; everything else is conditional.

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

Frontmatter + Quick start + Workflows + Advanced features link.

```
---
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 format
```

Two sentences, third person, max 1024 chars. First sentence = what it does. Second sentence = 'Use when [triggers]'.

```
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."
```

```
Review checklist
```

Run before shipping. Each item catches a common mistake.

```
[ ] Description includes triggers ("Use when...")
[ ] SKILL.md under 100 lines
[ ] No time-sensitive info
[ ] Consistent terminology
[ ] Concrete examples included
[ ] References one level deep
```

## Gotchas

- The description is the ONLY signal the agent uses to pick this skill. Vague descriptions get skipped — list concrete triggers.
- Keep SKILL.md under 100 lines. Beyond that, split into REFERENCE.md / EXAMPLES.md / scripts/.
- Write descriptions in THIRD person, not first. 'Extracts text…' not 'I extract text…'.
- Don't include time-sensitive info (dates, version numbers, 'as of October 2026'). Skills outlive the context they were written in.
- Use consistent terminology — don't call the same concept 'component', 'module', and 'service' across one skill.
- References go ONE level deep (SKILL.md → REFERENCE.md). Don't make agents traverse a tree.
- Add scripts for deterministic work — generated code drifts, scripts don't.
- Always review the draft with the user before shipping. The author often misses missing cases the user spots in 10 seconds.

---
Generated by SkillMake from https://github.com/mattpocock/skills/blob/main/skills/productivity/write-a-skill/SKILL.md on 2026-05-12T18:05:27.428Z.
Verify against source before relying on details.

File: ~/.claude/skills/mp-write-a-skill/SKILL.md