spb/ultra-sharp-agent-skills Public

1<!--2Author: Simon-Pierre Boucher3Contact: contact@spboucher.ai4-->56# Examples — Writing Agent Skills78## Contents9- The description formula, worked10- Complete worked example: a skill sharpened (bad → house style)11- The Sharp Skill Checklist (final gate)12- Trigger-eval examples13- Gotchas1415## The description formula, worked1617`[WHAT it does, one clause with key nouns]. Use when [literal user phrases,18file extensions, key terms]. Do not use for [nearest neighboring intent].`1920✅ "Writes user-facing release notes and changelog entries in the house21style — benefit-first, grouped by Added/Improved/Fixed. Use when the user22asks to write release notes, a changelog entry, a what's-new section, or a23version announcement. Do not use for git commit messages, PR descriptions,24or API reference documentation."2526❌ "A skill for helping with release-related writing tasks." (no triggers,27no boundary, would also under-trigger — nothing matches what users type)2829## Complete worked example: a skill sharpened3031**❌ Before:**3233```markdown34---35name: json-helper36description: Helps with JSON.37---3839# JSON Helper4041This skill helps you work with JSON files. JSON (JavaScript Object42Notation) is a popular data format. You can use many tools to work with43it, such as Python's json module, jq, or JavaScript. Depending on the44situation, choose the best tool and be careful with edge cases.45```4647Failures: vague name; description has no WHAT/WHEN/NOT; explains what JSON48is; offers a menu with no default; "be careful" is not a procedure; no49workflow, no validation, no output spec.5051**✅ After (house style):**5253```markdown54---55name: processing-json56description: Creates, reads, edits, validates, and queries JSON and JSON57  Lines files. Use when the user asks to fix, format, merge, or query a58  .json or .jsonl file, or mentions invalid JSON. Do not use for YAML or59  TOML config files or for designing APIs.60---6162# Processing JSON6364## Quick reference65Read/write: stdlib `json` — `json.dump(data, f, indent=2,66ensure_ascii=False)`. Large-file queries: `jq` (must be installed).6768## Workflow691. Parse the input; on failure report the parser's line/column verbatim.702. Apply the change in Python (never regex-edit JSON).713. Write atomically (temp file, then rename).724. Validate: re-parse the written file; if it fails, fix and repeat step 2.7374## Edge cases75- Trailing commas/NaN: stdlib rejects them — report, don't "repair" silently.76```7778## The Sharp Skill Checklist (final gate)7980Triggering: description has WHAT + "Use when" + "Do not use"; literal user81phrases; third person; ≤1024 chars; name gerund-form, lowercase-hyphens.82Body: <500 lines; no known-content; one default per decision; numbered83workflow ending in validation; output fully specified; concrete examples;84edge cases addressed. Resources: references one level deep; TOC over 10085lines; execute-vs-read explicit; scripts handle own errors; dependencies86stated. Validation: 3+ test prompts incl. ≥1 negative, run before shipping.8788## Trigger-eval examples8990For `processing-json` above:9192| Prompt | Expected | Why |93|---|---|---|94| "This config.json won't parse, fix it" | TRIGGER | "fix", ".json", "invalid JSON" |95| "Merge these two .jsonl exports" | TRIGGER | "merge", ".jsonl" |96| "Convert this YAML to nicer formatting" | NO TRIGGER | YAML excluded by boundary |9798A negative prompt that triggers means the description keywords are too99broad — tighten nouns, add the exclusion by name.100101## Gotchas102103- **Descriptions are a shared budget:** in Claude Code all skill listings104  share a character budget and overflow is dropped silently — a bloated105  description can knock *other* skills out of context.106- **First person kills discovery** ("I can help you…") — the description is107  injected into a system prompt written in third person.108- **Nested references get partially read** (`head -100`); keep every109  reference file linked directly from SKILL.md.110- **Time-sensitive facts** ("before v2, do X") rot; move legacy notes into a111  collapsed "old patterns" block or delete them.112- **A skill that documents imagined problems** stays unused; run the task113  without the skill first, and write down only what the agent actually114  missed — that gap is the skill.115