skill-improve

# Skill Improve Runs an improvement loop on a single skill: test → fix → retest → keep or revert. --- ## Phase 1: Parse Argument Read the skill name from the first argument. If missing, ask the user with a concise plain-text choice list instead of failing: ``` Which skill should I improve? [A] I'll provide a skill name [B] Stop here Example: $skill-improve tech-debt ``` Stop after asking. Do not continue until the user answers. Verify `.agents/skills/[name]/SKILL.md` exists. If not, stop with: "Skill '[name]' not found." --- ## Phase 2: Baseline Test Run `$skill-test static [name]` and record the baseline score: - Count of FAILs - Count of WARNs - Which specific checks failed (Check 1–7) Display to the user: ``` Static baseline: [N] failures, [M] warnings Failing: Check 4 (no ask-before-write), Check 5 (no handoff) ``` If baseline is 0 FAILs and 0 WARNs, note it and proceed to Phase 2b. ### Phase 2b: Category Baseline Look up the skill's `category:` field in `Codex Skill Testing Framework/catalog.yaml`. If no `category:` field is found, display: "Category: not yet assigned — skipping category checks." and skip to Phase 3. If category is found, run `$skill-test category [name]` and record the category baseline: - Count of FAILs - Count of WARNs - Which specific category rubric metrics failed Display to the user: ``` Category baseline: [N] failures, [M] warnings ([category] rubric) ``` If BOTH static and category baselines are 0 FAILs and 0 WARNs, stop: "This skill already passes all static and category checks. No improvements needed." --- ## Phase 3: Diagnose Read the full skill file at `.agents/skills/[name]/SKILL.md`. For each failing or warning **static** check, identify the exact gap: - **Check 1 fail** → which frontmatter field is missing - **Check 2 fail** → how many phases found vs. minimum required - **Check 3 fail** → no verdict keywords anywhere in the skill body - **Check 4 fail** → missing `agents/openai.yaml` metadata or one of the required keys - **Check 5 warn** → no ask-before-write language for a skill that edits files - **Check 6 warn** → no follow-up or next-step section at the end - **Check 7 fail/warn** → stale Codex wording (old skill paths, pseudo-tool references, or obsolete tool names) For each failing or warning **category** check (if category was assigned in Phase 2b), identify the exact gap in the skill's text. For example: - If G2 fails (gate mode, full directors not spawned): skill body never references all 4 PHASE-GATE director prompts - If A2 fails (authoring, no per-section May-I-write): skill asks once at the end, not before each section write - If T3 fails (team, BLOCKED not surfaced): skill doesn't halt dependent work on blocked agent Show the full combined diagnosis to the user before proposing any changes. --- ## Phase 4: Propose Fix Write a targeted fix for each failure and warning. Show the proposed changes as clearly marked before/after blocks. Only change what is failing — do not rewrite sections that are passing. Ask: "May I write this improved version to `.agents/skills/[name]/SKILL.md`?" If the user says no, stop here. --- ## Phase 5: Write and Retest Record the current content of the skill file (for revert if needed). Write the improved skill to `.agents/skills/[name]/SKILL.md`. Re-run `$skill-test static [name]` and record the new static score. If a category was assigned, also re-run `$skill-test category [name]` and record the new category score. Display the comparison: ``` Static: Before [N] failures, [M] warnings → After [N'] failures, [M'] warnings Category: Before [N] failures, [M] warnings → After [N'] failures, [M'] warnings (if applicable) Combined change: improved / no change / worse ``` --- ## Phase 6: Verdict Count the combined failure total: static FAILs + category FAILs + static WARNs + category WARNs. **If combined score improved (combined failure count is lower than baseline):** Report: "Score improved. Changes kept." Show a summary of what was fixed in each dimension. **If combined score is the same or worse:** Report: "Combined score did not improve." Show what changed and why it may not have helped. Ask: "May I revert `.agents/skills/[name]/SKILL.md` to HEAD?" If yes: restore the pre-edit snapshot you saved at the start of Phase 5 using `apply_patch`. Do not use destructive git checkout commands. --- ## Phase 7: Next Steps - Run `$skill-test static all` to find the next skill with failures. - Run `$skill-improve [next-name]` to continue the loop on another skill. - Run `$skill-test audit` to see overall coverage progress.