optimizing-descriptions

# Optimizing Skill Descriptions Operational guide for auditing and rewriting SKILL.md `description` fields so they trigger the way mizchi wants them to. The upstream reference is [agentskills.io/skill-creation/optimizing-descriptions](https://agentskills.io/skill-creation/optimizing-descriptions). This skill keeps the framework intact and adds the mizchi-specific two-track policy on top. ## Why this exists Agents see `name + description` at startup (progressive disclosure) and decide from that alone whether to load the full SKILL.md. The description is the entire triggering contract: - **Under-specified** → skill never fires when it should. - **Over-broad** → skill fires when it shouldn't, wasting context. Both failures are silent — the skill simply isn't doing its job. This audit makes them visible. ## When to invoke Meta-skill, explicit invocation only. Triggers: - "optimize / audit / rewrite this skill's description" - "audit descriptions per agentskills" - "tune trigger accuracy" - "go through mizchi/skills and fix descriptions" Do NOT use for: - Single-skill ad-hoc edits during normal skill authoring. - Newly written skills that haven't been used yet (write the description as part of `superpowers:writing-skills`; tune only after observed mistriggering). ## Two-track policy mizchi's skills split into two categories and need **different** description shapes. Picking the wrong one is the most common audit miss. | Track | Trigger policy | Description shape | Examples | |---|---|---|---| | **Project** | Pushy — auto-trigger desirable | `Use when ... — [symptom keywords]. Trigger on [file shapes] even if user does not name [domain].` | `playwright-test`, `cloudflare-deploy`, `gh-fix-ci`, `node-sqlite-vec`, `aws-vault-mfa-iam` | | **Meta** | Under-trigger — explicit invoke only | `Invoke ONLY when the user explicitly asks ... Do NOT auto-invoke on [common ambient signals].` | `skill-selector`, `skill-finder`, `waxa-eval`, `apm-usage`, `empirical-prompt-tuning`, `retrospective-codify`, `chezmoi-management`, this skill | How to classify a skill you're auditing: - Body contains "Meta-skill" / "explicit invocation" / "明示 invoke" → **Meta**. - Body is "best practices for X" / "reference for Y" / "how to use Z" → **Project**. - Persona / chat-only skills (e.g. `chloe-chat`) follow the Meta shape but with "Activate during ..." phrasing. ## Audit checklist ### Universal (both tracks) - [ ] Imperative phrasing — `Use when ...` (Project) or `Invoke ONLY when ...` (Meta). No `Reference for ...` openers without a follow-up imperative. - [ ] User-intent focused — describes what the user wants to do, not the skill's internal mechanics. - [ ] Concise — under 1024 chars (the spec hard limit; descriptions tend to grow during optimization, so check on every edit). - [ ] First clause covers the trigger condition — `name + first sentence` is what the agent actually scans most. ### Project-track additional - [ ] Symptom / surface keywords listed: file names (`.gleam`, `gleam.toml`), error strings (`network is unreachable`, `InvalidClientTokenId`), commands (`pi.registerTool`, `apm install`). - [ ] Pushy phrasing — `even if user doesn't name <domain>` / `Trigger on <symptom> even when <tool> isn't mentioned`. Captures cases where the user describes the problem without naming the technology. ### Meta-track additional - [ ] `Invoke ONLY when ...` / `Use ONLY when ...` opener. - [ ] `Do NOT auto-invoke on ...` clause listing the common ambient signals that would otherwise trigger it (touching certain files, finishing certain tasks, etc.). - [ ] Trigger phrases the user actually says, enumerated (`"codify today's lessons"`, `"find a Stripe skill"`, etc.) — agents match natural phrasing better when the exact verbalization is on the page. ## Common rewrite patterns Distilled from a single-pass audit of mizchi/skills (12 rewrites, 2026-05-12). ### Project rewrites ``` # Before: passive, no trigger Reference for the dotenvx environment variable management tool. # After: imperative + symptom + pushy Use when working with the dotenvx env-var tool — encrypting .env, juggling .env.production / .env.staging, committing .env.vault / .env.keys, wiring into GitHub Actions. Trigger on `.env.vault` / `.env.keys` symptoms even when the user does not say "dotenvx". ``` ``` # Before: best-practices opener, no trigger Best practices for building and reviewing Gleam projects on the Erlang target. # After: imperative + file shapes + BEAM symptoms Use when writing or reviewing Gleam on the Erlang target — Wisp + Mist HTTP services, OTP processes, gleeunit testing. Trigger on `gleam.toml`, `.gleam` files, or Erlang/BEAM symptoms even when "Gleam" isn't named. ``` ``` # Before: describes the situation but no imperative ECS Service Connect の DNS alias が IPv6 アドレスを返して接続できない問題の回避策。 # After: imperative + error-string symptoms Use when ECS Service Connect の DNS alias が IPv6 アドレスを返し、 IPv4-only の Fargate task から `network is unreachable` / `EAI_AGAIN` で接続失敗する とき。 OTel Collector → Tempo の OTLP gRPC、 Fargate → Service Connect の HTTP/gRPC 通信が失敗する症状から起動 (user が IPv6 と特定していなくても OK)。 ``` ### Meta rewrites ``` # Before: "Use after X" promotes auto-trigger On task completion, pair "what failed first" with "what finally worked" and codify ... Use after trial-and-error solutions to spare future-you the same trap. Trigger phrases: "codify today's lessons," ... # After: explicit-only with user-phrase trigger anchoring Pair "what failed first" with "what finally worked" and codify the should-have-known-it insight as an ast-grep rule, a skill, or a CLAUDE.md rule. Meta-skill: invoke ONLY when the user explicitly says "codify today's lessons," "make it a skill," "drop it into lint," or asks to extract a reusable rule from a trial-and-error fix. Do NOT auto-invoke at every task completion. ``` ``` # Before: "Consult when touching" auto-triggers on path matches mizchi's chezmoi dotfiles operations: source location, diff/apply flow, skill addition, the APM vs chezmoi boundary, pre-commit. Consult when touching ~/.claude/, ~/.config/, or ~/.zshrc, or initializing a new machine. # After: explicit-intent + Do NOT auto-invoke clause Meta-skill for mizchi's chezmoi dotfiles. Invoke ONLY when the user explicitly asks to manage / diff / apply chezmoi sources, add a skill to dotfiles, audit the APM vs chezmoi boundary, or initialize a new machine. Do NOT auto-invoke when the task only happens to touch a path under ~/.claude/, ~/.config/, or ~/.zshrc — consult only on explicit dotfile-management intent. ``` ## Workflow 1. **Extract** every `description:` field. Quick recipe: ```bash for f in */SKILL.md; do dir=$(dirname "$f") echo "=== $dir ===" awk 'BEGIN{in_fm=0; in_desc=0} /^---$/{in_fm=!in_fm; if(!in_fm) exit; next} in_fm && /^description:/{in_desc=1; sub(/^description:[[:space:]]*/,""); print; next} in_fm && in_desc && /^[a-zA-Z]+:/{in_desc=0} in_fm && in_desc{print}' "$f" echo done ``` 2. **Classify** each skill as Meta or Project from the body (see Two-track policy table above). 3. **Apply the checklist** per skill. Note the failing checks, don't fix yet. 4. **Patch in one batch.** Rewrite all flagged descriptions. Don't mix description-tuning commits with skill-body edits — keep the diff to `description:` lines only so the change is reviewable as a description-only audit. 5. **Verify with `waxa audit <skill>`** — picks up surface frontmatter issues (length, name shape, trigger-condition shape). Errors must be zero; warnings about body / LICENSE are out of scope here. 6. **Mirror** to `~/.claude/skills/<name>/SKILL.md` (mizchi propagation convention — running session needs the update without waiting for `apm install -g --update`). 7. **Commit as one** with a per-skill summary in the message. One audit pass = one commit, even when it touches 10+ skills. ## Trigger accuracy testing (next stage) The agentskills.io page describes an empirical step on top of manual review: run a query set against the agent with the skill installed, count trigger rate per query, split train/validation to avoid overfitting. waxa does not have this yet — when it does (`waxa trigger` sub-command in a future release), the manual audit produced by this skill becomes the input layer, and trigger-rate measurement becomes the verification layer. Until then, manual audit + `waxa audit` is the working approach. If you do run the empirical step by hand, follow agentskills.io's specifics: - 20 queries: ~10 should-trigger + ~10 should-not-trigger. - 3 runs per query (non-determinism averaging); threshold trigger_rate ≥ 0.5 to pass should-trigger, < 0.5 to pass should-not-trigger. - 60/40 train / validation split; select the best iteration by validation pass rate, not train. - Most valuable should-not-trigger queries are **near-misses** (keyword overlap, different intent). ## Common pitfalls | Mistake | Fix | |---|---| | Adding specific keywords from failed-trigger queries verbatim | Overfitting. Generalize to the category (`.gleam files` ≫ `gleam.toml exists`). | | Writing the description in terms of internal implementation | Rewrite from user intent. "What is the user trying to do?" | | Meta skill with `Use after X` / `Consult when X` | Auto-triggers on ambient signals. Rewrite to `Invoke ONLY when explicitly asked ... Do NOT auto-invoke on X`. | | Project skill with `ONLY when the user explicitly says ...` | Under-triggers. Make it pushy: `Use when ... Trigger on [symptoms] even if X not named.` | | Description grows past 1024 chars during rewrite | Check length on every edit; cut the least-load-bearing clause first. | | Iterating five rounds with no improvement | The query set is the problem, not the description. Look at the query examples — are they too easy / too hard / mislabeled? | | Rewriting description and body in the same commit | Hard to review and to revert. Description-tuning is a separate batch. | ## Related - `agentskills.io/skill-creation/optimizing-descriptions` — upstream methodology document (the framework this skill operationalizes). - `superpowers:writing-skills` — when creating a new skill from scratch; description is one of several components. Use this skill (`optimizing-descriptions`) only after the skill exists and has been observed. - `waxa-eval` — for measuring trigger accuracy empirically (when `waxa trigger` lands). - `waxa audit <skill>` — picks up the surface frontmatter issues (length, name shape, basic trigger-condition phrasing) that this audit also flags; useful as a fast pre-check. - `skill-finder` — the rubric there includes "frontmatter-health" which overlaps with this skill's universal checklist; skill-finder uses `optimizing-descriptions` patterns implicitly when evaluating an external skill candidate.