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.

The durable executor is an optional first-hop skill powered by Rote. It exists so tool-backed work — CLI commands, API calls, browser sessions, shell scripts, local processes — leaves durable evidence instead of disappearing into chat scrollback. When a task is recurrence-likely, the executor routes it through a named Rote workspace, captures execution evidence, and provides a path to synthesize that observed work into a reusable SkillSpec-backed skill.
The durable executor is entirely optional. Doctor risk reports, import, workspace flow, and router mode all work without it. Install it only when you want the Rote workspace capture and synthesis path.

​
What it does

The durable executor acts as a meta-router for tool-backed requests. When activated, it:
  1. Routes recurrence-likely tasks through a named Rote workspace, keeping command logs, artifacts, and token stats as workspace records rather than transient stdout
  2. Hands off domain work to the matching installed SkillSpec skill while preserving the durable packet (workspace, trace_dir, return_to, execution_policy)
  3. Falls back to capability seeds when no reviewed domain skill owns the requested capability, querying ~/.skillspec/capabilities/ through the capability CLI before touching any raw local tool
  4. Returns for durable closure — token stats, alignment, and evidence summary — after domain work completes
  5. Offers synthesis of the observed workspace into a draft skill.spec.yml scaffold via skillspec synthesize-from-workspace
The executor is provider-neutral. It does not hardcode adapters, browser systems, shell runners, or vendor substrates — those belong to selected domain skills and capability seeds.

​
Install the durable executor

The install command requires an explicit local source folder and preflights that rote is available on PATH before writing any files: 
skillspec durable-executor install examples/durable-executor \
  --target agents \
  --json
Valid --target values are agents, codex, and claude-local. Use --all-detected to install into every detected harness root in one pass. Use --dry-run to see what would be written without making changes. After install, SkillSpec records the source folder and every managed install directory under ~/.skillspec/durable-executor/config.json and writes a managed marker into each installed folder. If router mode is configured and enabled, router-managed visibility and the skill index are refreshed automatically. 
# Install from an explicit local source folder
skillspec durable-executor install examples/durable-executor \
  --target agents --dry-run --json

# Update all recorded managed installs (backs up before rewriting)
skillspec durable-executor update --json

# Disable (makes recorded installs explicit-only, does not remove files)
skillspec durable-executor disable --json

# Re-enable (re-checks rote on PATH, makes installs implicit again)
skillspec durable-executor enable --json

# Delete only recorded marker-protected installs
skillspec durable-executor delete --json
disable is a switch, not an uninstall. It keeps all recorded installs but sets them to explicit-only across Codex and Claude visibility metadata so they no longer compete for implicit selection. enable reverses this and checks that rote is still available on PATH.

​
Synthesize a skill from a workspace

After durable work completes in a named Rote workspace and you have approved the observed result, skillspec synthesize-from-workspace creates a draft skill.spec.yml scaffold from the workspace evidence: 
skillspec synthesize-from-workspace profile-enrichment \
  --task 'use parallel web to enrich this profile' \
  --out ./draft-profile-skill \
  --observation-approved
The --observation-approved flag is a required safety gate. The command refuses to write any files until the observed result and evidence summary have been shown and approved. This prevents synthesis from running on incomplete or unapproved traces. If live Rote workspace lookup is unreliable, you can supply evidence files directly: 
skillspec synthesize-from-workspace profile-enrichment \
  --task 'use parallel web to enrich this profile' \
  --out ./draft-profile-skill \
  --workspace-stats-report ./workspace-stats.json \
  --workspace-log ./workspace-log.jsonl \
  --workspace-meta ./workspace-meta.json \
  --observation-approved
The resulting draft scaffold marks inferred behavior for review and still requires validation, scenario tests, dependency review, and proof before it is ready to install.

​
Capability seeds

When no reviewed domain SkillSpec owns a requested capability, the executor queries the local capability seed store at ~/.skillspec/capabilities/ before touching any raw local tool.

Add a seed

skillspec capability add preferred-voice-cli \
  --domain voice \
  --kind cli \
  --provides text_to_speech \
  --command say

