One AGENTS.md, Every Model

The Problem

Your models read different playbooks

Each model has its own tool names, quirks, and preferred patterns. Maintaining separate files means they inevitably drift — and your agents start making subtly different mistakes.

1

Write the template

Create a single agents.mg file. Shared project rules go in the main body. Use Margarita's if blocks to add model-specific sections that are only rendered when that model is targeted.

agents.mg

# agents.mg
---
description: Universal agent instructions that adapt to Claude or Gemini.
parameter: model (string): Target model — "claude" or "gemini".
---

# Shared rules — always rendered for every model
<< # Margarita – Agent Guide >>

<<
## Project Overview
This repo contains three packages: Margarita (templating),
and Margarita (agentic workflows).
All packages live under `packages/`.
>>

<<
## Repository Layout
```
packages/
  margarita/   core templating engine (Python)
  margarita/   agentic .mgx runner
docs/          shared documentation source
```
>>

<<
## Running Tests
```bash
pip install -e packages/margarita[dev]
pytest packages/
```
>>

# Model-specific sections — only one block is ever rendered
if model == "claude":
  <<
  ## Claude Code – Tools & Workflow

  ### File Operations
  Use the purpose-built tools for every file operation — never shell
  out for things the tools handle directly:
  - **Read** before touching any file. No exceptions.
  - **Edit** for targeted changes; **Write** only for new files.
  - **Glob** / **Grep** to locate files — never `find` via Bash.
  - **Bash** for test runs, git commands, and build steps only.

  ### Task Management
  For any task with more than two steps, start with **TodoWrite**.
  Mark each item `in_progress` before starting and `completed` when
  done. Keep the list current throughout the session.

  ### Guardrails
  - Make the smallest change that solves the problem. Do not clean up
    surrounding code that wasn't part of the request.
  - Never commit unless explicitly asked. Never use `--no-verify`.
  - If a pre-commit hook fails, fix the root cause — don't bypass it.
  - After touching `margarita/`, run `pytest packages/margarita` and
    confirm the suite passes before calling the task done.
  >>

if model == "gemini":
  <<
  ## Gemini – Grounding & Response Style

  ### Search Before You Assume
  Before using any third-party library, API endpoint, or version
  number, call `@google_search` to verify it is current. Do not
  rely on training-data knowledge for fast-moving dependencies.
  If search returns conflicting results, surface them — don't pick one.

  ### Response Format
  - Lead with code, not explanation. Put prose after the block.
  - Every code snippet must have an explicit language tag on the fence.
  - If the task is ambiguous, ask one focused clarifying question
    rather than making assumptions and proceeding.
  - Keep answers short. If detail is needed, offer to expand.

  ### Citations
  When referencing a doc page, RFC, or external resource, include
  the URL inline so the team can verify. Prefer official documentation
  over blog posts or Stack Overflow. Flag anything that may be stale.
  >>

# Shared code style — always rendered for every model
<<
## Code Style
- Python 3.11+, type hints on all public functions.
- Black formatter, line length 88.
- Every public function needs a docstring.
>>

2

Render for each model

Pass the model variable via the --context flag and pipe the output straight into the right file. Drop this into a Makefile or CI step and your agent instructions stay fresh on every commit.

Claude → CLAUDE.md

# Render instructions for Claude Code
margarita render agents.mg \
  --context '{"model": "claude"}' \
  > CLAUDE.md

Gemini → AGENTS.md

# Render instructions for Gemini
margarita render agents.mg \
  --context '{"model": "gemini"}' \
  > AGENTS.md

3

See what each model receives

Both files share the same project overview, layout, test commands, and code style rules. Only the model-specific working section differs — everything else stays perfectly in sync.

CLAUDE.md

Rendered with model = "claude". The Gemini section is omitted entirely — Claude only sees what's relevant to it.

# Margarita – Agent Guide

## Project Overview
This repo contains three packages: Margarita (templating),
and Margarita (agentic workflows).
All packages live under `packages/`.

## Repository Layout
```
packages/
  margarita/   core templating engine (Python)
  margarita/   agentic .mgx runner
docs/          shared documentation source
```

## Running Tests
```bash
pip install -e packages/margarita[dev]
pytest packages/
```

## Claude Code – Tools & Workflow    ◄ model-specific

### File Operations
Use the purpose-built tools for every file operation — never shell
out for things the tools handle directly:
- **Read** before touching any file. No exceptions.
- **Edit** for targeted changes; **Write** only for new files.
- **Glob** / **Grep** to locate files — never `find` via Bash.
- **Bash** for test runs, git commands, and build steps only.

### Task Management
For any task with more than two steps, start with **TodoWrite**.
Mark each item `in_progress` before starting and `completed` when
done. Keep the list current throughout the session.

### Guardrails
- Make the smallest change that solves the problem. Do not clean up
  surrounding code that wasn't part of the request.
- Never commit unless explicitly asked. Never use `--no-verify`.
- If a pre-commit hook fails, fix the root cause — don't bypass it.
- After touching `margarita/`, run `pytest packages/margarita` and
  confirm the suite passes before calling the task done.

## Code Style
- Python 3.11+, type hints on all public functions.
- Black formatter, line length 88.
- Every public function needs a docstring.

AGENTS.md

Rendered with model = "gemini". The Claude section is omitted entirely — Gemini only sees what's relevant to it.

# Margarita – Agent Guide

## Project Overview
This repo contains three packages: Margarita (templating),
and Margarita (agentic workflows).
All packages live under `packages/`.

## Repository Layout
```
packages/
  margarita/   core templating engine (Python)
  margarita/   agentic .mgx runner
docs/          shared documentation source
```

## Running Tests
```bash
pip install -e packages/margarita[dev]
pytest packages/
```

## Gemini – Grounding & Response Style ◄ model-specific

### Search Before You Assume
Before using any third-party library, API endpoint, or version
number, call `@google_search` to verify it is current. Do not
rely on training-data knowledge for fast-moving dependencies.
If search returns conflicting results, surface them — don't pick one.

### Response Format
- Lead with code, not explanation. Put prose after the block.
- Every code snippet must have an explicit language tag on the fence.
- If the task is ambiguous, ask one focused clarifying question
  rather than making assumptions and proceeding.
- Keep answers short. If detail is needed, offer to expand.

### Citations
When referencing a doc page, RFC, or external resource, include
the URL inline so the team can verify. Prefer official documentation
over blog posts or Stack Overflow. Flag anything that may be stale.

## Code Style
- Python 3.11+, type hints on all public functions.
- Black formatter, line length 88.
- Every public function needs a docstring.

🔁

Single source of truth

Shared rules — project layout, test commands, code style — live in one place. Update once and both model files stay in sync.

🔨

Model-aware branching

Use Margarita's if blocks to tailor tool names, behavioral hints, and search instructions to each model's capabilities.

🚀

CI-friendly

Drop the render commands into a Makefile target or CI step. Generated files are committed, so models always have fresh instructions.

Ready to unify your agent instructions?

Margarita handles the branching. You write the rules once.

Read the Margarita Docs Next Guide: Custom Agent Loop →

One AGENTS.md,Every Model