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 decide evaluates the routing rules declared in a skill.spec.yml against a user task string and returns the full decision as JSON. It is the canonical way to determine which route a task should follow, which rules fired, what substitutions are forbidden, what elicitations are required, and what after-success closures were scheduled. Run decide before act when you want the raw routing decision without the full OODA action checklist, or use it in scripts that need to branch on a selected route. If you want a human-readable explanation of the same decision, use skillspec explain instead. Strip skill invocation prefixes from the user task before passing it as --input. The decision engine matches against the raw task intent, not the invocation form.

​
Synopsis

skillspec decide <path> --input <text> [--trace-dir <dir>]

​
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. Creates a new timestamped run subdirectory containing events/, trace.jsonl, and summary.json.

​
Examples

Evaluate a task without recording a trace: 
skillspec decide ./skill.spec.yml --input 'install this skill'
Record a decision trace for later alignment: 
skillspec decide ./skill.spec.yml \
  --input 'port this skill' \
  --trace-dir .skillspec/traces
Pass a task with hyphens in the text: 
skillspec decide ./skill.spec.yml \
  --input 'run end-to-end tests for the api module' \
  --trace-dir .skillspec/traces

​
Output

decide always emits JSON. The top-level fields mirror the internal Decision struct: 
{
  "input": "port this skill",
  "route": "port_skill",
  "route_selection": {
    "route": "port_skill",
    "basis": "rule_prefer",
    "rule_id": "porting_tasks_use_port_route",
    "reason": "task matches porting pattern"
  },
  "matched_rules": [
    { "id": "porting_tasks_use_port_route", "reason": "task matches porting pattern" }
  ],
  "forbid": ["direct_cli_without_rote_exec"],
  "elicit": ["approve_scope"],
  "after_success": ["trace_align"],
  "execution_plan": {
    "phases": [
      { "id": "setup", "owner_skill": "port-skill" },
      { "id": "qa_and_proof", "owner_skill": "port-skill" }
    ]
  }
}
FieldDescription
inputThe exact task string passed to the decision engine.
routeThe id of the selected route, or null if no route matched.
route_selectionHow the route was chosen: basis is rule_prefer, route_order_default, or default_route_order; rule_id identifies the winning rule when applicable.
route_orderOrdered list of route ids evaluated during selection.
matched_rulesList of rule ids that fired against the input, each with an optional reason.
forbidSubstitution ids that are forbidden for the selected route.
allowMap of explicitly allowed substitutions and their parameters.
elicitElicitation ids that must be answered before the route proceeds.
after_successClosure ids that are scheduled to run after the route succeeds.
execution_plan.phasesOrdered list of execution phase stubs. Expand with act to get full phase detail.
reasonOptional human-readable explanation for the routing outcome.
When --trace-dir is supplied, the command also prints the path of the written trace run directory before the JSON output.
  • skillspec explain <path> --input <text> — same decision in human-readable prose; useful for debugging rule logic.
  • skillspec act <path> --input <text> — expands the decision into a full OODA action checklist.
  • skillspec plan <path> --input <text> — lists the execution phases in order without the full action checklist.

Build docs developers (and LLMs) love

Get started for freeTalk to us