Grok Build (grok)

Select Grok explicitly and keep its project instructions visible to Git. Grok skips ignored rule files, so it is excluded from the default targets.

First rule

Create agnostic-ai.yaml:

version: 1
targets: [grok]
gitignore:
  enabled: true
  commit: [grok:instructions]

Create .agnostic-ai/rules/style.md:

---
name: style
---

Use Conventional Commits for commit subjects.

Run agnostic-ai sync, then agnostic-ai sync --check. Read .grok/rules/style.md and run git check-ignore --no-index .grok/rules/style.md: it should report no matching ignored path. A root or global ignore pattern can still hide the file. Sync rejects that case before emitting Grok output; remove the matching pattern yourself. Explicitly disabling agnostic-ai's ignore management is also supported when your own ignore policy keeps the rules visible. The check uses Grok's root .gitignore and global ignore file, not nested ignore files or .git/info/exclude. It conservatively requires parent directories to be re-included before a file below an ignored directory.

Install and open the CLI using the official setup guide. Grant project trust through Grok, then verify the rule in a session. Sync does not grant trust or run Grok.

Output

Scoped skills, agents, and commands use the corresponding directory below their source scope. Rules apply when Grok discovers that directory while walking from its working directory to the repository root. File glob conditions have no native rule equivalent; use a whole directory scope.

Output overrides use outputs.grok.dir, rules-dir, agents-dir, skills-dir, commands-dir, hooks-dir, mcp-file, and conf-file. conf-file separates permission settings from the MCP destination. A custom destination must still be a location Grok reads. Rule visibility checks include custom paths.

Native mappings

Agents carry name, description, model, native tools, disallowedTools, skills, effort, maxTurns, background, and the supported native fields under x-grok. Effort accepts low, medium, high, xhigh, or max. Portable can and tools use verified native allowlist aliases and disable unrequested MCP bridge tools. Explicit bridge IDs and x-grok.tools retain their native choices; a capability without an exact mapping fails with the agent name. Unknown native tool entries fail because Grok restores its full toolset for an unresolved name. Empty restrictions are rejected because native empty tools inherit all tools. To preserve an existing Grok restriction, use verified native aliases or IDs in tools or x-grok.tools.

Skills keep name, description, when-to-use, paths, allowed-tools, argument-hint, user-invocable, disable-model-invocation, metadata, license, and compatibility. Bundled files are copied unchanged. allowed-tools describes use and does not enforce permission. user-invocable: false also hides a skill from model discovery. Skill model and effort overrides are not applied by the verified contract.

Grok converts skill and command names to lowercase a-z, digits and hyphens, with a 64-character limit. Skills can fall back to their folder name. Sync rejects names with no valid native form before writing files.

MCP servers become [mcp_servers.<name>]. Stdio keeps command, args, env, and cwd. Remote servers keep url, headers, and explicit HTTP or SSE transport. disabled becomes the inverse native enabled. Native startup_timeout_sec and tool_timeout_sec stay seconds. Environment references remain text for Grok to expand. Native extras under x-grok include the source-backed authentication and timeout fields. Portable description and timeout produce coverage notes because they have no exact native mapping.

Project settings write only permissions.allow, permissions.ask, and permissions.deny to [permission]; x-grok.permission and x-grok.plugins carry native project configuration. Existing MCP servers and unrelated configuration keys are retained. Project model, effort, permission default mode, and session retention are unsupported. Ignore, review, and environment specs have no native output.

Hooks use native PascalCase event and optional matcher, command text, safely quoted args, timeout in seconds, and per-handler env. Sync adds AGNOSTIC_AI_TARGET=grok to generated handlers. Grok provides CLAUDE_PROJECT_DIR and GROK_WORKSPACE_ROOT. A matcher on Stop or UserPromptSubmit has no effect and produces a note. Hook errors fail open; native explicit denies block according to the event. Portable on/match hooks are not translated in this adapter. Use Grok-native events and its documented reply protocol. Project hook execution also requires Grok's hook trust approval.

On Windows, shared script paths that need shell-specific quoting, such as paths with spaces, require an explicit native wrapper command. Sync refuses an automatic 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 reads root and scoped rule, agent, skill, and command directories, resources, native hook JSON files, MCP tables, compact permission lists, and plugins. Plugins are retained under x-grok.plugins from the configured settings destination. Native hook groups are retained under x-grok.hooks, preserving each file's groups and handler fields. Unsupported hook handler types fail instead of being silently discarded. Imported standalone MCP credentials become environment references through the shared credential filter.

Inline agent MCP and hook metadata keep their native form. Import refuses literal credentials there, and in standalone hooks, before writing the source file. Hook env values are passed through literally, so putting ${TOKEN} there does not read the process environment. Inherit credentials from the process and reference them in hook command or url, where Grok expands variables. Import errors identify the native path without printing credential values.

Import uses the configured output directories. Importing emitted files into fresh source directories, syncing again, linting, and running sync --check are covered by the adapter tests.

Global configuration

agnostic-ai sync --global --only grok writes $GROK_HOME/AGENTS.md, skills/, agents/, hooks/, hook-scripts/, and config.toml. GROK_HOME defaults to ~/.grok and must be absolute when set. Global commands and permission lists are not emitted. The portable global model maps to [models].default; global effort is unsupported.

Global MCP servers and the default model share one planned config write. Sync owns individual servers and the model key, preserves other text and private file modes, checks for concurrent edits, and removes only unchanged owned values. agnostic-ai import --global grok reads the supported settings, MCP, and hook surfaces. Literal credentials are skipped by global import.

Protected paths

Not enforced. Use an instruction rule or explicit permission rules. See protected-path alternatives.