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.mdskills/grok-routing/SKILL.md
GitHubGrok 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):
- Route first (no side effects):
grok_build_routeor/grok:route— readnextAction(handle_with_claude|call_mcp_tool+ tool/flags). Do not re-derive the plan. - If
nextAction.requiresHumanGateBeforeDelegate: plan (grok_build_plan//grok:plan) then wait for approval before any edit tool. If the plan result hasplanWroteFilesorcommittedset totrue, the tree already changed before any approval — say so first. - Execute:
grok_build_delegate//grok:delegateor verify/grok:verifyasnextAction.toolsays. - Review gate:
/grok:review— diff +billing; never auto-commit. - Multi-turn:
/grok:resumeusingusage.lastSession.sessionIdor the last result’ssessionId. - Presets:
/grok:tests,/grok:migrate,/grok:boilerplate - Auth / ready:
grok_build_status(orgrok_auth_check) with the task's absolutecwd, or/grok:setup. If status reportsbillingMismatch, warn that the server is in subscription mode while past delegations were recorded as metered — they ran whenGROK_BUILD_AUTH_MODEwasapi; 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 reportsbillingCaveat, relay itsmessage(grok'sconfig.tomlgives 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
- If
statusis notcompleted(auth_error,timeout, orgrok_error), show the returnedmessageand stop — do not report the run as done. Otherwise showsummary,filesChanged, and especiallybilling(subscriptionvsmetered_api) — with themessageofbillingCaveatbeside it when the result carries one. Ifcommittedistrue, grok made a git commit although the server never commits: show the returnedmessage— 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 infilesChanged. An absentcommittedmeans the run could not be checked, not "no commit". IfresumedCwdis present, the resumed session belongs to that directory and grok worked there, not in thecwdyou passed — review the diff there. A completed result can also carry amessage— 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. - Run the
/grok:reviewchecklist (or equivalent): adversarial correctness/security/scope. - Never auto-commit; the server never commits. User decides accept / fix / discard.
- Risky or large work: use
worktree: trueso changes land in an isolated worktree (worktreePath); review there before merge. - Partial failure still may list
filesChanged— inspect before continuing. - Offer
/grok:resumewhen asessionIdis 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.