> ## 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.

# selftune eval

> Create portable evals and run evidence-backed skill comparisons.

## Run output-quality evaluations

```bash theme={null}
selftune eval run --skill-path /path/to/my-skill
```

| Flag                         | Purpose                                                      |
| ---------------------------- | ------------------------------------------------------------ |
| `--evals PATH`               | Override `evals/evals.json`                                  |
| `--workspace PATH`           | Override the sibling iteration workspace                     |
| `--baseline-skill-path PATH` | Compare with a previous skill instead of no skill            |
| `--feedback PATH`            | Copy an existing human-feedback JSON file into the iteration |
| `--agent NAME`               | Use `claude`, `codex`, `opencode`, or `pi`                   |
| `--model MODEL`              | Override the model used for execution and grading            |
| `--json`                     | Print the benchmark result as JSON                           |

The command creates a new numbered iteration and never overwrites a prior run.
See [Portable evaluations](/concepts/evals) for the artifact layout and review
rules.

## Generate routing cases

```bash theme={null}
selftune eval generate --skill my-skill --skill-path /path/to/my-skill
```

Add `--auto-synthetic` for a cold-start skill or `--blend` to combine observed
evidence with synthetic gap cases. When `--skill-path` is present, SelfTune
writes the portable package copy under `evals/` and keeps a compatibility mirror
for existing local workflows.

| Flag                          | Purpose                                                    |
| ----------------------------- | ---------------------------------------------------------- |
| `--skill NAME`                | Select a skill; omit only with `--list-skills`             |
| `--list-skills`               | List skills and their trusted-evidence readiness           |
| `--stats`                     | Show aggregate telemetry statistics for the selected skill |
| `--max N`                     | Limit generated entries per side                           |
| `--seed N`                    | Set the deterministic shuffle seed                         |
| `--output PATH`, `--out PATH` | Write an additional eval-set copy                          |
| `--no-negatives`              | Exclude negative routing examples                          |
| `--no-taxonomy`               | Skip invocation-type classification                        |
| `--skill-log PATH`            | Override the skill-usage log                               |
| `--query-log PATH`            | Override the query log                                     |
| `--telemetry-log PATH`        | Override the session telemetry log                         |
| `--agent NAME`                | Select the agent used for synthetic generation             |
| `--synthetic`                 | Generate cases from `SKILL.md` without logs                |
| `--auto-synthetic`            | Use synthetic cases when trusted triggers are unavailable  |
| `--blend`                     | Combine observed and synthetic cases                       |
| `--skill-path PATH`           | Select the skill package used by synthetic generation      |
| `--model MODEL`               | Override the generation model                              |
| `--help`                      | Show the current command help                              |

## Run mechanical assertions

```bash theme={null}
selftune eval unit-test --skill my-skill --skill-path /path/to/my-skill
```

Use `--generate` to draft assertions and `--run-agent` when the test requires a
live agent transcript.

## Analysis commands

```bash theme={null}
selftune eval composability --skill my-skill
selftune eval family-overlap --skills skill-a,skill-b
selftune eval import --dir /path/to/corpus --skill my-skill
```

Run `selftune eval <subcommand> --help` for the current strict flag surface.