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

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:

   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

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.