SKILL+ Improve

Use this skill when a Skill already exists and the user wants to know whether it is well composed, whether agents can use it effectively, and how to evolve it without making it worse.

This skill combines static audit, live behavior validation, validation-gated editing, and human adoption checkpoints.

Inputs

Collect or infer:

• Path or content of the existing skill folder.
• Target harnesses: Codex, Hermes, Claude Code, OpenCode, or custom.
• Existing evals, test prompts, traces, benchmark results, user complaints, or failure logs.
• Desired improvement goal: routing, structure, behavior, outcome, safety, portability, or maintainability.
• Risk level: file mutation, external send, deployment, permissions, privacy, finance, legal, or irreversible actions.

If the user only asks "is this skill good?", run audit and produce an improvement plan before editing.

Workflow

1. Snapshot And Protect

Before editing:

• Confirm the skill path and whether it is inside a git repo.
• Inspect SKILL.md, resources, examples, scripts, and evals.
• Preserve existing user changes.
• For git repos, prefer branch/commit-based tracking.
• Do not use destructive rollback such as git reset --hard.

If no version control exists, make a timestamped file backup before edits.

2. Static Audit

Score the skill across:

| Area | Purpose | |---|---| | Routing | Agent can discover the skill from description. | | Contract | Goal, inputs, outputs, verification, boundaries, and handoff are explicit. | | Runtime Boundary | Long knowledge is progressively loaded from resources. | | Reusability | No hidden local coupling, stale paths, or overlapping scope. | | Safety | High-risk actions have gates, blacklists, and human approval. | | Signal Density | No filler, generic model-known advice, or bloated examples. | | Self-Consistency | Description, body, resources, examples, and scripts agree. |

Cap the score at 60 for critical failures:

• Missing or non-functional description.
• Hardcoded secrets.
• Destructive action without approval boundary.
• Persona override unrelated to task.
• SKILL.md so large that routing and contract are buried.
• Output contract contradicts workflow or resources.

3. Runtime And Behavior Audit

Check whether the skill changes agent behavior:

• Does the target harness discover it?
• Does the agent read it when the task should trigger it?
• Does it add specific tool order, checks, fallback, or evidence behavior?
• Does it avoid known failures?
• Does it preserve existing successful behaviors?

For Codex, check .agents/skills/<skill>/SKILL.md discovery. For Hermes or custom harnesses, identify the skill discovery and injection contract before scoring runtime behavior.

4. Build Or Select Evaluation Tasks

Use the strongest available evaluation:

text
no-skill baseline
old-skill baseline
candidate-skill run
held-out test run
human review for high-risk or subjective tasks

If no benchmark exists, create 2 to 3 test prompts from real usage, but mark the run as dry_run. A skill cannot be called production-ready from dry-run evidence alone.

5. Choose The Improvement Mode

Pick one mode:

| Mode | Use when | |---|---| | repair | The skill has broken routing, missing contract, bad links, unsafe instructions, or stale paths. | | edit | The skill is mostly right but needs a targeted behavior, failure, or runtime boundary improvement. | | split | The skill has multiple unrelated load triggers or bloated scope. | | merge | Multiple skills overlap and confuse routing. | | deprecate | The skill is stale, unsafe, unused, or superseded. |

Do not change multiple independent dimensions in one optimization round unless the user explicitly asks for a broad refactor.

6. Generate Candidate Edit

Use bounded edits:

• Add, delete, replace, or move specific sections.
• Preserve proven useful guidance.
• Keep the edit small enough to attribute outcome change.
• Put long details into references/, examples/, scripts/, or evals/.
• Record why the edit should improve behavior.

For repeated failures, encode them as:

text
If <symptom>, first <repair>. If still failing, <fallback or handoff>.

7. Validate With A Gate

Use SkillOpt-style strict validation:

text
candidate_score = select_metric(hard, soft, mixed)

accept if candidate_score > current_score
reject otherwise

new best if candidate_score > best_score

Use:

• hard for deterministic exact checks.
• soft for partial-credit tasks.
• mixed for office workflows with both hard artifacts and quality judgment.

Rejected edits are evidence. Save why they failed so the next round does not repeat them.

8. Apply Darwin-Style Ratchet

Each round must end in one of:

| Status | Meaning | |---|---| | keep | Evidence improved and no critical regression appeared. | | revert | Candidate failed gate or introduced unacceptable regression. | | hold | Evidence is mixed or insufficient; do not publish. | | stop | Marginal gain is too small, risk is too high, or human rejects. |

Use independent review when possible. The same context that made an edit should not be the only judge of that edit.

Human checkpoint is mandatory when:

• The edit changes safety gates, permissions, external send behavior, destructive actions, or release status.
• The validation is subjective.
• The improvement is based only on LLM judge output.
• The dry-run ratio is high.

9. Report

Return:

text
improvement-report.md
schema-audit.md
eval-report.json or eval-summary.md
recommended-patches.json when not editing directly
updated SKILL.md when safe to edit
CHANGELOG entry when publishing

The report must include:

• Before score and after score.
• Changed files.
• Gate decision: keep, revert, hold, or stop.
• Evidence used: static audit, routing test, behavior test, outcome test, human review.
• Rejected edits or remaining risks.
• Next recommended round.

Verification

Before finishing:

• Re-run static audit after edits.
• Check that the description still matches the body.
• Check resource links and load conditions.
• Confirm no secrets, local-only paths, or unsafe actions were introduced.
• Confirm evaluation evidence is labeled as full test, selection run, dry run, or human-only review.
• If a change is kept, record why it is better than the previous skill.

Boundaries

• Do not call a skill improved because it reads better. Require behavior or outcome evidence when possible.
• Do not rely on the same agent context for both editing and final scoring.
• Do not use git reset --hard as routine rollback.
• Do not optimize for rubric points by adding bloat.
• Do not publish a high-risk skill without human review.
• Do not delete major content, weaken safety gates, or change external-send behavior without explicit user confirmation.

Runtime Resources

Load references/source-mechanics.md when you need exact mechanics from SkillOpt, darwin-skill, Skill-Schema-V2, Trace2Skill, EvoSkill, and SkillLens.