Skip to content
Get packs

Guide · Agent skill

How to use the Grok Build CLI Operator agent skill

Updated · written with AI from the project's own documentation and checked against our catalogue data

The grok-build skill teaches an AI agent how to operate the Grok Build command-line tool (the grok binary), a separate coding agent from xAI. Once installed and triggered, the agent knows which commands to use for interactive and headless runs, logging in, sessions, git worktrees, sandbox and permission settings, and output formats for scripts. This guide shows you how to install the skill, ask for it in plain language, and set it up safely.

Grok Build CLI OperatorXiaomiMiMo/MiMo-Code · MIT

Quick start

  1. 1Install the Grok Build CLI. Install the grok binary so it is on your PATH, then confirm with grok version. The skill will stop and give guidance if it is missing.
  2. 2Authenticate. Run grok login on a developer machine, or grok login --device-auth in headless or remote environments. You can alternatively provide XAI_API_KEY to the process that needs it.
  3. 3Download and unzip the skill. Download the grok-build ZIP from this page and unzip it into ~/.claude/skills/ or your project's .claude/skills/ folder.
  4. 4Start a request that names the skill. Ask the agent to use the grok-build skill and describe the task and the repository path.
  5. 5Choose sandbox and permissions. Pick --sandbox read-only, workspace or strict based on how much you trust the repository, and add --allow or --deny rules as needed.
  6. 6Review the output. Read the result in plain format, or use json or streaming-json if a script will consume it.

What is an agent skill and what does grok-build do?

An agent skill is a folder of instructions and reference files that an AI agent loads when a task matches it. The grok-build skill is written for the Grok Build CLI and covers interactive and non-interactive runs, authentication, sessions, worktrees, permissions, sandboxing, MCP servers, plugins, inspection, updates, and automation output.

The skill does not install Grok Build for you. It stops and gives install or authentication guidance if the grok binary is not available.

  • Starts a terminal task or a headless run with an explicit working directory and output format
  • Chooses sandbox and permission settings deliberately instead of defaulting to unattended approval
  • Uses built-in inspection and diagnostics before changing configuration
  • Asks you to confirm destructive actions such as session deletion or worktree removal

What do you need before installing grok-build?

The skill has three requirements. It needs the Grok Build CLI (grok binary) installed and on your PATH. It needs xAI authentication, either through grok login or the XAI_API_KEY environment variable. The skill runs scripts and uses the network.

The skill checks for the binary with command -v grok and grok version before any command runs.

  • Grok Build CLI (grok) installed and on PATH
  • xAI authentication via grok login or XAI_API_KEY
command -v grok grok version

How do you install the grok-build skill?

Download the ZIP from this page and unzip it into one of two locations. For a personal skill available across projects, unzip it into ~/.claude/skills/. For a single project, unzip it into that project's .claude/skills/ folder.

You can also upload the skill in the Claude apps. Open Settings, go to Capabilities, then Skills, and upload the ZIP there.

  • Personal: ~/.claude/skills/grok-build/
  • Project only: .claude/skills/grok-build/ inside your repository
  • Claude apps: Settings → Capabilities → Skills, then upload the ZIP

How do you trigger the skill with a natural request?

The skill only loads when you explicitly authorize it or name Grok Build or grok-build. A request that does not mention Grok Build will not activate it. Say the name in the request so the agent knows to use it.

Good trigger phrases name the tool and the task, for example asking the agent to use the grok-build skill to review a repository in read-only mode.

  • "Use the grok-build skill to explain the failing test in ./api without changing files."
  • "With grok-build, run a headless Grok Build job on /srv/app and return JSON."
  • "Load grok-build and show me which MCP servers Grok Build can see for this repo."

What does a typical headless run look like?

For scripts and CI, the skill uses headless mode with -p, an explicit working directory, the workspace sandbox, and a JSON output format. It also passes --no-auto-update so background update checks do not run inside automation.

Use plain output for people reading a terminal, json for one final machine-readable object, and streaming-json for newline-delimited progress events. Do not parse the interactive TUI in automation.

  • plain: for humans
  • json: one final object
  • streaming-json: newline-delimited incremental events
grok --no-auto-update \ --cwd /path/to/repo \ --sandbox workspace \ -p "Inspect the repository and explain the failing test." \ --output-format json

How do you control permissions and sandboxing safely?

Permissions and sandboxing are separate controls. Permission rules decide whether a tool call may run. A sandbox profile limits what an approved call can access. The skill prefers --sandbox workspace for normal repository changes, --sandbox read-only for review, and --sandbox strict for untrusted repositories.

Use --allow and --deny for per-run policy. Deny rules win. The sandbox is off by default unless you configure or select it, so check your setup before running unattended.

  • --sandbox workspace: normal repository changes
  • --sandbox read-only: review and auditing
  • --sandbox strict: untrusted repositories, then add narrow permission rules
  • --allow <RULE> and --deny <RULE>: per-run policy

How do sessions and worktrees work?

The skill can continue the most recent session, resume a named session, or start a new session with a UUID you supply. Use a git worktree when concurrent work could collide. Before deleting a worktree, the skill previews removal with a dry run. Deleting a session does not remove its worktree.

  • Continue: grok -c
  • Resume by ID: grok --resume <session-id>
  • New named session: --session-id <UUID>
  • Worktree: grok --worktree --ref main "Fix the flaky test"
grok worktree rm --dry-run <id>

What people use it for

  • Asking an agent to explain a failing test in a repository without letting it edit files, using read-only sandboxing
  • Running a headless Grok Build job in CI that returns one JSON object for a bot to read
  • Resuming yesterday's Grok Build session in the same directory to continue a refactor
  • Running two tasks at once in separate git worktrees so their changes do not collide
  • Checking which MCP servers and plugins Grok Build can see using inspection and diagnostics before adding new ones

Frequently asked questions

Is the grok-build skill free?

The skill is published under the MIT licence. The source does not state pricing for the Grok Build CLI or xAI access, so check the official xAI documentation for any costs on your account.

What do I need to install before using grok-build?

You need the Grok Build CLI (the grok binary) on your PATH and xAI authentication, either from grok login or the XAI_API_KEY environment variable. Without the binary the skill only gives install guidance.

Where do I put the grok-build skill folder?

Unzip the downloaded ZIP into ~/.claude/skills/ for personal use or into .claude/skills/ inside a project. You can also upload the ZIP in the Claude apps under Settings, Capabilities, Skills.

Why won't the agent use grok-build when I ask for a task?

The skill loads only when you explicitly authorize it or name Grok Build or grok-build. Include the name in your request. If it still does not load, confirm the folder is in the correct skills directory.

Is it safe to run Grok Build unattended?

Use --always-approve only with a suitable sandbox and explicit deny rules, because it can let commands change files or systems without review. The source notes the sandbox is off by default unless configured, so do not treat approval flags as sandboxing.

How is grok-build different from using the grok CLI directly?

The skill gives an agent the right commands and safety defaults for operating the grok CLI. It does not add functionality of its own, and it needs the grok binary installed to do anything.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Use grok-build if you already use the Grok Build CLI and want an agent to run it correctly, especially for headless jobs, sessions, worktrees and sandbox choices. Skip it if you do not have the grok binary, or if you plan to run unattended jobs without a sandbox or deny rules, since the skill adds little without the CLI and needs careful configuration to be safe.

Download the skill