Skip to content

skill-description-optimizer

Pack: companion

skill-description-optimizer

Purpose

Improve a skill's frontmatter description so matching is more precise, more reliable, and easier to debug.

Trigger phrases

Use this skill when the request includes ideas like:

  • "optimize description"
  • "improve trigger"
  • "fix skill description"
  • "description too broad"
  • "skill not triggering"

Core workflow

  1. Read the target skill's SKILL.md and extract the frontmatter description.
  2. Analyze description quality:
  3. length check: too short means under-specified; too long means unfocused
  4. trigger phrase density: does it contain actionable trigger words?
  5. specificity score: how precisely does it define when to activate?
  6. overlap analysis: compare against sibling skills to find trigger collisions
  7. boundary check: does it say what it does not handle?
  8. Generate optimization suggestions:
  9. add missing trigger phrases
  10. remove overly broad language
  11. sharpen activation boundary
  12. reduce overlap with siblings
  13. Output an analysis report plus a suggested new description.

How to execute

Primary command:

uv run .opencode/skills/skill-description-optimizer/scripts/optimize_description.py --path <skill-dir> --suggest --verbose

For sibling overlap analysis:

uv run .opencode/skills/skill-description-optimizer/scripts/optimize_description.py --path <skill-dir> --siblings <skills-dir> --suggest

Machine-readable output:

uv run .opencode/skills/skill-description-optimizer/scripts/optimize_description.py --path <skill-dir> --siblings <skills-dir> --json

Output format

Always report:

  • target skill name
  • current description
  • length assessment
  • trigger phrase findings
  • specificity score (0-100)
  • boundary check result
  • sibling overlap findings when available
  • concrete rewrite suggestions
  • suggested replacement description when requested

Must do

  • Read the actual target SKILL.md before making any recommendation.
  • Focus on description quality, trigger precision, and activation boundaries.
  • Compare against siblings when a sibling directory is available.
  • Explain why the current description underperforms.
  • Keep suggested descriptions concise, explicit, and trigger-oriented.

Must not do

  • Do not rewrite unrelated parts of the skill.
  • Do not modify skill files directly; this skill analyzes and suggests only.
  • Do not recommend vague catch-all wording such as "help with skills".
  • Do not ignore overlap risk when multiple sibling skills compete for similar requests.

... (5 more lines in full SKILL.md)