grok-delegate

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Grok Delegate

Grok 委托任务

You are the orchestrator. This skill lets you hand a bounded coding task to a separate implementer — the Grok Build CLI (

grok

) — then review what it produced and land it yourself. You write the brief and own the judgment; Grok does the typing under an explicit autonomy profile; you verify and commit.

Nothing here is specific to one orchestrating agent. The loop needs only the ability to run a shell command and read a file, so it works the same whether you are Claude Code, Cursor, OpenCode with a selected model, or any comparable agent. (It is designed for Claude Code and Cursor; treat other orchestrators as designed-for, not yet proven.)

你是任务协调者。此技能允许你将一个限定范围的编码任务交给独立的实现工具——Grok Build CLI（

grok

）——之后审核其产出内容并自行完成提交。你撰写任务简报并负责判断；Grok在明确的自主配置下执行编码；你负责验证和提交。

本流程不特定于某一协调Agent。该循环仅需具备运行Shell命令和读取文件的能力，因此无论你是Claude Code、Cursor、选定模型的OpenCode，还是其他同类Agent，它的工作方式都相同。（本流程专为Claude Code和Cursor设计；其他协调Agent视为适配对象，但尚未验证。）

When NOT to use this

不适用场景

The task is small enough to just do inline — delegation overhead is not worth it.
The
```
grok
```
CLI is not installed, not authenticated, or the account lacks Grok Build beta access.
You want to write the code yourself, or you only need a review without an implementer run.

任务规模小到可直接完成——委托的开销得不偿失。
```
grok
```
CLI未安装、未认证，或账户无Grok Build测试版访问权限。
你希望自行编写代码，或仅需审核而无需调用实现工具。

Prerequisites (check once)

前提条件（检查一次）

```
grok version
```
succeeds. If not, install on any platform with
```
npm i -g @xai-official/grok
```
(or use the installer from xAI's official Grok CLI docs) and authenticate (
```
grok login
```
, or
```
grok login --device-auth
```
on headless hosts, or set
```
XAI_API_KEY
```
).
Confirm which
grok
is on PATH.
```
command -v grok
```
shows the active binary and
```
grok version
```
its version — the relay records the version it ran into
```
result.json
```
, so a stale binary is visible after the fact.
You are in (or will point
```
--cd
```
at) the target git repository.

```
grok version
```
命令执行成功。若失败，可在任意平台通过
```
npm i -g @xai-official/grok
```
安装（或使用xAI官方Grok CLI文档中的安装程序）并完成认证（
```
grok login
```
，无头主机使用
```
grok login --device-auth
```
，或设置
```
XAI_API_KEY
```
）。
确认PATH中的
grok
版本。
```
command -v grok
```
显示当前使用的二进制文件路径，
```
grok version
```
显示版本——中继工具会将运行的版本记录到
```
result.json
```
中，因此事后可发现过期的二进制文件。
你处于（或通过
```
--cd
```
指定）目标Git仓库目录中。

The loop

操作流程

Run these five steps per task. Steps 1, 4, and 5 are your judgment; 2 and 3 are mechanical.

每个任务执行以下五个步骤。步骤1、4、5需你判断；步骤2、3为机械操作。

1. Write the brief

1. 撰写任务简报

Grok sees only the text you send — no orchestrator chat history, no shared context. Everything the task needs goes in the brief: the goal, the current state, what to change, what to leave untouched, the project's actual gate commands (discover them from the repo's CLAUDE.md/AGENTS.md/Makefile — do not assume), and a report contract. Tell Grok it will not commit (you will). Keep one task per brief. Full guidance and a template: references/writing-the-brief.md.

Grok仅能看到你发送的文本——无协调Agent的聊天历史，无共享上下文。任务所需的一切信息都需包含在简报中：目标、当前状态、需修改内容、需保留内容、项目的实际验证命令（从仓库的CLAUDE.md/AGENTS.md/Makefile中查找——请勿假设），以及报告约定。告知Grok它不会提交代码（由你完成）。每份简报对应一个任务。完整指南和模板：references/writing-the-brief.md。

2. Dispatch

2. 调度任务

Send the brief to Grok with the bundled helper. It wraps

grok -p

, captures the run, and writes a structured

result.json

— so your only job is "run a command, read a file." (

<skill-dir>

below is this skill's installed directory — the folder containing this

SKILL.md

, i.e. the directory you loaded the skill from. Claude Code prints it as "Base directory for this skill" when the skill loads; on other orchestrators use that same directory — if unsure where it landed, run

find ~ -name relay.mjs -path '*grok-delegate*'

and substitute the directory above it.)

bash

node "<skill-dir>/scripts/relay.mjs" --brief brief.txt --cd /path/to/repo

使用捆绑的辅助工具将简报发送给Grok。它封装了

grok -p

命令，捕获运行过程并写入结构化的

result.json

文件——因此你只需“运行命令，读取文件”即可。（下方的

<skill-dir>

是此技能的安装目录——包含本

SKILL.md

的文件夹，即你加载该技能的目录。Claude Code在技能加载时会打印“此技能的基础目录”；其他协调Agent使用同一目录——若不确定位置，可运行

