Skill Description Optimizer

The Problem

You published a skill on Agensi. It's installed 12 times. It's triggered exactly once. You ask the agent to use your skill and it picks a different one instead — or no skill at all. The problem is your description: "Provides utilities for code analysis and improvement tasks." That's a 512-token description that tells the agent what the skill is instead of when to use it. The retrieval surface — the first 40-90 characters of your description — contains filler words and self-referential phrasing instead of task-specific trigger keywords. Meanwhile, a competing skill with a terse, trigger-first description ("Use when reviewing SQL queries for injection, performance, or N+1 problems") activates every time because its first 90 characters are dense with matching tokens.

What You Get

• inspect command that parses SKILL.md frontmatter, estimates token usage against soft (250) and hard (512) budgets, and reports specific trigger-quality issues: missing WHEN-first wording, filler words, topic-shaped vs. trigger-shaped descriptions, and frontmatter structure problems
• optimize command that rewrites the description into WHEN-first trigger form ("Use when you need to [action]") while preserving the original wording and entire body text — no information loss, just restructured for retrieval
• evaluate command that scores a set of should-trigger and should-not-trigger phrases against the description using Jaccard token overlap plus verbatim-phrase bonuses, producing a JSON report proving (not guessing) that positive cases outscore near-miss negatives
• Overlap detection across your skill catalogue — identifies descriptions that are >60% token-identical and blur each other's activation space, with guidance on differentiating by naming concrete tasks and output artifacts
• Preflight proxy scoring using deterministic lexical heuristics (no API keys, no vendor dependencies) — designed as a fast check before real harness testing, not a replacement for it
• Stdlib-only CLI — runs anywhere Python runs, no PyYAML dependency, never executes dynamic code, and only writes to files you explicitly name with -o

Why This Beats Prompting It Yourself

When you try to rewrite your skill description by hand, you're guessing. You add more keywords hoping to cast a wider net, but you dilute the trigger signal. You write "comprehensive" and "powerful" and "all-in-one" because they sound good to humans — but the retrieval matcher cares about token overlap with the user's task description, not adjectives. This skill gives you a measurement loop: inspect → optimize → evaluate → verify. You can prove that your rewritten description out-scores the old one on real trigger phrases before shipping. No other tool provides this kind of evidence-based description QA.

Example Session

You: "My SQL query reviewer skill never triggers. Here's the description: 'Provides comprehensive database analysis and SQL optimization utilities.'"

Agent output:

{
  "inspect": {
    "description_est_tokens": 142,
    "token_budget_soft": 250,
    "desc_within_soft": true,
    "trigger_issues": [
      "R1.3: Description is topic-shaped, not trigger-shaped",
      "R1.4: No trigger keywords matching user task phrasing"
    ]
  },
  "optimize": {
    "new_description": "Use when you need to review SQL queries for injection, N+1 patterns, missing indexes, or ORM-generated SQL performance issues. Provides comprehensive database analysis and SQL optimization utilities.",
    "body_preserved": true
  },
  "evaluate": {
    "results": [
      {"phrase": "optimize a slow sql query", "score": 0.61, "label": "should-trigger"},
      {"phrase": "review a pull request for security", "score": 0.22, "label": "should-not-trigger"},
      {"phrase": "plan a vacation itinerary", "score": 0.04, "label": "should-not-trigger"}
    ],
    "summary": {"positive_cases_outscore_negatives": true}
  }
}

Use Cases

• Debugging why an installed skill never activates in Claude Code, Codex CLI, or Cursor
• Writing the frontmatter description for a new skill before publishing to any marketplace
• Auditing a skill catalogue of 10+ skills for uniform trigger quality and token budget compliance
• After AI-generated SKILL.md creation — AI-written descriptions tend to be topic-shaped rather than trigger-shaped
• Quality assurance for marketplace submissions that enforce description standards

Known Limitations

The evaluate scoring uses lexical overlap heuristics (Jaccard + verbatim bonus) as a preflight proxy — it cannot see inside any specific agent's embedding model or classifier. Always validate the final skill in your target harness before shipping. The optimizer only modifies the frontmatter description field; it does not rewrite the skill body. Description drift can occur after batch edits — rerun inspect across the full catalogue after any catalog-wide pass to ensure sibling skills don't blur each other's trigger space.