spb/ultra-sharp-agent-skills Public

1---2name: writing-agent-skills3description: 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.4---56<!--7Author: Simon-Pierre Boucher8Contact: contact@spboucher.ai9-->1011# Writing Agent Skills1213## When to use / when NOT to use14- **Use for:** creating new skills, sharpening existing SKILL.md files, fixing skills that under- or over-trigger, reviewing a skill against the checklist.15- **Do NOT use for:** prompts/system prompts, CLAUDE.md instructions, MCP tool schemas, or agent definitions — different formats with different rules.1617## House rules18191. **The description is the trigger — write it as WHAT + WHEN + NOT.** Third person, directive, ≤1024 chars, with the literal phrases a user would type.20   - ✅ "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."21   - ❌ "Helps with CSV files."22232. **One default per decision, with an escape hatch.**24   - ✅ "Use pdfplumber for extraction; for scanned PDFs use OCR (pytesseract) instead."25   - ❌ "You can use pypdf, pdfplumber, PyMuPDF, or…"26273. **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").28294. **Workflows end in validation.** Numbered steps; the last step checks the output and loops back on failure.30   - ✅ "Step 5: re-parse the output file; if invalid, fix and repeat step 3."31   - ❌ A list of steps that ends at "deliver".32335. **Assume the agent is smart.** Cut anything a strong model already knows; every paragraph must justify its token cost.34   - ✅ Straight to the library call and the project-specific rule.35   - ❌ "PDF (Portable Document Format) files are a common format that…"36376. **Specify the output completely:** structure, naming, destination, and input→output examples wherever style matters.38397. **Boundaries are pairwise-exclusive.** Name the nearest neighboring intent and exclude it explicitly, so no request plausibly fires two skills.40418. **Eval-first:** before shipping, write 3+ test prompts — at least one that must NOT trigger — and run/simulate them.4243## Workflow44451. Define the skill's single intent in one sentence; name it in gerund form (lowercase, hyphens, ≤64 chars, no reserved words).462. Draft the description: WHAT clause + "Use when …" with literal trigger phrases + "Do not use for …" naming the nearest non-target intent.473. 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.484. Move anything long into `references/` (TOC if over 100 lines); write scripts for deterministic steps and make execute-vs-read intent explicit.495. Write 3+ test prompts (≥1 negative); simulate each against the description; adjust wording until positives fire and negatives don't.506. Final gate: run the Sharp Skill Checklist (see references) line by line; fix every failure and re-run before delivering.5152## Edge cases53- **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.54- **Skill over-triggers** → add the "Do not use for" clause naming the intents it's stealing; move generic keywords out of the description.55- **Two skills fight over requests** → redraw the boundary in BOTH descriptions so they exclude each other by name.56- **Skill too long** → split by domain into reference files, or split into two skills if it has two intents.5758## References59The full checklist, description formula, and worked examples: see [references/examples.md](references/examples.md).60