chelch5/skill-description-optimizer

Skill Description Optimizer

The description field is routing logic — it determines when hosts invoke the skill. Bad descriptions cause undertriggering (skill never fires) or overtriggering (fires for wrong tasks).

Procedure

1. Read current description

Assess:

• Length: Too short (< 20 words) → likely undertrigger. Too long (> 100 words) → likely diluted.
• Style: Capability statement ("This skill can...") vs trigger statement ("Use when...")
• Discriminating power: Could this description match 5 other skills? If yes, it's too broad.

2. Identify failure mode

| Mode | Symptoms | Cause | |------|----------|-------| | Undertrigger | Skill never fires for intended tasks | Description too narrow, technical, or missing user vocabulary | | Overtrigger | Fires for unrelated tasks | Description too broad, overlaps siblings, no DO NOT USE boundary | | Passive | Inconsistent triggering | Describes what skill is, not when to invoke it |

3. Extract discriminating signals

What words predict THIS skill and not siblings?

• Specific task verbs (scaffold, audit, deprecate, package)
• Domain terms (ticket, manifest, overlay)
• Explicit names the user would say

4. Write optimized description

Structure (40-70 words):

• Sentence 1: Action verb + most discriminating signal (lead with what the skill does)
• Sentence 2: Context or problem it solves
• Sentence 3: "Use when [specific trigger condition]"
• Sentence 4: "Do not use [explicit boundary]"

Anti-patterns to avoid:

• "This skill helps with..." (passive)
• "A comprehensive tool for..." (marketing copy)
• "Use this when creating, adapting, refining, installing, testing, or packaging..." (kitchen-sink — matches everything)

5. Check sibling conflicts

Read 2-3 similar skill descriptions. Does the new description discriminate correctly? Add a distinguishing clause if needed.

6. Validate with test prompts

| Prompt | Type | Should Match? | |--------|------|---------------| | "[specific task in scope]" | positive | YES | | "[specific task in scope]" | positive | YES | | "[task for a sibling skill]" | negative | NO | | "[task for a sibling skill]" | negative | NO |

Output contract

## Description Optimization: [skill-name]

### Failure Mode
[Undertrigger | Overtrigger | Passive]

### Before
"[original description]"

### After
"[optimized description]"

### Discrimination Check
| Similar Skill | Differentiated By |
|---------------|-------------------|
| [sibling] | [distinguishing signal] |

### Test Prompts
| Prompt | Expected | Matches? |
|--------|----------|----------|

Failure handling

• Scope ambiguity at procedure level: Description can't fix this — recommend scope narrowing or skill splitting
• No discriminating signals: Skill may be too generic — narrow scope first
• Can't test routing: Create synthetic test prompts based on intended use