skill-optimization

Skill Optimization

Audit and refactor library components (rules, skills, traits) to eliminate redundancy, verbosity, and stale instructions.

When to Use

Cross-component audit — dedup, staleness, and token-budget trimming across the whole rule/skill/trait library. Authoring or validating a single skill's structure is skill-template, not this. And the upstream act of turning a retro finding into a new framework component is retro-to-framework; this skill optimises what already exists.

Procedure

1. Audit: Review <ai_hats_dir>/sessions/retros/ for recurring issues. List all active rules and skills in the current role composition.

2. Identify Debt:

   • Redundancy: two components covering the same behavior
   • Stale instructions: references to removed tools, obsolete workflows
   • Verbosity: rules that can be condensed without losing meaning
   • Misplaced content: rule that should be a skill (has a procedure), or skill that should be a rule (is just a constraint)
   • Prohibition-led wording, and unowned silences — both are debt here, and skill-template's validation checklist is where they are stated as authoring rules; audit against it, so the two do not drift apart

3. Refactor:

   • Merge fragmented rules into existing traits or skills
   • Condense verbose content into declarative checklists
   • Delete deprecated items
   • Move misplaced content to the right component type

4. Validate:

   • Run composer.compose() for affected roles — 0 errors
   • Run test suite — all green
   • Spot-check assembled prompt — no regressions

Completion

• Audit report produced with identified debt
• Refactoring applied and validated (0 errors, tests green)
• Token impact measured before/after

Anti-Patterns

• Refactoring without measuring token impact — optimization must be quantified
• Deleting components without checking wiring — verify every trait/role still resolves
• Cosmetic changes disguised as optimization — focus on real redundancy and staleness