One agent-neutral home for coding-agent instructions, rules, skills and MCP servers

[mike-echo-oscar-whiskey]

The problem

Omarchy pre-wires launchers for thirteen coding agents and lets you pick a default with omarchy default agent <name>. Switching agents is one command; switching their configuration is not. Each agent keeps its own instruction file, rules, skills, commands and MCP servers in its own place and its own format:

• Claude Code reads CLAUDE.md and ~/.claude/, with @path imports and JSON settings.
• Codex reads AGENTS.md and ~/.codex/, with TOML settings and a size cap on the instructions it loads.
• Gemini CLI and Antigravity read GEMINI.md and ~/.gemini/.
• The others each have their own variant.

So anyone who uses more than one agent, or tries a new one from the menu, either keeps several copies of the same working agreements in sync by hand, or finds that the agent they just switched to knows none of their conventions. Symlinking one file into every location does not hold up: the file names differ, import syntax and size limits differ, some clients deliberately skip symlinked config, and settings and MCP files are not even the same format.

Omarchy already solves half of this for one case

The manual says the Omarchy skill is symlinked into the skill directories of Claude Code (~/.claude/skills), Codex (~/.codex/skills), Pi and Antigravity. The idea is right: Omarchy knows which agents are installed and where each one looks. This proposal extends it from one bundled skill to the user's own configuration.

The proposal

Ship (or offer under Install > AI) one agent-neutral source of truth for the user's agent configuration, plus a step that renders it into each installed agent's native files:

1. One source. A single directory, for example ~/.config/agents/, holding plain-Markdown instructions, rules, skills and commands, and the MCP server list in one format.
2. Generated, not linked. A sync step writes each agent's own files from that source, translating file names, formats and import syntax, and respecting each agent's size limits by inlining or splitting.
3. Hand edits are safe. The sync writes only files it owns, or a clearly marked managed block inside a shared file; it never deletes a file it did not create, and it stops with a message rather than overwriting a hand edit.
4. Wired into Omarchy's flow. Choosing or installing an agent through the menu runs the sync, so a newly selected agent starts with the same instructions, skills and MCP servers as the previous one.
5. Dotfile-manager friendly. Only the source directory needs to be tracked in a dotfile repository; the generated files are reproducible.

Prior art

agnostic-ai (MIT) does this today. It reads a .agnostic-ai/ directory, per project or user-wide with sync --global in ~/.agnostic-ai/, and generates native configuration for 25 tools, Claude Code, Codex and Gemini CLI among them. It writes only between its own markers in shared files, resolves or inlines @path imports for tools that cannot follow them, and keeps an instruction word budget. It is young and moving fast (v0.81 at the time of writing), so it could be offered as an optional install under Install > AI, or serve as the reference for a small Omarchy-native equivalent built on the skill symlinking that already exists.

Why it fits Omarchy

Omarchy's AI approach is not to pick a favourite and to make every agent one keystroke away. Configuration that follows the user from agent to agent is the missing piece: it makes trying a different agent from the menu cheap instead of a migration.

Open questions

• Ship a tool such as agnostic-ai as an optional package, or a minimal Omarchy-native sync limited to the pre-wired agents?
• User-level only, or also a per-project convention (e.g. a repository-root AGENTS.md that every agent reads)?
• Should memory, the notes an agent keeps between sessions, be in scope, or stay each agent's own?

[jimy-r]

Generating the files is where I ended up too, for a reason worth adding to the list. I keep one set of role definitions and one file of project facts, and I wanted each agent definition to import both. Import lines turned out not to be expanded inside agent definition files, so the agents were running without the context the file appeared to include. Nothing failed. The fix was a render step that inlines the sources into each agent file, with a validator over the rendered output.

Two things I would carry over. A check that generated output still matches its source is what makes hand edits safe, since it turns a silent overwrite into a loud stop. And a shared root AGENTS.md is a weaker convention than it looks. In my probes Claude Code loaded a nested CLAUDE.md and ignored a nested AGENTS.md that had no sibling CLAUDE.md, so what each tool reads has to be tested per tool.

I would leave memory out. It is state each agent writes under its own rules, and syncing it means reconciling two writers.

I maintain a reference architecture that documents this pattern at https://github.com/jimy-r/agent-workspace-architecture/blob/main/PATTERNS.md#17-one-canonical-copy-and-pointers-from-everywhere-else

Drafted with Claude Code and reviewed by me before posting.