Running and Monitoring

Start a run

fastskill optimize run --config optimize.toml

FastSkill validates your config, creates a timestamped run directory under out_dir, and begins the training loop. When the run finishes, it prints the path to the best skill document:

Run complete. Best skill: .skillopt/runs/2026-06-03T14-22-01Z/best_skill.md

Override the output directory

fastskill optimize run --config optimize.toml --out-dir /tmp/my-runs

This overrides the out_dir value in the config without modifying the file.

Resume an interrupted run in one step

If you interrupted a run (Ctrl-C, timeout, machine restart), you can resume it directly from the run command:

fastskill optimize run --config optimize.toml --resume .skillopt/runs/2026-06-03T14-22-01Z

This delegates to the resume subcommand — it re-reads the stored config from the run directory and picks up where it left off.

Watch progress with `status`

In a second terminal, run:

fastskill optimize status .skillopt/runs/2026-06-03T14-22-01Z

This prints the current best score, epoch/step position, and a per-step table:

Run: .skillopt/runs/2026-06-03T14-22-01Z
Best score: 0.82  |  Epoch 2/5  |  Global step 14

Step  Gate      Score(S)  Score(S')  Delta    Tokens
1     accepted   0.60       0.67     +0.07    4,210
2     rejected   0.67       0.61     -0.06    3,890
3     accepted   0.67       0.74     +0.07    4,102
...

Column meanings:

Column	Description
`Step`	Global step index (1-based across all epochs).
`Gate`	Whether the patch was accepted or rejected.
`Score(S)`	Score before the patch.
`Score(S')`	Score after the patch.
`Delta`	`Score(S') - Score(S)`. Positive means improvement.
`Tokens`	Tokens consumed in this step (target + optimizer calls).

Live watch mode

fastskill optimize status .skillopt/runs/2026-06-03T14-22-01Z --watch

Re-reads and re-prints every ~2 seconds until the run completes.

Resume an interrupted run

fastskill optimize resume .skillopt/runs/2026-06-03T14-22-01Z

The resume subcommand reads the stored optimize.toml copy from the run directory (saved at run-start for provenance; legacy run directories from before the rename may instead contain skillopt.toml, which is still read for backward compatibility), re-validates it against the current files, and calls the training loop at the last checkpoint. Note: Resume uses the config stored inside the run directory, not your original config file. This ensures the run is reproducible regardless of changes you may have made to the config since starting.

Typical workflow

# 1. Start the run
fastskill optimize run --config optimize.toml

# 2. In a second terminal, watch progress
fastskill optimize status .skillopt/runs/<timestamp> --watch

# 3. If interrupted, resume
fastskill optimize resume .skillopt/runs/<timestamp>

# 4. When done, inspect a specific step (optional)
fastskill optimize inspect .skillopt/runs/<timestamp> --step 7

# 5. Export the best skill
fastskill optimize export .skillopt/runs/<timestamp> --out skills/my-skill/SKILL.md

Run directory layout

Every run creates a self-contained directory:

.skillopt/runs/2026-06-03T14-22-01Z/
├── optimize.toml          # stored config (provenance copy)
├── runtime_state.json     # live state: best_score, epoch, global_step
├── history.json           # array of step records
├── best_skill.md          # best skill document seen so far
├── step-1/
│   ├── patch.json         # proposed patch
│   ├── gate_scores.json   # before/after scores for gate decision
│   ├── skips.json         # cases skipped this step
│   ├── skill_before.md    # skill before this step's patch
│   └── skill_after.md     # skill after this step's patch
├── step-2/
│   └── ...
└── ...

The run directory is safe to copy, archive, or share. Resume and inspect commands only need this directory.

Getting Started

Configuration

Skill Management

Evals & Quality

Skill Optimization

CLI Reference

Registry

Advanced Topics

Integration

Running and Monitoring

Running and Monitoring

Start a run

Override the output directory

Resume an interrupted run in one step

Watch progress with `status`

Live watch mode

Resume an interrupted run

Typical workflow

Run directory layout

See also

​Running and Monitoring

​Start a run

​Override the output directory

​Resume an interrupted run in one step

​Watch progress with status

​Live watch mode

​Resume an interrupted run

​Typical workflow

​Run directory layout

​See also

Running and Monitoring

Start a run

Override the output directory

Resume an interrupted run in one step

Watch progress with `status`

Live watch mode

Resume an interrupted run

Typical workflow

Run directory layout

See also