Skip to content

Instantly share code, notes, and snippets.

@ansulev

ansulev/grok-migration.md

Last active July 12, 2026 16:49
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save ansulev/4e07bfc7d4b1aee71c8e3227efcb98b6 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save ansulev/4e07bfc7d4b1aee71c8e3227efcb98b6 to your computer and use it in GitHub Desktop.
Download ZIP
Raw
grok-migration.md

Grok Build Migration Guide & Shared Agent Context

Purpose: SoT for migrating from Claude Code → Grok Build (and multi-model setup with Codex, etc.)
Author: [Angel Sulev]

1. Overall Setup Philosophy

  • Maintain a model-agnostic central SoT at ~/.agents/skills/ (rules, commands, hooks, identity, agents, styles, etc.).
  • Use symlinks for tool-specific discovery:
    • ln -s ~/.agents/skills ~/.grok/skills
    • ln -s ~/.agents/skills ~/.claude/skills
    • Same for ~/.agents/commands/, hooks, agents, etc.
  • Grok Build has excellent Claude Code compatibility — it auto-loads AGENTS.md, CLAUDE.md, .claude/rules/, skills, plugins, hooks, MCP servers with zero extra config.

2. Key Grok Build Features to Leverage

  • Plan Mode: Always start complex tasks in plan mode. Review/approve/comment before execution.
  • Subagents: Spawn parallel independent agents (up to ~8) with dedicated personas/contexts for research, testing, etc.
  • Skills: Use /skillify to capture successful workflows into reusable slash commands.
  • Hooks: Lifecycle on edits/tool calls — place in shared dir.
  • Memory & Git Integration: Strong terminal-native support (builds, tests, sandbox).
  • Headless Mode: For scripting/CI.
  • Inspection: Run grok inspect (or equivalent) to see loaded configs/skills.

3. Migration Checklist from Claude Code

  1. Install: curl -fsSL https://x.ai/cli/install.sh | bash
  2. Symlink shared ~/.agents/ structure (see above).
  3. Enhance root AGENTS.md (and project-level ones):
    • Global identity, coding standards, STYLE.md content.
    • Add Grok-specific guidance: "Prefer plan mode + subagents for parallel work", "Use /skillify on successful flows".
  4. Test skills/hooks — tweak matcher descriptions if auto-trigger differs slightly.
  5. Run side-by-side with Claude (deep reasoning) and Grok (speed + parallelism).

4. Best Practices for This Agent

  • Context Priority: Keep AGENTS.md concise but authoritative. Put critical rules at the top or bottom as needed.
  • Workflow: For new tasks → Plan → Subagents where helpful → Approve → Execute → /skillify reusable parts.
  • Multi-Model: Feed this file + tool-specific refinements into Claude/Codex/Grok sessions. Maintain one master set.
  • Testing: Start in small repos. Use grok inspect frequently.
  • Evolution: Periodically review and /skillify high-value workflows from Claude into the shared SoT.

5. Free Trial / Usage Notes

  • Grok 4.5 in Grok Build is available for limited free trial (no top-up required for basic testing).
  • Monitor limits; upgrade for heavy use.
  • API key works for direct integration.

Grok Build Access Notes (July 2026)

  • Full Grok Build Beta (TUI with plan mode, subagents, etc.) currently requires SuperGrok / X Premium+ subscription.
  • Limited free access exists via:
    • Web: grok.com/build
    • Cursor with xAI API key
    • Basic API calls
  • xAI API key alone does not unlock the full CLI beta.
  • Start trial if needed, test thoroughly, then decide.

Core Identity / Always Follow:

  • Be precise, plan-first, leverage parallelism.
  • Capture reusable knowledge aggressively via skills.
  • Maintain compatibility with Claude ecosystem while optimizing for Grok strengths.

Save this file and reference it in your prompts (e.g., "Follow instructions in grok-build-migration.md"). Update it as you discover more.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment