When a SkillSpec-backed skill runs, the result is not only a final response — it is a record you can inspect. The CLI writes an append-only decision trace as the rule engine evaluates your contract, and the runtime writes an execution ledger as phases progress and evidence is captured. After the run,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 trace align compares both artifacts against the contract and produces a structured alignment report with a three-valued verdict: aligned, partial, or unproven.
The third verdict — unproven — is the methodological core. Binary pass/fail forces an evaluator to treat missing evidence as either success or failure. The convention that the absence of an error means success is exactly what hides dropped steps. SkillSpec reports unproven when the trace lacks the evidence to decide, rather than inferring success from silence.
Decision trace
When you runskillspec decide with --trace-dir, the CLI creates a run directory:
Trace event kinds
The trace vocabulary is a closed set. An event either appears in the trace or it does not — absence is informative.| Event | Written when |
|---|---|
input_received | The user input is captured before rule evaluation |
spec_loaded | The spec is loaded; records skill_id and schema |
rule_evaluated | Each rule is checked; records rule_id and matched: true/false |
rule_matched | A rule matched; records rule_id and reason |
route_selected | A route is set; records route, basis, rule_id, and reason |
route_order_set | A rule replaced the route ordering |
forbid_added | A rule added forbidden substitutions |
allow_added | A rule granted explicit permissions |
elicitation_requested | A rule appended a clarifying question |
after_success_scheduled | A rule scheduled post-task closures |
outcome_recorded | The final decision: route, route_selection, and matched_rules |
route_selected event carries a basis field that explains why the route was chosen:
rule_prefer— a matched rule’spreferfield set itroute_order_default— a rule changed route order and the first in that order wondefault_route_order— no rule acted; the first ranked route was used
Execution ledger
The execution ledger lives alongside the decision trace:| Event | Records |
|---|---|
phase_started | Phase id, owner skill, timestamp |
requirement_satisfied | Phase id, requirement id, evidence kind and reference |
requirement_failed | Phase id, requirement id, failure evidence |
evidence_attached | Artifact or response reference captured during the phase |
stats_collected | Workspace/token metrics snapshot |
adapter_discovery_finished | Adapter health/probe results |
cli_readiness_check_finished | CLI preflight result |
process_started | Process launch, executor (rote_exec vs. direct), workspace |
final_response_sent | Whether the response included result, evidence, alignment, and token-savings sections |
unproven rate in an alignment report often signals that the harness is not writing structured events, not that the skill is broken.
Alignment
skillspec trace align compares the decision trace and execution ledger against the contract:
- Re-runs the spec on the captured input to produce an expected decision
- Checks that the trace records the same route, matched rules, forbids, elicitations, and after-success closures
- Derives execution obligations from the selected route and matched rules
- Checks the ledger for structured evidence that each obligation was satisfied
- Writes
alignment.jsonand a proof digest to the run directory
Alignment properties
The aligner produces one of three verdicts per check and an aggregate per run:aligned
The trace contains evidence that the expectation held. The decision was reproduced and execution obligations have structured proof.
partial
Some expectations met, at least one obligation unproven or violated. The run partially aligns — report the concrete missing-proof rows.
unproven
The trace lacks the events needed to decide. This is not failure — it means the harness didn’t record enough structure, or execution wasn’t traced.
- Decision replay — did re-running the spec on the captured input produce the same route, rules, forbids, and elicitations?
- Execution proof — does the ledger prove the route was fulfilled, forbids were not violated, elicitations were answered, and after-success closures ran?
Trace event JSON example
Aroute_selected event in trace.jsonl:
requirement_satisfied event in execution.jsonl:
Trace spec section
Thetrace section of a skill.spec.yml declares which events the evaluator should persist. Setting required: true tells a conforming harness it must either write the trace or state that tracing is unavailable before relying on the decision.
record is empty or absent, an evaluator may record every v0 event kind. The spec does not contain per-rule file-writing instructions — it declares intent, and the evaluator acts on it.