Mistral Vibe Loads AGENTS.md — Stop Replacing Its System Prompt

For roughly half a year I configured Mistral Vibe in this WordPress monorepo the wrong way. I had written detailed, repo-specific instruction files — one at the project root, one for each theme — and wired them in by setting system_prompt_id = "vibe" in every .vibe/config.toml. It worked. The agent followed the rules. But it was the wrong mechanism, and it quietly cost me the thing I was paying Mistral for: their built-in agentic system prompt. This post explains what Vibe actually does with AGENTS.md, since when, and why replacing the system prompt is almost never what you want.

Quick Reference: Two Different Mechanisms

Mistral Vibe has two completely separate ways to feed it instructions. Confusing them is the entire mistake. Here is the distinction in one table.

Mechanism	What it does	When to use it
AGENTS.md files	Adds your instructions on top of Vibe’s built-in agent prompt. Loaded automatically from trusted folders.	Almost always. This is the home for project-specific rules.
system_prompt_id in config.toml	Replaces the entire built-in system prompt (prompts/cli.md) with your own markdown file.	Almost never. Only if you are deliberately rebuilding the agent’s core behaviour from scratch.

I was using the second mechanism to do the first mechanism’s job. My .vibe/prompts/vibe.md files were really just project instructions — “follow these block-pattern rules,” “run WP-CLI from the Trellis VM,” “no AI attribution in commits.” But by loading them as the system prompt, I was overwriting Mistral’s carefully tuned tool-use, planning, and editing instructions with a thin instruction sheet that said nothing about how to actually be an agent.

How Vibe Resolves Its System Prompt

Reading the Vibe source makes the behaviour unambiguous. The default value of system_prompt_id is cli — Mistral’s built-in agent prompt. When you set it to anything else, Vibe loads a markdown file with that name from .vibe/prompts/ and uses it instead of the default. There is no merge. Your file becomes the whole system prompt.

# vibe/core/config/_settings.py
system_prompt_id: str = SystemPrompt.CLI   # default = "cli"

@property
def system_prompt(self) -> str:
    return load_system_prompt(self.system_prompt_id)   # loads .vibe/prompts/<id>.md, replacing the default

The AGENTS.md path is entirely different. Vibe walks up from your current directory to the trust root, collects every AGENTS.md it finds, and appends them to the system prompt as a clearly labelled “project instructions” section — keeping the built-in cli prompt fully intact underneath.

# vibe/core/system_prompt.py (paraphrased)
sections = [ built_in_cli_system_prompt ]      # the default agent stays
...
project_docs = mgr.load_project_docs()         # every AGENTS.md, cwd up to trust root
for doc_dir, doc_content in project_docs:
    doc_sections.append(f"Contents of {doc_dir}/AGENTS.md:\n\n{doc_content}")
# appended as "## Project instructions (checked into the codebase)"

This is exactly how Claude Code treats CLAUDE.md: the model keeps its own operating instructions and your repo rules ride on top. I had assumed for months that Vibe simply didn’t do this — that it had no CLAUDE.md equivalent and the only lever was the system prompt. That assumption was wrong, and it’s worth explaining why it was so easy to get wrong.

Since When Has Vibe Loaded AGENTS.md?

Digging through the Vibe git history, the capability is older than I expected — and considerably older than the documentation for it. Here is the actual timeline.

Date	Version	What landed
9 Dec 2025	Initial release	Runtime loading of a trusted project instruction doc into the system prompt (_load_project_doc) existed in the very first public commit.
8 Jan 2026	v1.3.4	A configurable list of trusted instruction filenames (TRUSTABLE_FILENAMES).
17 Feb 2026	v2.2.0	AGENTS.md became the canonical, named project-instruction file (AGENTS_MD_FILENAMES).
16 Mar 2026	v2.5.0	Full multi-level loading: every AGENTS.md from cwd up to the trust root, merged with priority, in a dedicated wrapper.
5 May 2026	v2.9.4	AGENTS.md finally documented in the README.md.
17 Jun 2026	PR #813 (open)	An /init command that scans the repo and authors an AGENTS.md for you. (My PR — not yet merged.)

So AGENTS.md has been the right answer since v2.2.0 in mid-February 2026 — about four months before I finally migrated — and a generic “load a project instruction file at runtime” mechanism shipped in the very first release in December 2025. The feature was never hidden in code. It was hidden in the changelog.

It Was Mostly a Documentation Gap

