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 act runs the SkillSpec decision engine on a task, then expands the result into a complete OODA action checklist covering the current execution phase. The checklist includes matched rules, allowed actions, forbidden substitutions, required transitions, phase handoffs, and the effective phase tool boundary — everything an agent needs to choose its next action without guessing. Use act at the start of execution and again before each phase transition. If you need to inspect the phase sequence first without the full checklist, run skillspec plan and then call act --phase <id> for each phase in turn.

​
Synopsis

skillspec act <path> --input <text> \
  [--trace-dir <dir>] \
  [--run <run-dir>] \
  [--phase <id>] \
  [--json]
--trace-dir and --run are mutually exclusive: use --trace-dir when no trace run exists yet, and --run to associate the checklist with an existing run directory.

​
Options

FlagTypeDefaultDescription
<path>path(required)Path to a skill.spec.yml file.
--inputstring(required)User task text to route. Strip skill invocation prefixes before passing it. Hyphenated values are accepted.
--trace-dirdirectory path(none)Directory where append-only decision trace event files should be written. Conflicts with --run.
--rundirectory path(none)Existing trace run directory to associate with this action checklist instead of writing a new trace. Conflicts with --trace-dir.
--phasestring(none)Expand this execution phase by id instead of the first pending phase. Use after plan to target a specific phase.
--jsonflagoffEmit JSON instead of a concise human report.

​
Examples

Basic checklist for the first pending phase: 
skillspec act ./skill.spec.yml --input 'port this skill'
Write a new trace and get the checklist in one command: 
skillspec act ./skill.spec.yml \
  --input 'port this skill' \
  --trace-dir .skillspec/traces
Associate with an existing run directory (common after run-loop or decide): 
skillspec act ./skill.spec.yml \
  --input 'port this skill' \
  --run .skillspec/traces/run-1712345678-12345
Target a specific phase by id: 
skillspec act ./skill.spec.yml \
  --input 'port this skill' \
  --run .skillspec/traces/run-1712345678-12345 \
  --phase qa_and_proof

​
Output

Without --json, act prints a formatted OODA checklist. With --json it emits a structured ActReport: 
{
  "input": "port this skill",
  "selected_route": "port_skill",
  "route_selection": {
    "route": "port_skill",
    "basis": "rule_prefer",
    "rule_id": "porting_tasks_use_port_route"
  },
  "matched_rules": [
    { "id": "porting_tasks_use_port_route", "reason": "task matches porting pattern" }
  ],
  "current_phase": {
    "id": "setup",
    "owner_skill": "port-skill",
    "requires": ["validate_source"],
    "checks": ["source_shape_ok"],
    "forbid": [],
    "handoff": null,
    "jumps": [],
    "tool_boundary": null
  },
  "phases": [...],
  "forbidden": ["direct_cli_without_rote_exec"],
  "elicitations": ["approve_scope"],
  "after_success": ["trace_align"],
  "allowed_now": [
    "execute current phase `setup` requirements before later phases",
    "satisfy phase requirements: validate_source"
  ],
  "required_transitions": [
    "complete phase `setup` before starting phase `qa_and_proof`"
  ],
  "before_tool_call": [...],
  "ooda_loop": [...],
  "tool_boundary": {
    "default": "deny",
    "allow": ["skillspec_cli", "current_phase_owner_skill", "..."],
    "forbid": ["direct_cli_without_rote_exec"],
    "permission_required_for": ["any_unlisted_tool", "any_forbidden_action", "..."],
    "instruction": "Use only the allowed tools and substrates for this phase...",
    "sources": ["runtime_default"]
  },
  "authority": "The selected route and matched rules override lower-level skill defaults and generic tool preferences.",
  "trace": {
    "run_id": "run-1712345678-12345",
    "run_dir": ".skillspec/traces/run-1712345678-12345",
    "trace_jsonl": ".skillspec/traces/run-1712345678-12345/trace.jsonl",
    "summary_json": ".skillspec/traces/run-1712345678-12345/summary.json"
  }
}
FieldDescription
current_phaseThe phase being expanded — the first pending phase or the one targeted by --phase.
phasesFull list of all execution phases in order with their requirements, checks, forbids, handoffs, and jumps.
forbiddenCombined forbid set: route-level forbids + current phase forbids + handoff forbids.
allowed_nowConcrete list of actions allowed in the current phase.
required_transitionsPhase ordering constraints and handoff requirements that must be respected.
before_tool_callChecklist items to verify before every tool call during this phase.
ooda_loopFour-step Observe-Orient-Decide-Act instructions for each iteration.
tool_boundaryEffective phase tool boundary merged from entry.tool_boundary, route, and phase declarations. default is deny unless overridden.
tracePaths to the associated trace run when --trace-dir or --run was supplied.
  • skillspec plan <path> --input <text> — list phases in order before deciding which one to expand.
  • skillspec decide <path> --input <text> — raw decision output without the OODA checklist.
  • skillspec run-loop — batches sensemake, decide, plan, and act in a single spec load.

Build docs developers (and LLMs) love

Get started for freeTalk to us