skill-optimizer

Audits and rewrites skill frontmatter to improve router invocation rates.

1|Updated Jul 2, 2026
One-click install
npx skills add https://github.com/mccleod1290/bb-agentic-setupv2 --skill skill-optimizer-mccleod1290
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: skill-optimizer
Source: https://github.com/mccleod1290/bb-agentic-setupv2/tree/main/web-skills/skill-optimizer
Command: npx skills add https://github.com/mccleod1290/bb-agentic-setupv2 --skill skill-optimizer-mccleod1290

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Skills often fail to trigger because the router never sees their full description, the name uses camelCase or a cursed token, or the when-to-use text misses the phrasings users actually type. This Skill measures and fixes that routing surface so skills get invoked when they should. ## Core Features & Use Cases - Mechanical fixes: Converts descriptions to folded >- blocks, enforces word-separated hyphen-case names, and strips the claude token from names. - Eval-driven measurement: Generates should-trigger and should-not-trigger query sets, then measures invocation and false-positive rates with an isolated router agent. - Rewrite and verify loop: Rewrites name, description, and when-to-use for trigger coverage, re-measures, and reports before/after rates with a rename impact check. - Use Case: A skill fires only 10% of the time it should. Run the optimizer to apply mechanical fixes, generate evals, rewrite the frontmatter, and verify the invocation rate climbs toward the 80% target. ## Quick Start Optimize the skill at web-skills/my-skill so the router invokes it reliably, and report the before and after invocation rates.

Frequently Asked Questions about skill-optimizer

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I fix a skill that is not triggering?▼

Check the frontmatter first: ensure the description uses a folded `>-` block so the router sees every line, the name is hyphen-case without camelCase, and the name contains no `claude` token. Then write should-trigger evals and rewrite the description to cover the phrasings users actually type.

How do I measure a skill's invocation rate?▼

Generate 10-15 should-trigger queries and 5-10 should-not-trigger queries, then dispatch them to an isolated router agent with the target frontmatter plus confusable distractor skills. Invocation rate is should-trigger queries that picked the target divided by total should-trigger queries.

Why does a multi-line YAML description break skill routing?▼

A bare unquoted multi-line YAML value collapses, so the router often sees only the first line and the rest is invisible to routing. Use the folded block scalar `>-` so every line of the description is parsed and available for routing decisions.

Can I rename a skill safely?▼

Yes, but run a rename impact check first: rename the folder to match the name field, then grep the repo for the old name and update references in agent configs, other skills' boundary clauses, and docs. Flag any reference you cannot update safely.

What are the limitations of router-agent invocation measurement?▼

The router agent is a model-as-router simulation, not a byte-for-byte replica of the real harness routing. Treat measured rates as a strong relative before/after signal rather than an absolute guarantee of production invocation behavior.