optimizing-descriptions

name

optimizing-descriptions

description

Meta-skill for auditing and rewriting SKILL.md `description` fields per the agentskills.io optimizing-descriptions framework, layered with mizchi's two-track trigger policy (Meta = explicit-invoke-only, Project = pushy auto-trigger). Invoke ONLY when the user explicitly asks to "optimize a skill description," "audit descriptions," or "rewrite descriptions per agentskills." Do NOT auto-invoke after every SKILL.md edit; description tuning is a deliberate batch, not a per-edit reflex.

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.

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:

   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.