claudetools/.claude/skills/grok/SKILL.md

name, description

name

description

grok

Route a task to the Grok CLI (xAI Grok 4.3) for capabilities Claude lacks or for an independent second model. Use for: IMAGE generation/editing, VIDEO generation (image->video), live WEB + X/TWITTER search (current/real-time data past Claude's cutoff), and adversarial second-opinion VERIFICATION or drafts. Invoke on: "ask grok", "grok image", "generate/make an image", "make a video / animate this", "grok verify / second opinion from grok", "search X / twitter", "what's the latest <current-event/version>". Grok is a capability EXTENSION (image/video/live-data), not a replacement for Claude's own coding/editing.

Grok capability router

Claude shells out to the locally-installed Grok CLI (grok.exe, xAI Grok 4.3) for things Claude can't do natively, or for a genuinely independent second model. Verified working on this machine (2026-06-04): image gen, image->video, live web/X search, text reasoning.

Auth: Grok uses its own OIDC login (~/.grok/auth.json, grok.com, ~6h refresh) — no API key. If calls fail with auth errors, the user runs grok login.

The wrapper

bash "$CLAUDETOOLS_ROOT/.claude/skills/grok/scripts/ask-grok.sh" <mode> ...

Mode	Usage	What it does
text	ask-grok.sh text "<prompt>" or text --prompt-file <path>	One-shot text answer (independent model). --prompt-file for long content (review/summarize a doc).
verify	ask-grok.sh verify "<claim/finding>" or verify --prompt-file <path>	Adversarial second opinion — Grok tries to REFUTE/find gaps, returns a verdict + reasons.
review	ask-grok.sh review <file-path> ["<instructions>"]	Grok reads the file at <path> itself (its read_file tool) and reviews it — no embedding, handles large files, can pull in referenced files. Path resolution: absolute, CWD-relative, or relative to $CLAUDETOOLS_ROOT — see the path gotcha below. Spaces OK.
review-files	ask-grok.sh review-files [-i "<instr>"] <f1> [f2 …]	Review a set of files together (grok read_files each) — for cross-file consistency or a multi-file change. Same path resolution as review (see gotcha below); spaces OK. No code passed as a shell arg → no quote hell.
review-diff	ask-grok.sh review-diff [-C <repo-dir>] [-i "<instr>"] <gitref> [-- <pathspec>]	Review a git diff (git diff <gitref> from <repo-dir>; default repo root, use -C for a submodule e.g. -C projects/msp-tools/guru-rmm). The diff goes via the prompt file (not a shell arg); grok can read_file changed files for full context (cwd = repo dir).
image	ask-grok.sh image "<prompt>" [out.png]	image_gen (Imagine) → copies the artifact to out (default grok-image.png).
video	ask-grok.sh video "<motion prompt>" <input-image> [out.mp4]	image_to_video on an input image → copies to out. ~60-90s.
xsearch	ask-grok.sh xsearch "<query>"	Live web search, returns text with citations. Grok's multi-agent web_search frequently TIMES OUT on multi-part queries, so xsearch uses streaming-json and auto-falls-back to gemini search when grok doesn't finish (you'll see [grok xsearch timed out -> answered via gemini search]). Net: reliable answers; gemini is the workhorse engine.
raw	ask-grok.sh raw <grok args...>	Escape hatch — passes args straight to grok.

The script captures JSON (--output-format json), parses the result, and for media retrieves the artifact by sessionId from ~/.grok/sessions/<enc-cwd>/<sessionId>/{images,videos}/ — so artifacts are recovered even when a headless run reports stopReason: Cancelled before echoing the path (a known finalization quirk of the -p mode).

Warning

Path gotcha for review / review-files (this has bitten us repeatedly). A relative path is resolved against ONLY two roots: your current directory, and $CLAUDETOOLS_ROOT (/d/claudetools). It is NOT resolved against a submodule or any arbitrary subdir. So a path like server/src/api/auth.rs that is relative to a submodule (e.g. projects/msp-tools/guru-connect/) fails with file not found whenever your CWD isn't that submodule — even though the file obviously exists. When reviewing files in a submodule or any non-root subtree, pass ABSOLUTE paths (e.g. build the list with find "$(pwd)/server/src" -name '*.rs' from inside the submodule). Absolute paths always work regardless of CWD and tolerate spaces. (For review-diff, the analogous fix is -C <submodule-dir>.)

Machine availability (fleet)

Grok is per-machine — the skill syncs fleet-wide but the binary does not. Availability is gated by identity.json (per-machine, gitignored):

"grok": { "installed": true, "binary": "C:/Users/guru/.grok/bin/grok.exe",
          "auth": "oidc", "is_fleet_host": true,
          "capabilities": ["text","verify","image","video","xsearch"] }

• If grok.installed is false (or the block is absent), ask-grok.sh exits 3 with routing guidance instead of failing obscurely. Claude on such a machine should NOT attempt local Grok.
• Fleet Grok hosts: GURU-5070, GURU-BEAST-ROG — machines with Grok installed. When others get it, set their identity.json grok block (and update this line).

Remote routing (NOT yet wired): a non-host machine cannot run Grok locally. To fulfill a Grok request from elsewhere, route it to the host (GURU-5070). Candidate channels: GuruRMM agent command execution (/rmm — GURU-5070 is enrolled; the hard part is shipping image/video artifacts back), grok agent serve (WebSocket relay), or a coord-API job queue. Until that's built, Grok requests originate on the host machine.

When to route to Grok

• Image / video creation or editing — Claude can't generate media; Grok can. (image, video)
• Current / real-time facts — anything past Claude's knowledge cutoff, breaking news, latest versions, or X/Twitter sentiment. (xsearch)
• Independent verification — a genuinely different vendor/model to red-team a Claude finding or design before acting on it. (verify)
• Diverse drafts / second opinion — alternative phrasing or approach to compare. (text)

When NOT to

• Pure classify/extract/summarize → cheaper via Tier-0 Ollama (.claude/OLLAMA.md).
• Editing this repo's code → Claude's own agents (the Grok CLI can read .claude/ and run tools, but Claude owns the codebase work).
• Never delegate unsupervised destructive / production actions to Grok. The earlier SBS post-mortem (docs/session-notes/2026-06-03-claude-postmortem-grok-mspbackups-sbs.md) showed Grok over-claims and under-verifies — always review Grok output before acting on it, and confirm media is what was asked for (Claude can view images).

Safety / operational notes

• ~/.grok/config.toml defaults to permission_mode = "always-approve" (auto-runs tools). The wrapper's single-context modes (text/verify/review*) override with --permission-mode dontAsk --no-subagents (cheap, bounded, timeout-predictable). xsearch is the deliberate exception: it uses --yolo and leaves subagents ENABLED, because web_search runs the grok-4.20-multi-agent model — passing --no-subagents made it hang with zero output (the long-standing xsearch-empty bug; root-caused + fixed 2026-06-16). Don't re-add --no-subagents to xsearch.
• Prompts are passed via --prompt-file only (inline args break on shell quoting).
• grok-build does NOT support --effort/--reasoning-effort (supports_reasoning_effort:false in the model info) — passing them 400s. Don't.
• Models (verify live with grok models): grok-build ("Grok Build", xAI's latest coding model, 512k ctx — the documented default per docs/user-guide/11-custom-models.md) and grok-composer-2.5-fast ("Cursor's latest coding model", fast). Gotcha: on this machine the runtime default that grok models reports is grok-composer-2.5-fast, and the wrapper pins no -m, so it currently rides whatever the runtime default is (not necessarily grok-build). web_search uses a SEPARATE model, grok-4.20-multi-agent (set via [tools] web_search / GROK_WEB_SEARCH_MODEL).
• After media gen, Claude should view the image (Read tool) to confirm correctness; videos can be confirmed by header/ffprobe.

Reference

• Binary: ~/.grok/bin/grok.exe (not on PATH; the wrapper auto-locates it or honors GROK=).
• Full capability investigation + verification: see the 2026-06-04 session log.
• Grok native tools observed: image_gen, image_edit, image_to_video, reference_to_video, web_search, web_fetch, x_keyword_search, x_semantic_search, x_user_search, x_thread_fetch, run_terminal_command, file ops, scheduler_*, monitor, memory.