Grok Build native reference
Start with the Grok setup.
Native mappings
Agents
- Kept:
name,description,model, nativetools,disallowedTools,skills,effort,maxTurns,background,permissionMode,hooks, and supported fields underx-grok. effort:low,medium,high,xhigh, ormax.- Portable
canandtoolsmap to verified native allowlist aliases and disable unrequested MCP bridge tools. - Explicit bridge IDs and
x-grok.toolskeep their native choice. - A capability with no exact mapping fails and names the agent.
- An unknown native tool fails, because Grok restores its full toolset for an unresolved name.
- An empty restriction is rejected, because native empty
toolsinherits every tool. - To keep an existing restriction, put verified aliases or IDs in
toolsorx-grok.tools.
Skills and names
- Kept:
name,description,when-to-use,paths,allowed-tools,argument-hint,user-invocable,disable-model-invocation,metadata,license,compatibility. Bundled files are copied unchanged. allowed-toolsdescribes use; it enforces nothing.user-invocable: falsealso hides the skill from model discovery.- Skill model and effort overrides are not applied.
- Skill and command names become lowercase
a-z, digits, and hyphens, up to 64 characters. A skill can fall back to its folder name. - A name with no valid native form is rejected before any file is written.
MCP servers
- Written as
[mcp_servers.<name>]. - Stdio keeps
command,args,env,cwd. Remote keepsurl,headers, and explicit HTTP or SSE transport. disabledbecomes the inverseenabled.startup_timeout_secandtool_timeout_secstay in seconds.- Environment references stay as text for Grok to expand.
x-grokcarries native extras, such as authentication and timeouts.x-grok.headers_helperkeeps a string command that supplies dynamic HTTP request headers, supported since Grok Build 1.0.88. Import keeps the nativeheaders_helperunderx-grok; project and global sync write it back.- Portable
descriptionandtimeoutgive coverage notes (no exact mapping).
Project settings
- Only
permissions.allow,permissions.ask, andpermissions.denyare written, to[permission]. x-grok.permissionandx-grok.pluginscarry native project configuration.- Existing MCP servers and unrelated keys are kept.
- Unsupported: project model, effort, permission default mode, session retention.
- Ignore, review, and environment specs have no native output.
- User scope: portable voice settings write
ui.voice_capture_modeandui.voice_stt_language. Grok has no dictation on/off key.
Hooks
- Events: the 14 in the hooks page Events table, plus
StopCancelled. The page leaves it out, but Grok 1.0.4 added it (changelog, event list). It runs instead ofStopwhen a turn ends without completing. - Fields: native PascalCase
event, optionalmatcher, command, safely quotedargs, timeout in seconds, per-handlerenv. - Sync adds
AGNOSTIC_AI_TARGET=grok. Grok providesCLAUDE_PROJECT_DIRandGROK_WORKSPACE_ROOT. - A matcher on
StoporUserPromptSubmitdoes nothing and gives a note. - Errors fail open. Native explicit denies block, depending on the event.
- Portable
onandmatchhooks are not translated. Use Grok-native events and its reply protocol. - Project hooks need Grok's hook trust approval.
- Windows: a shared script path that needs shell-specific quoting (such as a path with spaces) needs an explicit native wrapper command. Sync refuses a rewrite it cannot preserve. Existing native invocation commands keep their quoting.
Import
Run agnostic-ai import grok before the first sync of a native project. It uses the configured output directories.
- Reads: root and scoped rule, agent, skill, and command directories, resources, native hook JSON, MCP tables, compact permission lists, plugins.
- Plugins stay under
x-grok.plugins.x-grok.hookskeeps each hook file's groups and handler fields. - An unsupported hook handler type fails import.
- Standalone MCP credentials become environment references through the shared credential filter.
- MCP
descriptionis left out with a note, because Grok ignores it. The same server imported from Claude Code or Cursor keeps its description. - Global sync preserves the original native file.
- Inline agent MCP and hook metadata keep their native form. Literal credentials there and in standalone hooks are refused before any write (setting value rule). Errors name the path, never the value.
- Hook
envvalues pass through literally, so${TOKEN}there reads nothing. Use it in the hookcommandorurl, where Grok expands variables. - Adapter tests cover the round trip: import, sync, lint,
sync --check.
Global configuration
agnostic-ai sync --global --only grokwrites$GROK_HOME/AGENTS.md,skills/,agents/,hooks/,hook-scripts/, andconfig.toml.GROK_HOMEdefaults to~/.grokand must be absolute when set.- Global commands and permission lists are not written. Global effort is unsupported.
- The global model maps to
[models].default. - MCP servers and the model share one planned write of the config file. Sync owns individual servers and the model key, keeps other text and private file modes, checks for concurrent edits, and removes only unchanged owned values.
agnostic-ai import --global grokreads supported settings, MCP, and hooks. It skips literal credentials.