skillspec decide — Evaluate routing rules for a user task

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

Flag	Type	Default	Description
`<path>`	path	(required)	Path to a `skill.spec.yml` file.
`--input`	string	(required)	User task text to route. Strip skill invocation prefixes before passing it. Hyphenated values are accepted.
`--trace-dir`	directory 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" }
    ]
  }
}

Field	Description
`input`	The exact task string passed to the decision engine.
`route`	The id of the selected route, or `null` if no route matched.
`route_selection`	How the route was chosen: `basis` is `rule_prefer`, `route_order_default`, or `default_route_order`; `rule_id` identifies the winning rule when applicable.
`route_order`	Ordered list of route ids evaluated during selection.
`matched_rules`	List of rule ids that fired against the input, each with an optional `reason`.
`forbid`	Substitution ids that are forbidden for the selected route.
`allow`	Map of explicitly allowed substitutions and their parameters.
`elicit`	Elicitation ids that must be answered before the route proceeds.
`after_success`	Closure ids that are scheduled to run after the route succeeds.
`execution_plan.phases`	Ordered list of execution phase stubs. Expand with `act` to get full phase detail.
`reason`	Optional 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.

Runtime Commands

Authoring Commands

Installation & Discovery

skillspec decide — Evaluate routing rules for a user task

Synopsis

Options

Examples

Output

​Synopsis

​Options

​Examples

​Output

​Related

Synopsis

Options

Examples

Output

Related