| name | skill-improve |
| version | 0.1.0 |
| description | One-pass improvement workflow for an existing SKILL.md. Use when the user asks
to improve, tighten, repair, simplify, deconflict, or upgrade a skill without
running a full SkillOpt training session. Applies SkillOpt lessons such as
evidence-first review, failure/success separation, bounded edits, validation,
and rejected-change notes. Trigger here for "improve this SKILL.md in one
bounded pass", "tighten the trigger text and output format for this skill",
"repair this skill after a failed plugin-health check, but keep the edit
small", or "make this skill better using SkillOpt lessons but do not create
train selection or test splits". This does not create train/selection/test
splits or run an offline optimization loop; use skillopt-training-run for
repeated rollouts and held-out gates, and plugin-health for audit-only checks.
|
| triggers | ["improve this skill","skill-improve","tighten this skill","repair this skill","upgrade this skill","make this skill better"] |
| allowed-tools | ["Read","Write","Edit","Bash","Grep","Glob"] |
| mutating | true |
| writes_pages | false |
| writes_to | ["plugins/",".plugin-manager/skill-improve/"] |
| disable-model-invocation | false |
Skill Improve
Contract
Use this for a focused, single-pass skill upgrade. It borrows SkillOpt's
discipline without running SkillOpt: gather evidence, separate failures from
working behavior, make a small bounded patch, validate it, and record what was
changed or deliberately rejected.
Use the smallest adequate validation surface. This skill should improve the
target skill and stop; it should not become a plugin release, upstream harvest,
or full optimization run unless evidence shows the request belongs there.
Escalate to ../skillopt-training-run/SKILL.md only when the user wants a full
training loop, repeated rollouts, train/selection/test splits, model or harness
comparison, slow/meta updates, or best-skill export.
Workflow
-
Preflight
- Run
git status --short --branch.
- Identify the target
SKILL.md, plugin, docs surface, and ownership
boundary.
- Read the target skill, plugin README, nearby skills, and any relevant tests,
routing fixtures, or plugin-health output.
- Preserve unrelated user edits.
-
Evidence scan
- Look for concrete signals: user complaint, stale docs, failed validation,
confusing trigger text, missing output contract, unsafe write scope,
duplicated instructions, vague advice, missing anti-patterns, or examples
of successful use worth preserving.
- Check whether the skill has routing fixtures. If absent or stale, treat
missing coverage as evidence when routing is part of the change.
- If no concrete evidence exists, do a design review against local skill
conventions and label the result as judgment-based.
-
Failure and success reflection
- Failure side: identify recurring or high-impact gaps the skill should
prevent.
- Success side: identify behavior already working that should remain intact.
- Prefer general rules over example-specific patches.
- Do not add content already covered by the skill.
-
Bounded patch
- Apply the smallest useful edit set; default to 1 to 4 focused changes.
- Prefer localized add, replace, or delete edits over full rewrites.
- Keep the skill concise and under the repo's existing style.
- Add or update
routing-eval.jsonl only when trigger behavior or routing
boundaries change.
- Do not add new scripts, references, or agents unless deterministic behavior
or progressive disclosure clearly needs them.
-
Validation
- Run
python3 "${CLAUDE_PLUGIN_ROOT}/skills/plugin-health/scripts/plugin_audit.py" --plugin <plugin-name> --json.
- Run
npm run render:check and npm run validate when the improvement
changes shared plugin metadata, generated manifests, or marketplace
surfaces.
- Run
claude plugin validate plugins/<plugin-name> when available.
- Run focused tests for any scripts or fixtures touched.
- If validation is unavailable, state exactly what was not run.
-
Receipt
- For non-trivial improvements, write a short receipt under
.plugin-manager/skill-improve/YYYY-MM-DD-HHMM-<skill>.md with evidence,
changes, validation, and rejected ideas.
- Skip the receipt for tiny typo-only or docs-only fixes unless the user asks
for an audit trail.
Output Format
SKILL IMPROVE
Target: plugins/<plugin>/skills/<skill>/SKILL.md
Mode: one-pass
Evidence:
- <signals used>
Changes:
- <bounded edit summary>
Validation:
- <command>: pass|fail|not-run
Rejected:
- <idea intentionally not applied or none>
Receipt: <path or skipped>
Anti-Patterns
- Turning a one-pass improvement request into a full training run.
- Rewriting the whole skill because a bounded patch would work.
- Optimizing around one anecdote without saying the evidence is thin.
- Adding verbose background that belongs in a reference file or nowhere.
- Removing successful behavior while fixing a failure.
- Changing trigger/routing behavior without updating routing evidence.
- Claiming improvement without running available validation.
