| name | skill-description-optimizer |
| description | Rewrite a skill's description field to fix routing problems — undertriggering, overtriggering, or passive language that fails to match user intent. Use when a skill isn't being found by agents, evaluation shows low trigger recall, or batch-auditing descriptions for a library release. Do not use when the skill's scope is the problem (not just description text) or when the description is already performing correctly. |
| license | Apache-2.0 |
| compatibility | {"clients":["openai-codex","gemini-cli","opencode","github-copilot"]} |
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
