> ## Documentation Index
> Fetch the complete documentation index at: https://docs.selftune.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Improve a skill

> Turn real usage evidence into a bounded skill change that you can review and verify.

Improve a skill when SelfTune has evidence of a specific problem, such as
missed activation, weak instructions, or a regression. Start with a preview and
keep the change only when its validation is stronger than the current version.

## Ask your agent

```text theme={null}
Use SelfTune to inspect <skill-name> and tell me whether it has enough evidence
for an improvement. If it does, prepare the smallest relevant change in preview
mode, show me the evidence and diff, and explain how you will verify it. Do not
write, publish, upload, or enable automatic rollback until I approve the plan.
```

## What should happen

<Steps>
  <Step title="Confirm the target and evidence">
    The agent resolves the source `SKILL.md`, checks health and recent evidence,
    and stops if the data does not support a specific change.
  </Step>

  <Step title="Preview a bounded change">
    The default manual preview is:

    ```bash theme={null}
    selftune improve --skill-path /path/to/skill --dry-run
    ```

    Select a narrower scope only when the evidence identifies that surface.
  </Step>

  <Step title="Review the proposal">
    Review the source evidence, changed files, behavioral claim, validation
    method, and recovery plan. A larger diff is not evidence of a better skill.
  </Step>

  <Step title="Apply and verify">
    After approval, let the agent apply the proposed change and repeat the same
    evaluation against the previous version. Keep a backup or version-control
    diff until post-change evidence is available.
  </Step>
</Steps>

## Success criteria

* The proposal addresses an observed problem, not a speculative rewrite.
* Unrelated skill surfaces and files remain unchanged.
* The comparison uses the same evaluation conditions for both versions.
* The agent reports ambiguous or negative results instead of selecting a winner.
* You can identify and restore the previous version.

<Warning>
  Do not use a higher score from a different test set, agent, or model as proof
  of improvement. Change one side of the comparison at a time.
</Warning>

Resolve the canonical skill source before evaluating. Inspect evidence
read-only, state whether it is sufficient, and use dry-run or proposal mode
first. Report the mutation surface, files, evidence, comparison method, and
rollback path. Stop for approval before writing the skill, publishing,
uploading, or enabling autonomous operation. If the candidate does not beat the
accepted version under comparable conditions, recommend no change.