grok-agents
'Ask Grok', 'have Grok build or review this': drive the Grok CLI headless from another agent as a peer, builder or fresh reviewer.
phuryn · Static checks on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add phuryn/product-engineering --skill grok-agentsAbout this skill
name: grok-agents description: "'Ask Grok', 'have Grok build or review this': drive the Grok CLI headless from another agent as a peer, builder or fresh reviewer."
Grok agents — the Grok CLI headless as a partner
Any agent can run the Grok CLI non-interactively and get a full Grok session back: its tools, the repository's instructions where Grok reads them, a session that can be continued. Used that way it is a partner from another model family, same standing as the agent calling it: a peer that argues a decision through, a builder that takes a stage, or a reviewer that has never seen the build. This skill is how to brief it, which mode to run it in, and the commands. Everything here was read from grok --help and run on Grok CLI 1.0.70 (2026-11-02) unless it says otherwise; the CLI changes often, so check grok --help before relying on a flag.
The partner discipline (compact)
The full doctrine is the delegation skill; this is what must hold even when this folder is copied alone.
- A delegate gets the why, not just the what. The goal in the owner's terms, the decision it feeds, the facts, the reasoning behind non-obvious choices, the constraints that bind and the traps a smart newcomer would walk into, and how the result will be proved. Never a keystroke script.
- Peer, not tool. Its view is not binding, and neither is yours. A choice you would not have made is a disagreement to surface, not a defect.
- Early, not late, and iterate. The cheapest wins are at framing; three to eight turns is normal.
- Converge before surfacing. Bring the human one result, or a disagreement stated cleanly.
- A delegated diff is unreviewed code, and the session that wrote it never clears it. Read it, check the disk, re-run the gate yourself; the independent review is a fresh session (the
independent-reviewskill). - What never delegates: deciding what the product should do; accepting or rejecting a review finding; anything that touches a real system, development included (a deploy, a migration applied to any database, a server's secrets, a live setting); final verification; the judgement that a stage is done.
Three modes
| Mode | What it is for | Tools | Session |
|---|---|---|---|
| Peer | a decision argued through, a draft pushed on, a framing checked | read-only: --tools read_file,grep,list_dir, no shell, no edits | continued with --resume <id> |
| Builder | a stage with a goal, its binding decisions and how to prove it | every tool, approved: --always-approve, in a worktree of its own | continued within the stage |
| Reviewer | fresh eyes on a change | read-only, isolated from memory and other tools' settings (§ Reviewer) | always new |
Every mode shares four rules, each from a run that went wrong:
- The prompt goes in a file:
--prompt-file <brief>, never an inline-p "…". A long prompt inline trips the calling agent's permission classifier and the call is refused. --cwd <repo>on every call, so the session works in the repository you mean, and< /dev/null, because a CLI with an open stdin waits for input forever. A baregrokwith no prompt flag opens the interactive screen and hangs with no output.- Read the output format you asked for.
--output-format jsonreturns one object withtext,stopReason,sessionId,num_turnsandusage, which is what a calling agent wants;plainis the text alone. - Effort and model are stated.
--reasoning-effort xhighfor anything that needs judgement; the CLI's default is lower.grok modelslists the models and the default (grok-4.7on2026-11-02);-m <id>pins one.
Peer
SID=$(python -c "import uuid; print(uuid.uuid4())") # name the session yourself
grok --prompt-file "$S/turn-1.md" --cwd <repo> --session-id "$SID" \
--tools read_file,grep,list_dir --disallowed-tools search_tool,use_tool \
--deny MCPTool --deny Bash --deny Edit --deny Write --disable-web-search \
--always-approve --reasoning-effort xhigh --output-format json < /dev/null > "$S/turn-1.json"
# the next turn continues it: every flag again, --resume in place of --session-id
grok --resume "$SID" --prompt-file "$S/turn-2.md" --cwd <repo> \
--tools read_file,grep,list_dir --disallowed-tools search_tool,use_tool \
--deny MCPTool --deny Bash --deny Edit --deny Write --disable-web-search \
--always-approve --reasoning-effort xhigh --output-format json < /dev/null > "$S/turn-2.json"
--session-id <uuid>names the session, and--resume <uuid>continues it with its context (2026-11-02: a word given in the first turn came back from the second). Keep the id in a file beside the brief;-ccontinues the most recent session in the directory, which is whatever ran there last, so don't rely on it.--always-approveis what lets it read at all. Without it Grok can't approve its own file reads, and it exits 0 after a sentence of preamble, which reads like an answer. With the read-only allowlist above, approving everything approves only reading.- In peer mode Grok reads what you read: in a folder it trusts, the project's own instruction files and the skills its Claude compatibility finds load too (
grok inspectlists them). That is the point for a peer, and the reason the reviewer turns it off.
Builder
grok --prompt-file "$S/stage-brief.md" --cwd <worktree> --session-id "$SID" \
--always-approve --deny MCPTool --disable-web-search \
--reasoning-effort xhigh --output-format json < /dev/null > "$S/build-1.json"
--always-approveapproves every tool call, the shell included. So the builder works in a git worktree of its own, never the tree you are editing, and its brief keeps every real system out: no pushes, no deploys, no migrations, no secrets (§ The partner discipline, 6).--deny MCPToolkeeps it off the MCP servers this machine has connected, a database's included.- **Check the