Grok Build Migration

A Grok Build to Claude Code migration is mostly a configuration translation, not a rewrite of your repository. Keep AGENTS.md, import it from CLAUDE.md, move portable skills and agent prompts deliberately, rebuild MCP and hook configuration in Claude's formats, then compare both agents on the same small task before deleting anything.

The code stays put. Git history stays put. Your tests remain the judge. The work is making sure Claude sees the same instructions and has only the tools you intended to grant.

What actually moves

xAI describes Grok Build as a terminal coding agent with interactive and headless modes, Agent Client Protocol support, custom models, skills, plugins, hooks, MCP servers, and subagents. Its user settings live in ~/.grok/config.toml, while project configuration can live under .grok/ (Grok Build overview, Grok Build settings).

Claude Code has equivalents for most of those concepts, but the file formats are not interchangeable. Anthropic separates persistent instructions, settings, MCP servers, skills, subagents, hooks, and plugins into different files and directories (Claude Code extension overview).

That last row matters. Do not spend an afternoon trying to transplant a conversation transcript. Put durable decisions in repository files, commit them, and let Claude read the source of truth.

Inventory before touching configuration

Start in the repository root. Ask Grok what it currently discovers, then save a plain inventory for yourself:

grok inspect

find . -maxdepth 4 \
  \( -path './.grok/*' -o -name 'AGENTS.md' -o -name 'Agents.md' -o -name 'AGENT.md' \) \
  -type f \
  -print \
  | sort

grok inspect is the official verification command for config sources, instructions, skills, plugins, hooks, and MCP servers (xAI settings documentation). The find command gives you a repository-local list. It does not expose the values inside ~/.grok/config.toml, where API keys or private endpoints may live.

Make a temporary branch before changing shared instructions:

git switch -c chore/migrate-grok-to-claude
git status --short

If the working tree is already dirty, stop and understand those changes first. Migration work is much easier when every diff belongs to the migration.

Keep AGENTS.md as the shared source

Grok Build walks the AGENTS.md file family from the working directory to the repository root (xAI skills and plugins documentation). Claude Code reads CLAUDE.md, not AGENTS.md.

Anthropic documents the bridge directly: create CLAUDE.md and import the existing file (Claude Code memory documentation).

@AGENTS.md

## Claude Code

- Run the existing test command before reporting a code change complete.
- Ask before changing deployment, billing, or production data.
- Keep generated files out of commits unless the task explicitly requires them.

This is better than maintaining two copies. Shared rules remain in AGENTS.md. Claude-only behavior sits below the import.

Run Claude and verify the file is loaded:

claude

Then run /context inside the session. CLAUDE.md should appear under memory files. If it does not, check that you launched Claude from the repository or one of its subdirectories.

Run the safe migration helper

The script below does three conservative things:

1. Creates a CLAUDE.md import when one does not exist.
2. Copies project skills into .claude/skills/ without overwriting existing files.
3. Writes a report of Grok components that still need manual translation.

It does not touch user configuration, copy secrets, convert hooks, or delete .grok.

Save it as scripts/prepare-claude-migration.sh:

#!/usr/bin/env bash
set -euo pipefail

repo_root="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
cd "$repo_root"

if [[ -e "CLAUDE.md" ]]; then
  printf 'Keeping existing CLAUDE.md\n'
elif [[ -f "AGENTS.md" ]]; then
  printf '@AGENTS.md\n\n## Claude Code\n\n- Run tests before reporting completion.\n' > CLAUDE.md
  printf 'Created CLAUDE.md with an AGENTS.md import\n'
else
  printf 'No AGENTS.md found. Run /init in Claude Code after installation.\n'
fi

mkdir -p .claude/skills

if [[ -d ".grok/skills" ]]; then
  while IFS= read -r -d '' skill_dir; do
    skill_name="$(basename "$skill_dir")"
    destination=".claude/skills/$skill_name"

    if [[ -e "$destination" ]]; then
      printf 'Skipped existing skill: %s\n' "$destination"
      continue
    fi

    cp -R "$skill_dir" "$destination"
    printf 'Copied skill for review: %s\n' "$destination"
  done < <(find .grok/skills -mindepth 1 -maxdepth 1 -type d -print0)
fi

report=".claude/grok-migration-review.md"
{
  printf '# Grok Build migration review\n\n'
  printf 'Generated from repository-local files only.\n\n'
  printf '## Files still requiring manual review\n\n'

  for candidate in \
    .grok/config.toml \
    .grok/agents \
    .grok/hooks \
    .grok/plugins \
    .grok/mcp.json
  do
    if [[ -e "$candidate" ]]; then
      printf -- '- `%s`\n' "$candidate"
    fi
  done

  printf '\n## Checks\n\n'
  printf -- '- [ ] CLAUDE.md loads in `/context`\n'
  printf -- '- [ ] Every copied skill has valid frontmatter\n'
  printf -- '- [ ] MCP servers reconnect without copied secrets\n'
  printf -- '- [ ] Permission rules deny sensitive files\n'
  printf -- '- [ ] The normal test and build commands pass\n'
} > "$report"