Search seeds

skillspec capability search text_to_speech \
  --domain voice \
  --explain \
  --json

List seeds by domain

skillspec capability list --domain voice

Inspect a seed

skillspec capability inspect preferred-voice-cli \
  --domain voice \
  --json
Seeds are not SkillSpecs and are not handoff targets. The executor searches, inspects, and verifies a seed before relying on it. If the first search returns no candidates, it broadens to related capability and domain terms before falling back to an unseeded local tool — and that fallback requires an explicit user ask or a created-and-verified seed first. To update an existing seed’s ranking or mark it as failed: 
skillspec capability update preferred-voice-cli \
  --domain voice \
  --priority 70 \
  --add-provides speech_synthesis

​
Rote requirement

The durable executor requires a Rote binary on PATH. Every install, update, and enable command preflights rote availability before writing files or changing visibility. If rote is not installed, the preflight reports exactly what is missing. Rote provides workspace initialization (rote init), process capture (rote exec --), stream follow, background process leasing, token stats (rote workspace stats), dependency tracing (rote trace --deps), and TypeScript flow replay (rote deno run). Download and configure Rote at modiqo.ai.

​
The plan-act-progress loop

Once inside a durable workspace, the executor coordinates a structured plan-act-progress loop using SkillSpec runtime commands: 
# Start a guided run against the durable executor spec
skillspec run-loop examples/durable-executor/skill.spec.yml \
  --input 'check gh status and remember the result' \
  --guide agent --json

# Read the current phase checklist
skillspec run checklist .skillspec/traces/run-123 --stage loop --json

# Record a progress checkpoint with evidence
skillspec progress checkpoint .skillspec/traces/run-123 \
  --requirement-satisfied durable_closure/compute_workspace_stats=command:workspace-stats.json \
  --quiet

# Align the trace against the spec for proof
skillspec trace align examples/durable-executor/skill.spec.yml \
  --decision-trace .skillspec/traces/run-123 \
  --execution-trace .skillspec/traces/run-123/execution.jsonl \
  --proof-digest .skillspec/traces/run-123/proof-digest.json \
  --quiet
The progress checkpoint and trace align commands keep the execution ledger in execution.jsonl. Token stats are recorded with skillspec progress stats: 
skillspec progress stats .skillspec/traces/run-123 \
  --workspace profile-enrichment \
  --workspace-stats-report ./workspace-stats.json \
  --phase durable_closure \
  --requirement compute_workspace_stats \
  --quiet

​
The durable executor skill.spec.yml structure

The installed skill contract (examples/durable-executor/skill.spec.yml) declares routes for the most common durable patterns: 
schema: skillspec/v0
id: durable.executor
title: durable executor

activation:
  summary: Universal first-hop for any tool-backed request that may execute,
    inspect, mutate, automate, browse, call, fetch, generate, install,
    test, run, or create artifacts through CLI, shell, API, adapter,
    browser, provider, local process, or external tool.
  priority: meta_router

routes:
  - id: durable_domain_handoff
    label: Hand off domain work and return for durable closure
    rank: 1
  - id: capability_bootstrap
    label: Bootstrap capability when no domain SkillSpec exists
    rank: 2
  - id: shell_then_browser_handoff
    label: Run shell evidence, then hand off browser work
    rank: 3
  - id: adapter_first_cli_fallback
    label: Use rote adapters, then rote exec CLI fallback
    rank: 4
  - id: one_shot_process
    label: Capture a one-shot process
    rank: 10
  # ... additional routes for stream follow, background process,
  # PTY transcript, dependency preflight, crystallized flow
The durable_memory_tasks_start_at_meta_router rule governs which requests enter the durable path. When the user says phrases like “remember this”, “future recall”, “reusable”, or “preserve evidence”, the rule matches via user_says_any and prefers the durable_domain_handoff route. The spec forbids direct CLI calls without rote exec, untracked stdout as proof, and final responses without workspace evidence and token math — all enforced by skillspec trace align at closure time.

Build docs developers (and LLMs) love

Get started for freeTalk to us