# Description Optimizer > Rewrites and optimizes the description field of a SKILL.md file to maximize triggering reliability. The description is the primary mechanism Claude uses to decide whether to invoke a skill — a weak description means the skill never fires, regardless of how good the body is. Use this skill whenever a user says "my skill isn't triggering", "rewrite my skill description", "optimize this description", "why doesn't my skill activate", or shares a SKILL.md with a vague or short description field. Also triggers when a user is preparing to publish a skill and wants to maximize discovery. Produces 3 ranked description variants with scores and a recommendation. Always use this skill on any skill description before publishing to a marketplace or sharing publicly. - Skill: `anvil-code/description-optimizer` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add anvil-code/description-optimizer` - Raw SKILL.md: https://api.skillmd.com/api/skills/anvil-code/description-optimizer/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Product & Planning - Author: Anvil-Code (https://skillmd.com/u/anvil-code) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/anvil-code/description-optimizer --- # Description Optimizer — Anvil & Code Rewrites SKILL.md description fields to maximize triggering reliability. The description is the single highest-leverage line in any skill — it determines whether Claude uses the skill at all. This tool generates 3 optimized variants, scores each, and gives a clear recommendation. --- ## The Triggering Problem Claude reads skill descriptions to decide whether to consult a skill for a given user request. The decision happens in milliseconds. Skills with weak descriptions get skipped even when they're the perfect tool. Common failure modes: | Description type | Trigger rate | Why | |-----------------|-------------|-----| | "A skill for helping with X" | Very low | No action verb, no trigger phrases, no specificity | | "Helps Claude do X better" | Low | Describes Claude, not what the user asks for | | "Use when user asks about X" | Moderate | Good intent but missing I/O signal | | "Generates Y from X. Use when user says [phrase1], [phrase2]..." | High | Action verb + I/O + explicit triggers | --- ## Phase 1 — Intake Ask for the skill's current description AND the skill body (if available). If the user only provides the description, work with that — but note in the output that body context would improve the variants. Also ask: "What are the top 3 things users say right before they need this skill?" This is the most valuable input for writing high-trigger descriptions. --- ## Phase 2 — Analyze the Current Description Before writing variants, diagnose what's wrong: **Score the current description on 5 dimensions (1–3 each):** 1. **Action verb** — Does it start with what Claude will DO (not what the skill is)? - 3: Opens with verb: "Generates", "Audits", "Converts", "Builds", "Extracts" - 2: Active but subject-first: "This skill generates..." - 1: Passive, noun-first, or vague opener 2. **Trigger phrases** — Does it include exact phrases users say? - 3: 3+ explicit quoted phrases ("when user says X", "triggers on Y") - 2: 1–2 phrases or paraphrased triggers - 1: No explicit trigger phrases 3. **I/O specificity** — Does it name the input and output format? - 3: Names both input format and output format explicitly - 2: Names one but not both - 1: Neither named — just describes the goal abstractly 4. **Coverage** — Does it cover multiple ways users phrase the same need? - 3: Covers formal, casual, and adjacent phrasings - 2: Covers 1–2 phrasings - 1: Only matches one exact phrasing 5. **Length** — Is it in the optimal range? - 3: 60–120 words - 2: 30–59 words or 121–200 words - 1: Under 30 or over 200 words **Current score: X/15** Report the score and a one-sentence diagnosis before writing variants. --- ## Phase 3 — Write 3 Variants Write exactly 3 variants. Each must differ meaningfully — not just rephrasing the same sentence. **Variant A — Comprehensive (recommended for complex or multi-use skills)** - Full trigger phrase coverage (5+ phrases) - Explicit I/O names - "Also triggers when" clause - "Always prefer this skill over" ending - Target: 100–130 words **Variant B — Tight (recommended for focused, single-purpose skills)** - 3 trigger phrases, precisely chosen - I/O named in first sentence - No "also triggers" — clean and direct - Target: 60–80 words **Variant C — Discovery-optimized (recommended for marketplace listings)** - Opens with the user's pain, not the skill's action - Uses terminology buyers search for - Includes the skill's differentiator vs. the obvious alternative - Target: 80–110 words --- ## Phase 4 — Score and Recommend Score each variant on the same 5-dimension rubric (1–3 each, max 15). Present scores in a table: | Dimension | Current | Variant A | Variant B | Variant C | |-----------|---------|-----------|-----------|-----------| | Action verb | X | X | X | X | | Trigger phrases | X | X | X | X | | I/O specificity | X | X | X | X | | Coverage | X | X | X | X | | Length | X | X | X | X | | **Total** | **/15** | **/15** | **/15** | **/15** | Then give a clear recommendation: "Use Variant [X] because [one sentence reason]." If the user's current description scored 12+, say so: "Your current description is strong. Here are variants if you want to experiment, but shipping as-is is reasonable." --- ## Phase 5 — Delivery Present variants in code blocks, ready to paste directly into the YAML frontmatter. Remind the user: description values with multiple lines use `>` (block scalar) in YAML: ```yaml description: > First line of description. Second line continues here. All treated as one paragraph. ``` Offer to apply the recommended variant directly to their SKILL.md if they share the full file. --- ## Output Format ``` ## Description Analysis: [skill name] **Current score: X/15** [One-sentence diagnosis] --- ### Variant A — Comprehensive [score X/15] [description text] ### Variant B — Tight [score X/15] [description text] ### Variant C — Discovery-optimized [score X/15] [description text] --- ### Score Comparison [table] ### Recommendation Use Variant [X]. [One-sentence reason.] ``` --- ## Anti-Patterns - Never write a variant under 30 words — it will not trigger - Never write all three variants with the same opening line - Never score a variant higher than the current description unless it genuinely improves a dimension - Never recommend a variant without explaining why in one sentence - Never leave the user with three equal options and no recommendation --- ## Test Cases **Test 1 — Classic weak description** Input: `description: "A skill for helping with code reviews."` Expected: Current score 3–5/15. Three meaningfully different variants, all scoring 10+. Variant B recommended (focused, single-purpose skill). **Test 2 — Already-strong description** Input: A 90-word description with action verb, 4 trigger phrases, explicit I/O Expected: Current score 12–14/15. Variants offered as experiments. User told current version is shippable. **Test 3 — No trigger phrases** Input: A 60-word description that describes the skill well but has no "when user says X" clause Expected: Trigger phrase dimension scores 1. All three variants add explicit trigger phrases. Score improves by at least 4 points across all variants.