Skip to content

SKILL.md

Latest commit

 

History

History
202 lines (144 loc) · 7.02 KB

SKILL.md

File metadata and controls

202 lines (144 loc) · 7.02 KB
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:

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.