llm-cli-gateway: Skill for Claude Code

Provider: xAI Grok CLI

Process guidance for keeping the gateway's Grok (grok) integration aligned with the upstream CLI. This skill does not define argv/env behaviour; the single mechanical source of truth is UPSTREAM_CLI_CONTRACTS.grok in src/upstream-contracts.ts, enforced by validateUpstreamCliArgs / validateUpstreamCliEnv. Never re-encode flags, permission modes, sandbox, or resume rules here or in TOML.

Identity

These values mirror UPSTREAM_CLI_CONTRACTS.grok.upstreamMetadata and docs/upstream/provider-sources.dag.toml ([providers.grok]). The TypeScript metadata is authoritative; the TOML is scanner input only.

When to use

• An xAI Grok CLI release lands and you need to check for contract drift.
• A grok request fails the upstream contract check before spawn.
• npm run upstream:scan -- --live reports a change on the x.ai changelog.

How LLM agents should use Grok through the gateway

1. Discover the live gateway/provider surface before relying on Grok-specific controls or local skill tools:

   provider_tool_capabilities({cli:"grok"})
   

   For a cached read-only resource, use provider-tools://grok.
2. Use grok_request for normal turns and grok_request_async for long-running review, analysis, or diversity checks. Sync calls may auto-defer; poll llm_job_status and fetch with llm_job_result when that happens.
3. Omit model unless the caller explicitly asked for a specific variant; the gateway resolves the configured Grok default.
4. Do not copy Claude tool names such as Read, Grep, Glob, or Bash into Grok allowedTools; Grok has its own provider-native tool names. This was the root cause of prior Grok reviewer startup failures.
5. Grok supports gateway allowedTools / disallowedTools, allow / deny, alwaysApprove, permissionMode, agent/subagent controls, web-search toggles, memory/planning toggles, prompt controls, output format, workspace/worktree/native-worktree controls, session controls, and compaction/effort controls as reported by provider_tool_capabilities. Use approvalStrategy:"legacy": Grok rejects mcp_managed before launch and approvalPolicy has no effect. Its permission and sandbox controls remain provider-native. Native ACP also rejects those Claude-only fields.
6. mcpServers is descriptive metadata only; Grok owns its MCP configuration.
7. Local Grok skills are discoverable from ~/.grok/skills and bundled skill directories. provider_tool_capabilities reports discovered provider-native tools such as Imagine image_gen, image_edit, image_to_video, and reference_to_video when those skills are present. The gateway still executes Grok through grok_request; it does not directly call those native tools.
8. The full subcommand surface (including agent/*, update, worktree, dashboard, login, etc.) is exposed via provider_subcommands_list, provider_subcommand_contract, and provider_subcommand_drift for inspection and drift monitoring. dashboard (grok 0.2.60 (474c2bbfc)+) is catalogued as read-only/inspect.
9. Grok continuity is real via sessionId, resumeLatest, createNewSession, --resume, and --continue. Auth must already be set up with grok login or XAI_API_KEY. Bind concurrent repository work with workingDir or a verified workspace. Use gateway worktree only with an explicit provider-native sessionId that is not overridden by createNewSession; fresh, createNewSession, and resumeLatest-only worktree requests fail closed.
10. An unscoped CLI child uses a fresh neutral temporary cwd. A cwd-scoped resumeLatest without a stable selected target fails closed. Grok's current prompt contract is argv-bound, so oversized UTF-8 input fails as non-retryable input_too_large and is never truncated. All other caller-controlled argv values are admitted in their final encoded form before spawn. Embedded NUL bytes return non-retryable invalid_input without exposing the rejected value.