find ~ -name relay.mjs -path '*grok-delegate*'

并替换为其上级目录。）

bash

node "<skill-dir>/scripts/relay.mjs" --brief brief.txt --cd /path/to/repo

read-only (review/diagnosis; best-effort — verify touchedFiles): add --read-only

continue the previous Grok session: add --resume-last (send only the delta brief)

hard time limit (watchdog): add --timeout 2h (default: off; implementation runs routinely need 1-2h)

see all options: node .../relay.mjs --help


The helper defaults to a write-capable (`workspace-write`) autonomy profile — `--always-approve` plus
`--sandbox workspace` — and writes its artifacts to a temp dir, so the repo under review stays clean.
It **never commits** — see step 5. Mechanics, flags, and the `result.json` shape:
[references/dispatch-and-poll.md](references/dispatch-and-poll.md).


辅助工具默认使用可写入（`workspace-write`）的自主配置文件——`--always-approve`加`--sandbox workspace`——并将产物写入临时目录，因此待审核的仓库保持干净。它**绝不会**提交代码——见步骤5。机制、参数和`result.json`结构：[references/dispatch-and-poll.md](references/dispatch-and-poll.md)。

3. Wait for completion

3. 等待完成

The helper blocks until Grok finishes, so back it with whatever your orchestrator offers and resume when it returns:

Claude Code: run the Bash call with
```
run_in_background: true
```
; you are notified on completion.
Plain shell / other agents: run it in the foreground for short tasks, or background it and poll the result file —
```
… &
```
in bash/zsh (including Git Bash/WSL), or your shell's equivalent (
```
Start-Job
```
in PowerShell,
```
start /b
```
in cmd). The run is done when
```
result.json
```
exists with a
```
status
```
. (A pre-run usage error — bad args or an empty brief — instead exits with code 2 and a stderr message and writes no result file, so check the exit code too. A missing
```
grok
```
binary exits 127 but does write a
```
result.json
```
with status
```
grok_unavailable
```
.)

Do not trust progress trackers over reality: a run is finished when

result.json

is written and the process has exited. Read the working tree, not a status line. The implementer's full report is the

finalMessage

field in

result.json

(also printed in full on stdout between the report markers).

辅助工具会阻塞直到Grok完成任务，因此可借助协调Agent提供的后台运行能力，完成后再恢复操作：

Claude Code：使用
```
run_in_background: true
```
运行Bash命令；完成后会收到通知。
普通Shell/其他Agent：短任务可在前台运行，长任务可后台运行并轮询结果文件——在bash/zsh（包括Git Bash/WSL）中使用
```
… &
```
，或使用Shell的等效命令（PowerShell中的
```
Start-Job
```
，cmd中的
```
start /b
```
）。当
```
result.json
```
存在且包含
```
status
```
字段时，任务完成。（预运行使用错误——参数无效或简报为空——会以代码2退出并输出stderr信息，且不写入结果文件，因此需同时检查退出码。缺失
```
grok
```
二进制文件会以127退出，但会写入
```
status
```
为
```
grok_unavailable
```
的
```
result.json
```
。）

不要依赖进度跟踪器，以实际状态为准：当

result.json

写入且进程退出时，任务才完成。查看工作目录的实际状态，而非状态行。实现工具的完整报告位于

result.json

的

finalMessage

字段中（也会在stdout的报告标记之间完整打印）。

4. Review — do not trust the self-report

4. 审核——不要轻信自我报告

Grok's

result.json

includes its own summary and gate claims. Re-verify, don't accept:

Re-run the project's gates yourself (the test/lint/build commands from step 1). Never take "gates passed" on faith.
Read the diff against the brief: did Grok do what was asked, nothing more (scope creep) and nothing less?
```
touchedFiles
```
in the result is your starting point.
Run the relevant guard skills on the diff if you have them installed (clean-code-guard, test-guard, etc. from
```
guard-skills
```
) — this skill produces the work; those skills judge it.
For schema/migration changes, round-trip them; for removals, grep for dangling references.

Full checklist: references/review-and-land.md.

Grok的

result.json

包含其自身的总结和验证声明。重新验证，不要直接接受：

自行重新运行项目的验证命令（步骤1中的测试/ lint/构建命令）。永远不要轻信“验证通过”的说法。
对照简报查看代码差异：Grok是否完成了要求的工作，不多做（范围蔓延）也不少做？结果中的
```
touchedFiles
```
是你的起点。
若已安装相关守护技能，在差异上运行它们（
```
guard-skills
```
中的clean-code-guard、test-guard等）——本技能负责生成工作成果；那些技能负责评判成果。
对于架构/迁移变更，进行往返测试；对于删除操作，查找悬空引用。

完整检查清单：references/review-and-land.md。

5. Land it

5. 完成提交

The orchestrator commits. Only after the gates pass and the diff holds:

