Skills Optimization Pro

Problem to Solve

As Agent Skills accumulate, common failures are not only bad wording. Missing frontmatter fields, over-broad triggers, vague steps, absent exception paths, broken references, and version mismatches with CHANGELOG can make skills undiscoverable, unstable, or hard to maintain. These issues are scattered across formatting, prompt structure, dependency declarations, and validation, making manual review expensive and lacking a shared scoring or rollback baseline.

How It Works

The skill runs a diagnose → route → optimize → validate → record loop. L1 fixes frontmatter and formatting; L2 applies pattern matching, scoring, and edits to one skill; L3 can scan many skills and produce a comparison report. Diagnosis classifies the skill type and selects patterns such as Tool Wrapper, Generator, Reviewer, Inversion, or Pipeline, then scans anti-patterns AP-2 through AP-13, including Vague Instruction, Missing Fallback, Zombie Reference, and Silent Failure.

Before and after changes, it runs Trigger Test, Understanding Test, Execution Test, and Regression Test, and requires version updates, CHANGELOG entries, and results.tsv records. Constraints include preserving core functionality, avoiding new dependencies, changing one dimension per round, keeping SKILL.md under 150% of its original size, and maintaining rollback through backups and git revert. It is better understood as an evaluation and rewriting workflow for skill repositories rather than a business-logic generator.

Fit and Limits

It is useful for governing prompt quality, format consistency, dependency declarations, and validation records in existing Skills. It is not intended to create the core capability of a new skill, nor to batch-modify environments without backups, user confirmation, or CHANGELOG support. If a skill’s functional definition is unclear, clarify the business objective before entering this workflow.