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.
Usage
selftune verify --skill-path <path> [options]
selftune publish --skill-path <path> [options]
selftune create status --skill-path <path> [options]
selftune create init --name <name> --description <text> [options]
selftune create scaffold --from-workflow <id|index> [options]
selftune create check --skill-path <path> [options]
selftune create replay --skill-path <path> [options]
selftune create baseline --skill-path <path> [options]
selftune create report --skill-path <path> [options]
selftune create publish --skill-path <path> [options]
init creates a blank draft package. scaffold creates the same package shape
from a discovered multi-skill workflow in SQLite telemetry. check runs spec
validation plus selftune’s package-readiness checks to tell you the next
draft-lifecycle step. replay, baseline, report, and publish complete the
package validation and handoff path. create report renders the same measured
package evaluator used by publish as one benchmark-style artifact. create publish re-runs package replay and package baseline before it hands the draft
into watch, rather than jumping straight into description-only evolve.
If you want the smaller lifecycle surface, use selftune verify as the
trust-building front door and selftune publish as the shipping front door.
verify runs the same readiness contract as create check, then emits the
benchmark-style report once the draft is ready. publish delegates to
create publish and starts watch by default unless you pass --no-watch.
create subcommand flags
The low-level create surfaces keep their full expert flag set even when you
mostly use the smaller verify / publish lifecycle commands.
| Flag | Used by | Meaning |
|---|
--name | create init | Display name for the new draft package |
--description | create init, create scaffold | Routing description for the draft package |
--output-dir | create init, create scaffold | Parent directory for the new package |
--force | create init, create scaffold | Overwrite scaffold files if the directory already exists |
--from-workflow | create scaffold | Workflow ID or list index to scaffold from |
--skill-name | create scaffold | Override the generated scaffolded skill name |
--write | create scaffold | Persist the scaffold instead of previewing it |
--min-occurrences | create scaffold | Minimum workflow frequency when resolving the selection |
--skill | create scaffold | Restrict workflow discovery to chains containing the named skill |
--skill-path | create status/check/replay/baseline/report/publish, verify, publish | Path to a skill directory or SKILL.md |
--mode | create replay, create baseline | Routing-only or full-package evaluation mode |
--agent | create replay, create baseline, create report, verify | Runtime agent used for evaluation |
--eval-set | create replay, create baseline, create report, verify | Override the canonical eval-set path |
--watch | create publish | Start watch immediately after publish succeeds |
--no-watch | publish | Skip the default watch handoff and return the next watch command instead |
--ignore-watch-alerts | create publish, publish | Bypass the publish-time watch gate after review |
--json | most subcommands | Emit structured JSON output |
--help | all subcommands | Show command help |
selftune verify lifecycle
selftune verify runs through the following steps:
- Run the same draft-package readiness checks as
selftune create check
- Auto-generate missing evidence (evals, unit tests, replay, baseline) unless
--no-auto-fix
- If the draft is ready, run the benchmark-style package report
- Recommend
selftune publish when verification passes
Auto-fix behavior
By default, verify attempts to repair a failing readiness check automatically
before reporting failure. When a check identifies a gap — missing evals, unit
tests, routing replay data, or a baseline — verify runs the appropriate
sub-command on your behalf and re-evaluates readiness. It will attempt up to
four sequential fixes before stopping.
This means running verify on a fresh draft will often produce a passing result
in a single command rather than requiring you to manually run each remediation
step in sequence.
To skip automatic evidence generation and receive the raw readiness result, pass
--no-auto-fix:
selftune verify --skill-path ./my-skill --no-auto-fix
--no-auto-fix when:
- You want to inspect exactly what is missing before generating anything
- You are running
verify in CI and prefer explicit control over each step
- A previous auto-fix attempt produced unexpected output that you want to review
verify flags
| Flag | Default | Description |
|---|
--skill-path <path> | — | Path to the draft skill package (required) |
--agent <agent> | — | Override the agent used for evaluation |
--eval-set <path> | — | Override the eval-set path instead of using the canonical one |
--no-auto-fix | off | Skip automatic evidence generation when readiness checks fail |
--json | off | Emit machine-readable JSON output |
--help | off | Show command help |
Watch gate
When create publish starts watch, it evaluates the resulting watch signal
through a watch gate. If the gate fails, publish is blocked: the skill is
not written to the registry and published is returned as false.
The JSON result includes:
| Field | Type | Meaning |
|---|
watch_gate_blocked | boolean | true when the watch gate prevented publication |
published | boolean | false whenever watch_gate_blocked is true |
next_command | string | Remediation command to run — points to selftune watch when blocked |
watch_gate_passed | boolean | Whether the gate passed |
watch_trust_score | number | Trust score derived from the latest watch signal |
Watch gate blocked publish: yes
Recovering from a blocked publish
Run the next_command returned in the result — it will be a selftune watch
invocation for the skill. Once watch accumulates enough passing signal to
satisfy the gate, re-run create publish.
# Gate blocked — run the remediation command from next_command
selftune watch --skill my-skill --skill-path ./my-skill
# Then retry publish
selftune create publish --skill-path ./my-skill
--ignore-watch-alerts.