Commit the verified work yourself, with a clear message.
If it needs changes, send a delta brief with
```
--resume-last
```
(don't restate the whole task) and review again.

由协调者提交代码。仅在验证通过且代码差异符合要求后：

自行提交已验证的工作，附带清晰的提交信息。
若需要修改，使用
```
--resume-last
```
发送增量简报（无需重述整个任务）并再次审核。

Autonomy model

自主权限模型

Grok's default permission mode is

ask

, which blocks on approval prompts in a headless pipe. The relay therefore always sets autonomy explicitly:

Relay flag	What Grok gets	Use when
(default)	`--always-approve --sandbox workspace`	Normal implementation — writes scoped to the working tree
`--read-only`	`--sandbox read-only --permission-mode plan`	Review / diagnosis — best-effort, not enforced (see caveat below)
`--full-access`	`--always-approve --sandbox off`	Explicit opt-in when the task needs unrestricted tools

--always-approve

alone would approve all tools (writes, shell, network) — closer to unrestricted than to a workspace-scoped write. Pairing it with

--sandbox workspace

is what keeps the default safe. Reach for

--full-access

only when the human asks for it.

--read-only
is best-effort, not a hard guarantee. The read-only sandbox restricts out-of-workspace filesystem/network access, not grok's own edit tool, and headless

plan

mode is advisory — a run verified here still wrote the working tree when told to. Use

--read-only

to signal review intent, but always confirm

touchedFiles

afterward; treat the diff, not the flag, as the guarantee. The relay automates the check: it snapshots

git status

before a

--read-only

run and sets

readOnlyViolation: true

result.json

(with a summary warning) when the tree changed anyway. It's a porcelain-level tripwire — an edit inside an already-dirty file can evade it, so on a dirty tree the diff review stays the only real guarantee.

Grok的默认权限模式是

ask

，这会在无头管道中阻塞等待批准提示。因此中继工具始终会显式设置自主权限：

Relay 参数	Grok 获得的权限	使用场景
(默认)	`--always-approve --sandbox workspace`	常规实现任务——写入操作限定在工作目录内
`--read-only`	`--sandbox read-only --permission-mode plan`	Review / diagnosis — best-effort, not enforced (see caveat below)
`--full-access`	`--always-approve --sandbox off`	Explicit opt-in when the task needs unrestricted tools

仅使用

--always-approve

会批准所有工具（写入、Shell、网络）——更接近无限制权限，而非限定在工作目录的写入权限。将其与

--sandbox workspace

搭配使用才能保证默认模式的安全性。仅当用户要求时才使用

--full-access

。

--read-only
是尽力而为的模式，并非硬性保证。只读沙箱限制工作目录外的文件系统/网络访问，但不限制grok自身的编辑工具，且无头

plan

模式是建议性的——曾出现过在此模式下仍修改了工作目录的情况。使用

--read-only

来表明审核意图，但事后务必确认

touchedFiles

；以代码差异而非参数作为保证。中继工具会自动检查：在

--read-only

运行前快照

git status

，若目录发生变更，则在

result.json

中设置

readOnlyViolation: true

（并附带摘要警告）。这是一个表层的触发机制——若修改已脏文件内的内容可能会规避检查，因此在脏目录中，代码差异审核仍是唯一真正的保证。

Authorization model

授权模型

Delegation is something the human opts into. Once they have ("run this queue", "proceed"), committing verified, gate-passing work is the agreed contract — that is the whole point. Two limits on that mandate: surface, don't absorb (report Grok's design decisions, defensible-but-unasked turns, and non-blocking nitpicks rather than silently keeping them) and stop for scope changes (if correct completion needs going beyond the brief, ask — don't expand the mandate yourself). The full treatment is in references/review-and-land.md.

委托是用户主动选择的操作。一旦用户确认（“运行此队列”、“继续”），提交已验证且通过测试的工作就是约定的内容——这正是核心目的。此授权有两个限制：透明化，不隐瞒（报告Grok的设计决策、合理但未要求的变更，以及非阻塞性的小问题，而非默默保留）；范围变更时停止（若正确完成任务需要超出简报范围，需询问用户——不要自行扩大授权）。完整说明见references/review-and-land.md。

References

参考资料

references/writing-the-brief.md — how to write a brief Grok can execute blind: structure, XML blocks, the report contract, embedding the real gate commands.
references/dispatch-and-poll.md —
```
relay.mjs
```
flags, the
```
result.json
```
contract, backgrounding per orchestrator, and recovery when a run misbehaves.
references/review-and-land.md — the review checklist, the commit boundary, and the rework cycle via
```
--resume-last
```
.
references/multi-task-queues.md — running a sequential queue: carrying constraints forward, progress tracking, and the end-of-run coherence check.

references/writing-the-brief.md — 如何撰写Grok可独立执行的简报：结构、XML块、报告约定、嵌入实际验证命令。
references/dispatch-and-poll.md —
```
relay.mjs
```
参数、
```
result.json
```
约定、各协调Agent的后台运行方式，以及运行异常时的恢复方法。
references/review-and-land.md — 审核清单、提交边界，以及通过
```
--resume-last
```
进行返工的循环流程。
references/multi-task-queues.md — 运行顺序队列：传递约束、进度跟踪，以及运行结束时的一致性检查。