Grok Build CLI: Teaching Grok Your Project (AGENTS.md)
The difference between a generic agent and one that feels like a teammate is context. AGENTS.md is how you give Grok that context once, so it follows your conventions in every future session without you repeating yourself.
Just arriving? Start at Grok Build CLI: Zero to Hero (Start Here).
What it is
An AGENTS.md file is plain Markdown that Grok reads and appends to its system prompt. Whatever you write becomes part of the instructions Grok follows in that directory tree: coding standards, build and test commands, architecture rules, PR conventions.
It is discovered hierarchically. Global rules apply everywhere, repo rules apply to the project, and directory rules take the highest priority. Grok also reads CLAUDE.md for compatibility, so migrating from Claude Code is friction free.
Write actionable rules, not documentation
The best AGENTS.md files are specific and imperative. "Use TypeScript" beats "use modern JavaScript." "Run npm test before committing" beats "test your code." Keep it to instructions Grok can act on.
Deeper files win
When Grok runs inside a subdirectory, it loads every AGENTS.md from the repo root down to your current directory, and they accumulate. If the root says "use styled-components" but a component folder says "use CSS modules," the deeper file wins because it appears later in the prompt. This is how a monorepo gives its frontend and backend packages different rules.
One-off rules for a single run
Need a constraint just for this session without touching any files? Append it with --rules. It stacks on top of whatever AGENTS.md files were discovered.
The rest of the .grok directory
AGENTS.md is the headline, but the .grok/ folder in your repo can also carry project-scoped MCP servers (.grok/config.toml), skills, hooks, agent definitions, and an LSP config. Each file is capped at 10,000 characters, gitignored files are skipped, and grok inspect shows you exactly which rules loaded and from where.
Commit AGENTS.md to the repo so the whole team benefits. Keep personal overrides in ~/.grok/ or a gitignored local file.
Continue the series
The full series
- Grok Build CLI: Zero to Hero (Start Here)
- Grok Build CLI: Sessions, Rewind and Compaction
- Grok Build CLI: Slash Commands and Keyboard Mastery
- Grok Build CLI: Teaching Grok Your Project (AGENTS.md) (you are here)
- Grok Build CLI: Models and Custom Endpoints
- Grok Build CLI: Extending Grok with MCP, Skills, Plugins and Hooks
- Grok Build CLI: Cross-Session Memory
- Grok Build CLI: Subagents, Plan Mode and Background Work
- Grok Build CLI: Headless Mode and Automation
- Grok Build CLI: Sandbox and Permissions
- Grok Build CLI: IDE Integration with ACP
- Grok Build CLI: The Evolution (Power-User Version History)