Skills Improve

Assess against the improvement dimensions in this skill's criteria.md (same folder). For each dimension, generate specific, actionable suggestions tied to what you actually read — not generic advice. Reference specific steps or sections.

3. Present suggestions

If AskUserQuestion is available, use it with multiSelect: true. Otherwise, present suggestions conversationally and let the user respond in plain language.

• Number each suggestion.
• For each: what to change, why it matters, which file(s) it touches.
• Group by dimension.

The user may select improvements, ask follow-up questions, or add their own ideas. If the user selects none, skip to Phase 3 (Optimize).

Phase 2 — Implement

4. Preview

For each selected improvement, show what will change:

• Which file(s) will be modified or created.
• A plain-language summary of the change.

Proceed only after the user confirms.

5. Backup

Before modifying files, create a timestamped backup:

• Create {skill_folder}/.backups/{filesystem-safe-timestamp}/ (use an ISO-8601 timestamp with : replaced by .).
• Record a list of the files that exist before changes (exclude .backups/) so rollback can remove newly created files.
• Copy all files that will change into the backup folder.

6. Apply selected improvements

• Preserve existing structure and voice.
• If an improvement requires a new file (e.g. extracting criteria into criteria.md), create it.
• Update last-updated in SKILL.md frontmatter to current UTC timestamp (ISO-8601).

7. Verify

Check that the modified skill is still well-formed:

• SKILL.md frontmatter is valid YAML.
• All files that existed before still exist.
• No broken references to other files or skills.

8. Rollback if needed

If verification fails:

• Restore all files from the backup created in step 5.
• Delete any newly created files that were not present in the pre-change file list (excluding .backups/ itself).
• Inform the user: "The improvements didn't apply cleanly. I've restored the skill to its previous state."
• Skip to step 13 (Summary) to report what went wrong. Do not run /skills-review in this case.

Phase 3 — Optimize

9. Optimize for conciseness

Re-read the improved skill. Assess against the optimization checklist in this skill's criteria.md.

10. Present optimization proposals

Show the user what you would tighten, with before/after for significant changes.

Ask for confirmation. If declined, skip to Phase 4.

11. Apply optimizations

Apply confirmed optimizations. Update last-updated.

Phase 4 — Review

12. Run skills-review

Invoke /skills-review on the improved skill.

13. Summary

Report:

• What was improved and why.
• Approximate token count change (if optimization was applied).
• Any review findings that need attention.