---
name: writing-agent-skills
description: Authors ultra-sharp SKILL.md skills for AI agents using the Sharp Skill method — trigger-optimized descriptions, progressive disclosure, validation-loop workflows, and eval-first testing. Use when the user asks to create, write, improve, or review a skill, a SKILL.md file, a slash command, or asks why a skill is not triggering. Do not use for writing prompts or system prompts, CLAUDE.md project instructions, or MCP tool definitions.
---

<!--
Author: Simon-Pierre Boucher
Contact: contact@spboucher.ai
-->

# Writing Agent Skills

## When to use / when NOT to use
- **Use for:** creating new skills, sharpening existing SKILL.md files, fixing skills that under- or over-trigger, reviewing a skill against the checklist.
- **Do NOT use for:** prompts/system prompts, CLAUDE.md instructions, MCP tool schemas, or agent definitions — different formats with different rules.

## House rules

1. **The description is the trigger — write it as WHAT + WHEN + NOT.** Third person, directive, ≤1024 chars, with the literal phrases a user would type.
   - ✅ "Profiles CSV files and produces a data-quality report. Use when the user asks to profile, audit, or inspect a CSV… Do not use for converting or editing CSV data."
   - ❌ "Helps with CSV files."

2. **One default per decision, with an escape hatch.**
   - ✅ "Use pdfplumber for extraction; for scanned PDFs use OCR (pytesseract) instead."
   - ❌ "You can use pypdf, pdfplumber, PyMuPDF, or…"

3. **Progressive disclosure:** body under 500 lines (aim far lower); depth in `references/` linked one level deep; a table of contents in any reference over 100 lines; scripts for deterministic work with intent explicit ("Run scripts/x.py" vs "See scripts/x.py for the algorithm").

4. **Workflows end in validation.** Numbered steps; the last step checks the output and loops back on failure.
   - ✅ "Step 5: re-parse the output file; if invalid, fix and repeat step 3."
   - ❌ A list of steps that ends at "deliver".

5. **Assume the agent is smart.** Cut anything a strong model already knows; every paragraph must justify its token cost.
   - ✅ Straight to the library call and the project-specific rule.
   - ❌ "PDF (Portable Document Format) files are a common format that…"

6. **Specify the output completely:** structure, naming, destination, and input→output examples wherever style matters.

7. **Boundaries are pairwise-exclusive.** Name the nearest neighboring intent and exclude it explicitly, so no request plausibly fires two skills.

8. **Eval-first:** before shipping, write 3+ test prompts — at least one that must NOT trigger — and run/simulate them.

## Workflow

1. Define the skill's single intent in one sentence; name it in gerund form (lowercase, hyphens, ≤64 chars, no reserved words).
2. Draft the description: WHAT clause + "Use when …" with literal trigger phrases + "Do not use for …" naming the nearest non-target intent.
3. Write the body: when/not-when, rules or quick reference (one default per decision), numbered workflow ending in validation, edge cases, one-level-deep references.
4. Move anything long into `references/` (TOC if over 100 lines); write scripts for deterministic steps and make execute-vs-read intent explicit.
5. Write 3+ test prompts (≥1 negative); simulate each against the description; adjust wording until positives fire and negatives don't.
6. Final gate: run the Sharp Skill Checklist (see references) line by line; fix every failure and re-run before delivering.

## Edge cases
- **Skill under-triggers** → rewrite the description with the user's literal phrasing; check the collection's total description budget (Claude Code truncates the listing) — shorten siblings if needed.
- **Skill over-triggers** → add the "Do not use for" clause naming the intents it's stealing; move generic keywords out of the description.
- **Two skills fight over requests** → redraw the boundary in BOTH descriptions so they exclude each other by name.
- **Skill too long** → split by domain into reference files, or split into two skills if it has two intents.

## References
The full checklist, description formula, and worked examples: see [references/examples.md](references/examples.md).