Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/modiqo/skillspec/llms.txt

Use this file to discover all available pages before exploring further.

skillspec run-loop batches sensemake, decide, plan, and act into a single spec load. Instead of calling each command separately — which each parses and validates the spec independently — run-loop reads the file once and returns all four artifacts in one structured report. This is the preferred entry point for guided agent runs. Use it with --guide agent --json to start a stateful run that writes guide-state.json and guide-summary.md, and emits machine-readable --- START ---, --- CURRENT ---, and --- END --- anchors so the agent can compact the context and resume without re-reading a human checklist parade. Use --resume <run-dir> to continue an existing guided run. The command reads the run directory’s guide-state.json, determines the current phase and open requirements, and emits an updated checklist from that state.

​
Synopsis

skillspec run-loop <path> \
  [--input <text> | --resume <run-dir>] \
  [--guide agent|full] \
  [--view index|summary|full] \
  [--trace-dir <dir>] \
  [--phase <id>] \
  [--json]
--input and --resume are mutually exclusive.

​
Options

FlagTypeDefaultDescription
<path>path(required)Path to a skill.spec.yml file.
--inputstring(none)User task text to route. Strip skill invocation prefixes. Conflicts with --resume.
--resumedirectory path(none)Existing guided run directory. Reads guide-state.json and continues the run from its current state. Conflicts with --input.
--guideagent | full(none)Emit a stateful agent guide. agent writes guide-state.json and guide-summary.md and prints start/current/end anchors. full emits additional narrative content for human review.
--viewindex | summary | fullindexSensemake detail level included in the batch report.
--trace-dirdirectory path(none)Directory where append-only decision trace event files should be written.
--phasestring(none)Expand this execution phase instead of the first pending phase.
--jsonflagoffEmit JSON instead of a compact human report.

​
Examples

Start a new guided run and write machine-readable anchors: 
skillspec run-loop ./skill.spec.yml \
  --input 'port this skill' \
  --trace-dir .skillspec/traces \
  --guide agent \
  --json
Resume an existing guided run from its directory: 
skillspec run-loop ./skill.spec.yml \
  --resume .skillspec/traces/run-1712345678-12345 \
  --guide agent \
  --json
Non-guided batch report for scripting — summary view, no anchors: 
skillspec run-loop ./skill.spec.yml \
  --input 'port this skill' \
  --view summary \
  --json
Target a specific phase when the current phase is already known: 
skillspec run-loop ./skill.spec.yml \
  --input 'port this skill' \
  --phase qa_and_proof \
  --guide agent \
  --json

​
Output

Without --guide, run-loop emits a RunLoopReport containing sensemake, decision, act, and an optional trace block. The batched_commands field lists which commands were combined: ["sensemake", "decide", "plan", "act"]. With --guide agent --json, the output also includes the guide report and the command writes two files in the run directory:
  • guide-state.json — machine-readable current state: spec id, run id, current phase, open requirements, allowed commands, forbids, repeat-until condition, and exit proof commands. The agent reads this file to resume without context loss.
  • guide-summary.md — human-readable summary of the same state, suitable for run summaries and issue comments.
The anchors printed to stdout wrap the guide output so the agent can locate the boundaries for compaction-safe resume: 
--- START ---
<guide output>
--- CURRENT ---
<current phase checklist>
--- END ---
The --- END --- anchor in a proof-bearing run includes the quiet token-stats, final-response, and alignment commands the agent should run before closing the run.

​
Guide State and Resume

When --guide agent is active, every invocation updates guide-state.json in the trace run directory. The state records:
  • The spec id and current spec fingerprint
  • The run id and run directory path
  • The selected route and matched rules
  • The current phase and open requirements
  • The allowed commands for the current gate
  • The forbid set
  • The repeat-until condition for the loop
  • The exit proof commands (quiet trace align, compact, etc.)
To resume, pass the same spec path and the run directory with --resume: 
skillspec run-loop ./skill.spec.yml \
  --resume .skillspec/traces/run-1712345678-12345 \
  --guide agent \
  --json
The command reads guide-state.json, re-evaluates the current phase against the execution ledger, and emits a fresh checklist anchored to the current state.
  • skillspec run checklist <skill.spec.yml-or-run-dir> --stage entry|loop|exit --json — generate a concrete execution checklist from a spec file or an existing guided run directory. For run directories, reads guide-state.json and emits the current phase, open requirements, allowed commands, forbids, repeat-until condition, and exit proof commands. Read-only; exits non-zero when guide state is missing or exit is requested before remaining phases are complete.
  • skillspec act — expand a single phase without batching.
  • skillspec progress show — inspect phase and requirement progress for an existing run.

Build docs developers (and LLMs) love

Get started for freeTalk to us