printf 'Wrote %s\n' "$report"
printf 'Review the diff before committing. Nothing under .grok was deleted.\n'

Make it executable and run it:

chmod +x scripts/prepare-claude-migration.sh
./scripts/prepare-claude-migration.sh
git diff -- CLAUDE.md .claude scripts/prepare-claude-migration.sh

Copying a skill is only the start. Grok and Claude both use skill folders with Markdown instructions and resources, but a skill may mention Grok-only commands or tools. Read every copied SKILL.md, replace those references, and invoke the skill on a disposable task.

Translate settings by purpose

Grok stores user defaults in TOML. Claude Code settings are JSON. Renaming config.toml to settings.json gives you invalid configuration and a false sense of completion.

Split the translation into four buckets:

• Behavioral instructions belong in CLAUDE.md or .claude/rules/.
• Tool permissions and environment settings belong in .claude/settings.json or the uncommitted .claude/settings.local.json.
• MCP server definitions belong in .mcp.json.
• Repeatable workflows belong in skills, subagents, hooks, or plugins.

A minimal project settings file can deny common secret files and allow safe inspection commands:

{
  "permissions": {
    "allow": [
      "Bash(git status *)",
      "Bash(git diff *)",
      "Bash(npm test *)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Bash(rm -rf *)"
    ]
  }
}

Claude Code permissions and its operating-system sandbox are separate layers. Permissions decide which tools and paths Claude may request; sandboxing limits what shell processes can reach even if a bad instruction gets through (Anthropic permissions documentation).

Do not commit credentials in either system. Reference environment variable names in shared configuration and keep values in your secret manager or local environment.

Reconnect MCP servers one at a time

Grok Build can discover MCP servers from its configuration. Claude Code uses .mcp.json, settings, managed configuration, or plugin-provided .mcp.json files (Claude Code MCP documentation).

Do not translate five servers and debug them as a group. Add one, restart or reload as required, authenticate it, call one read-only tool, then move to the next.

A project-level stdio server has this shape:

{
  "mcpServers": {
    "docs": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "./docs"]
    }
  }
}

Treat that as a shape, not a universal server recipe. Use the server publisher's current package name and arguments. In Claude, run /mcp to inspect connections and complete OAuth when a remote server requires it.

Port agents, hooks, and plugins deliberately

Grok Build's open-source release includes its extension system, including skills, plugins, hooks, MCP servers, and subagents (xAI open-source announcement). That makes the concepts familiar. It does not make manifests portable.

For each agent:

1. Copy the plain-language role and completion criteria.
2. Rebuild its YAML frontmatter using Claude's supported fields.
3. Restrict its tools.
4. Pick a Claude model alias.
5. Test it with an explicit mention before relying on automatic delegation.

Claude custom subagents live in .claude/agents/ and require name and description. They can also define tools, model, permission mode, skills, hooks, memory, effort, and worktree isolation (Anthropic subagent documentation).

Hooks need more suspicion. A hook is executable automation. Recreate it from its intended event and safety rule, not from copied syntax. A formatter after Edit is straightforward. A hook that auto-approves shell commands deserves a line-by-line review.

Plugins bundle several moving pieces. Claude plugins have their own manifest and component locations, so reinstall an official equivalent when one exists. Port custom plugins only after the basic repository works without them.

Compare behavior before removing Grok

Pick a small task with a crisp answer, such as adding one validation rule and one unit test. Run it in separate branches or reset between attempts. Give both tools the same repository state and the same prompt.

Score the result on evidence:

Claude Code has its own planning, subagent, and headless workflows. Do not force every Grok habit into a one-for-one replacement. Once the baseline works, read the Claude Code headless guide and custom agent guide for the native patterns.

Keep .grok for at least one normal work cycle. Delete it only after Claude has completed real tasks, your team has reviewed the new configuration, and the old tool is no longer part of CI or onboarding.

Where the $29 Code Kit fits

Switching agents does not create a delivery process by itself. You still need a plan, tests, review, and a clean build. The $29 Code Kit is a one-time harness around Claude Code that runs a plan, build, evaluate, and test loop with repeatable quality gates. It has no subscription, but Claude Code itself still needs your own paid Anthropic plan. The Kit does not migrate Grok configuration for you. It gives the new Claude setup a consistent way to ship once the migration is sound.

Posted by @speedy_devv