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

# Skill improve skill for AI agents

> Upgrade an underperforming Summer skill — run it against a behavioral spec with and without changes via a parallel-eval harness; ship the winner. A Summer Engine skill for AI agents.

`skill-improve` is a skill from the [Summer skill library](/mcp/skills): a guide your AI agent reads when the task matches, so it builds the good version on the first try. Upgrade an underperforming Summer skill — run it against a behavioral spec with and without changes via a parallel-eval harness; ship the winner.

| | |
| - | - |
| Status | Stable |
| Domains | Agent workflow, Meta |
| Version | `1.0.3` |
| Engine version | `>=4.6` |
| Recommended set | No, installed by `--all` or by name |

## When your agent uses it

* A contributor wants to upgrade a Summer skill that is underperforming or to fix a regression
* Comparing a skill with and without a change against a behavioral spec before shipping the winner

## Install

`summer setup` installs every skill for your agent. To add only this one:

```bash theme={null}
npx -y summer-engine@latest skills install skill-improve --agent claude-code
```

Swap `claude-code` for your agent, such as `codex` or `cursor`. See [Skills](/mcp/skills#quick-start) for every option.

## The skill

Adapted from the `skill-creator` skill in `anthropics/skills`. Use when a skill's behavioral spec fails assertions or the skill produces low-quality output.

## When to use this vs. `/skill-test`

* `/skill-test spec` reasons over text. Cheap and fast, but lossy.
* `/skill-improve` runs the skill in parallel subagents, with and without the proposed changes. Slower and more expensive, but accurate.

Run this when `/skill-test spec` flags issues you can't fix by reading the skill alone.

## Steps

### 1. Pick the skill + the spec

Ask the user:

* **Skill slug.** Resolves to `library/skills/<slug>/SKILL.md`.
* **Test cases to focus on.** Default: all `## Case` blocks in `evals/skills/specs/<slug>.md`.

### 2. Establish a baseline

For each Case:

1. Spawn a subagent (`Task` tool, `general-purpose`) with the **current** skill body in context.
2. Give it the Case's Input + Fixture.
3. Capture the tool calls it makes and the diff it produces.
4. Score against the Case's Assertions.

Save outputs to `tests/runs/<skill-name>/baseline/case-<N>/`.

### 3. Propose changes

Read the failing Cases. Identify the gap between what the skill says and what the agent did. Common gaps:

* Skill names a tool but the agent picked a different one (clarify the trigger).
* Skill assumes a fixture detail the agent missed (add explicit step to confirm).
* Skill's "May I" wording is too generic for the agent to infer the right ask.

Draft a revised SKILL.md. May I write it to `tests/runs/<skill-name>/proposed/SKILL.md`?

### 4. Run the proposed version

Repeat step 2 with the proposed SKILL.md. Save to `tests/runs/<skill-name>/proposed/case-<N>/`.

### 5. Compare and decide

For each Case, score:

* Assertions passed (proposed vs. baseline).
* Tool-call efficiency (fewer tools = better, all else equal).
* Hallucination / unwanted ops (penalize).

Output:

```
Case 1 (Happy):     baseline 4/6  proposed 6/6  yes ship proposed
Case 2 (Failure):   baseline 3/4  proposed 4/4  yes ship proposed
Case 3 (Edge):      baseline 3/3  proposed 3/3  = no change
```

If proposed wins on net, prompt the user:

> Proposed version wins 2 cases, ties 1, loses 0. May I overwrite `library/skills/<slug>/SKILL.md` with the proposed version?

### 6. Ship

On user yes:

* Overwrite `SKILL.md` and bump `version` in `resource.yaml`.
* Commit with message `feat(skill): improve <name> — <one-line summary of change>`.

## Collaborative protocol

This skill writes files at multiple steps. Always ask before each write.

## See also

* `skill-test`
* `tests/runner.md`
* `evals/skills/specs/`

## Related skills

* [`skill-test`](/skills/skill-test): Lint a Summer skill before commit, audit the whole library, or check a behavioral spec assertion — static structural rules plus behavioral specs.

***

Source: [`library/skills/skill-improve/SKILL.md`](https://github.com/SummerEngine/summer/blob/main/library/skills/skill-improve/SKILL.md), rendered from `summer-engine@4.3.0` on npm.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.