Compile

Compile a skill

You orchestrate the rote CLI. It runs an LLM compiler agent over a source skill and emits a deterministic pipeline. Your job: resolve the inputs, run the CLI, then interpret the output for the user. You never classify nodes or write pipeline.yaml yourself — the CLI's agent does.

1. Identify the source skill

The source is a directory containing a SKILL.md (optionally a references/ folder). The user names it, or you infer it from context (a skill just discussed, a path in the conversation, .claude/skills/* or skills/* in the project).

Confirm the resolved absolute path with the user before running. Compilation costs real time and tokens; never guess-and-go. If the directory has no SKILL.md, stop and ask.

2. Pick a runtime target

Ask the user which runtime, with these tradeoffs (one line each):

If the user has no opinion and no existing infra, use dbos — it is the CLI's default and the only target with zero standing infrastructure (you can omit --runtime entirely in that case).

3. Resolve the CLI (uv)

The CLI ships on PyPI as the rote-cli package and is run via uvx — no virtualenv, no pip, nothing to install beyond uv itself. The package's executable is named rote, so every invocation is uvx --from rote-cli rote <args>. Do not run uvx rote-cli ... — uvx looks for an executable named after the package and the published wheel doesn't ship one.

1. Check uv: uv --version. If missing, tell the user to install it with one command, then re-check:

   curl -LsSf https://astral.sh/uv/install.sh | sh
   

2. Confirm the CLI resolves:

   uvx --from rote-cli rote --version
   

3. Only if the user needs unreleased features (or PyPI is unreachable), substitute the GitHub source — same CLI, different origin:

   uvx --from git+https://github.com/trevhud/rote rote --version
   

Do not clone the repo or build a venv; uvx handles isolation.

4. Run the compilation

uvx --from rote-cli rote compile <skill-dir> --runtime <runtime> --out <out-dir>

Pick an out-dir the user will find, e.g. ./compiled/<skill-name> next to the source skill. Ensure it does not clobber existing work.

Set expectations before launching — this is not a quick command:

• It spawns claude -p as a subprocess. The driver deliberately scrubs ANTHROPIC_API_KEY / ANTHROPIC_AUTH_TOKEN from the child environment so the run bills against the user's Claude subscription, not per-token API charges. Do not "fix" auth by exporting an API key; if the user explicitly wants API billing, pass --agent api instead.
• A realistic skill takes ~13 minutes wall clock and 30-40 agent turns (Sonnet, ~$0.70 on subscription). Small skills are faster.
• Therefore run it in the background and tell the user you did. Poll the process and check in rather than blocking the session.

If the run exits nonzero, check whether <out-dir>/compiled/pipeline.yaml exists anyway — the CLI recovers completed work from transient subprocess failures and says so in its output. Surface stderr to the user either way.

5. Report the result

Read <out-dir>/compiled/pipeline.yaml and <out-dir>/compiled/compile-report.md, then summarize:

1. Node-kind table — count nodes per kind and what each kind means here:

   Kind	Count	Meaning
   pure_function	n	deterministic code, LLM removed
   external_call	n	direct API call with retry/timeout
   llm_judge	n	typed LLM signature (kept, but bounded)
   agent_loop	n	still agentic (genuinely exploratory)
   hitl_gate	n	durable human approval point

2. Codified fraction — nodes that no longer need an LLM, mandatory nodes, and what each HITL gate blocks on.

3. Where things landed — <out-dir>/compiled/ (IR, extracted/, signatures/, report) and <out-dir>/runtime/<runtime>/ (the deployable code).

4. Next steps — the extracted/* modules are scaffolds that raise NotImplementedError; the user fills in real API client code, then deploys the runtime output. Once deployed, rote register + rote serve expose the pipeline as an MCP tool so Claude can trigger runs — the serve skill in this plugin walks through that.