# 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.

# 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.