grok-routing

When to delegate coding work to Grok Build vs handle it in Claude. Use whenever the user asks for bulk edits, test backfill, migrations, boilerplate, exploratory prototypes, or whether to use /grok:de

SKILL.md

GitHub

Grok routing (Claude orchestrates, Grok executes)

You are in a session where the grok plugin can run Grok Build via MCP. Product goal: help the user use Grok well, feel Grok’s strength, and enjoy Claude ↔ Grok collaboration — not replace Claude.

Default posture

When a task is a good fit for Grok, propose delegation first (brief why + tool), then run it if the user agrees or already asked to use Grok. Do not dump every coding task on Grok.

Delegate to Grok when

Fit Examples
Bulk / repetitive Same pattern across many files, renames, import fixes
Low-risk volume Test backfill, docs sync, boilerplate CRUD/DTO/scaffold
Narrow independent scope Single module, clear acceptance criteria, little monorepo coupling
Exploratory prototype Try an approach fast; user will review

Tools (prefer this order):

  1. Route first (no side effects): grok_build_route or /grok:route — read nextAction (handle_with_claude | call_mcp_tool + tool/flags). Do not re-derive the plan.
  2. If nextAction.requiresHumanGateBeforeDelegate: plan (grok_build_plan / /grok:plan) then wait for approval before any edit tool. If the plan result has planWroteFiles or committed set to true, the tree already changed before any approval — say so first.
  3. Execute: grok_build_delegate / /grok:delegate or verify /grok:verify as nextAction.tool says.
  4. Review gate: /grok:review — diff + billing; never auto-commit.
  5. Multi-turn: /grok:resume using usage.lastSession.sessionId or the last result’s sessionId.
  6. Presets: /grok:tests, /grok:migrate, /grok:boilerplate
  7. Auth / ready: grok_build_status (or grok_auth_check) with the task's absolute cwd, or /grok:setup. If status reports billingMismatch, warn that the server is in subscription mode while past delegations were recorded as metered — they ran when GROK_BUILD_AUTH_MODE was api; ask the user to confirm the current value is the one intended. Do not stop on it: it describes history and stays true while those rows remain, so treating it as a gate would block every later delegation. If it reports billingCaveat, relay its message (grok's config.toml gives some model its own key or one inherited from [model_providers.<id>], or could not be checked) but do not stop — it is a warning, not a gate.

Always pass absolute cwd. Prefer English prompts for the prompt field.

Do not make coding edits through grok_cli / /grok:cli. A passthrough that carries a prompt is a real grok turn: the pre-delegate auth hook gates it and delegation history records it (via: 'grok_cli'). But it has none of delegate's review aids — no worktree isolation, no parsed summary, no committed check, no billingCaveat. /grok:cli stays the escape hatch for subcommands that are not coding edits (models, sessions, memory, …), but some of them delete — memory clear can take each memory scope as a whole folder, sessions delete a session, worktree rm a folder — so confirm the scope first; use grok_build_delegate / grok_build_verify for coding edits.

Optional tool fields (validated; bad values fail without running grok): model — omit it unless you have a reason, so the run follows whatever the CLI defaults to (grok models is the only current answer; on 2026-09-22 that was grok-4.7, with a grok-4.7-build-fast tier beside it, and the model the run records is reported back as model). grok-build is remapped to the CLI default. Also max_turns (stop cleanly after n turns, keeping partial edits — a bound on work rather than timeout_ms's wall clock), effort (low/medium/high/xhigh), resume / continue (not both), sandbox (workspace | read-only | strict | devbox | off — Linux/macOS kernel enforce; Windows not assumed). Do not pass best_of_n — CLI 1.0 removed --best-of-n. Results may include sessionId for later resume. filesChanged lists paths that became dirty during the run; use worktree: true on already-dirty trees for full attribution.

External orchestrators: copy the loop in examples/orchestrator-consumer.md and ${CLAUDE_PLUGIN_ROOT}/docs/07-orchestrator-integration.md.

Keep in Claude (do not delegate)

  • Architecture / design decisions, API shape trade-offs
  • Security (auth, crypto, permissions), secrets, compliance / regulated domains
  • Work needing whole monorepo or very large context
  • Final code review and quality gate (you always review Grok’s diff)

After every Grok run

  1. If status is not completed (auth_error, timeout, or grok_error), show the returned message and stop — do not report the run as done. Otherwise show summary, filesChanged, and especially billing (subscription vs metered_api) — with the message of billingCaveat beside it when the result carries one. If committed is true, grok made a git commit although the server never commits: show the returned message — it names the folder whose HEAD moved and the commit it moved from, with how to inspect and undo it there (never run those commands in another folder) — and remember the committed files are no longer in filesChanged. An absent committed means the run could not be checked, not "no commit". If resumedCwd is present, the resumed session belongs to that directory and grok worked there, not in the cwd you passed — review the diff there. A completed result can also carry a message — show it whenever there is one: besides a commit notice, it can say that the prompt, with any files it @-mentions or skill it invokes, was too long for grok (its request to the model left out part of the prompt or of what grok added to it), so the work may not reflect the whole prompt.
  2. Run the /grok:review checklist (or equivalent): adversarial correctness/security/scope.
  3. Never auto-commit; the server never commits. User decides accept / fix / discard.
  4. Risky or large work: use worktree: true so changes land in an isolated worktree (worktreePath); review there before merge.
  5. Partial failure still may list filesChanged — inspect before continuing.
  6. Offer /grok:resume when a sessionId is available for follow-ups.

Auth failures

If tools fail with install/login messages, guide /grok:setup or the message’s commands. Do not attempt grok login or install inside this session for the user.

Cost note

Default mode is subscription. Do not thrash (no delegate-on-every-keystroke). In API/metered mode, be stricter about fit and avoid wasteful retries.