The honest root cause: the feature shipped in February but wasn’t written into the README until v2.9.4 on 5 May 2026 — a three-month gap. If you set up your project config before May, the only instruction mechanism you’d have seen documented was the custom system prompt. That’s exactly what I did. The current README now states the distinction plainly:

You can create AGENTS.md files to add custom instructions. You can also replace the entire system prompt. […] Instructions in AGENTS.md override the default system prompt. […] Custom system prompts entirely replace the default one (prompts/cli.md).

Mistral Vibe README, v2.17

“Add custom instructions” versus “replace the entire system prompt” — once that sentence exists, the choice is obvious. Before it existed, it wasn’t. If you’ve been running Vibe since early 2026, it’s worth checking your own config.toml files for a stale system_prompt_id.

Why Replacing the System Prompt Is the Wrong Call

The built-in cli prompt is not boilerplate. It is the instruction set that makes Vibe a competent agent: how to use tools, when to plan, how to edit files safely, how to read before writing, how to scope commits, how to behave in headless mode. When you point system_prompt_id at a file that only says “here are my block-pattern rules,” all of that disappears. You keep your rules and lose the agent.

There’s a second, subtler cost. A custom system prompt is a fork. Every time Mistral improves the default cli prompt — better tool use, new safety behaviour, refined editing heuristics — you get none of it, because your file replaced it. With AGENTS.md you’re always running the latest built-in agent plus your rules. You’re a consumer of upstream improvements, not stranded on a snapshot.

The Migration, Step by Step

This repo had three Vibe-configured locations: the monorepo root, the Sage 11 theme, and the block theme. Each had a .vibe/prompts/vibe.md loaded as the system prompt. The migration for each was identical.

1. Merge the content. Move every still-accurate, repo-specific rule from vibe.md into the matching AGENTS.md, de-duplicating against what was already there. Watch for stale rules — my oldest vibe.md still referenced block categories and a text domain that had since changed, so I deliberately left those behind rather than copy them forward.
2. Restore the default prompt. Set system_prompt_id = "cli" in each config.toml. This step is mandatory: if you delete vibe.md while the config still points at "vibe", Vibe throws MissingPromptFileError on launch.
3. Delete the file. Remove vibe.md and its now-empty prompts/ directory.

The config change is one line per location:

# .vibe/config.toml
- system_prompt_id = "vibe"   # loaded vibe.md AS the whole system prompt
+ system_prompt_id = "cli"    # built-in agent prompt; AGENTS.md layers on top

One nuance worth calling out: don’t blindly paste a 700-line vibe.md into AGENTS.md. Because AGENTS.md now supplements the built-in prompt rather than replacing it, it should carry only what’s genuinely repo-specific. Anything that was really just re-describing how to be an agent can go — Mistral’s own prompt already covers it.

AGENTS.md Behaves Like CLAUDE.md

If you already structure repos for Claude Code, there is nothing new to learn. The placement and precedence rules map almost one-to-one.

• User-level: ~/.vibe/AGENTS.md applies to every project on your machine.
• Project-level: an AGENTS.md in any directory from your cwd up to the trust root is loaded automatically.
• Precedence: closer directories override more distant ones, so a theme-level AGENTS.md can refine the monorepo root’s rules.
• Trust-gated: files are only loaded for trusted folders — the same security model that protects you from a hostile repo injecting instructions.
• Subdirectory injection: when Vibe reads a file in a subtree that has its own AGENTS.md, it pulls that file in on demand — so monorepos with per-package rules just work.

The practical upshot for a monorepo like this one: keep cross-cutting rules (commit hygiene, deployment, Trellis VM access) in the root AGENTS.md, and put theme-specific block, pattern, and styling rules in each theme’s own AGENTS.md. Vibe assembles the right combination based on where you’re working.

Takeaways

• Mistral Vibe does load AGENTS.md at runtime, the way Claude Code loads CLAUDE.md — and has since v2.2.0 in February 2026.
• Use AGENTS.md for repo-specific rules. It adds to the built-in agent prompt.
• Only use a custom system_prompt_id if you intend to replace Vibe’s entire agent behaviour — which you almost never do.
• If you adopted Vibe before May 2026, audit your config.toml for a custom system_prompt_id that should be "cli".
• When migrating, move only genuinely repo-specific guidance into AGENTS.md and drop anything that merely re-describes general agent behaviour.

The lesson isn’t really about Mistral Vibe. It’s that a powerful, undocumented feature is functionally invisible. The capability shipped in December and was named in February, but until it reached the README in May, the “obvious” path was the wrong one. Re-reading your tool’s changelog occasionally is cheaper than running a fork of its system prompt for six months.