description-optimizer

---
name: description-optimizer
description: >
  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.
---

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