Agent-Agnostic Config
What happens to your AI coding setup when you switch agents?
The Problem
Every AI coding agent has its own config format. Build everything in .claude/ and you're locked in. Build in .cursor/rules/ and Gemini can't see it. The knowledge is the same — the wiring is different.
Agent-specific dirs = vendor lock-in
Shared knowledge base + thin adapters = portability
Standards Alignment
The Agentic AI Foundation (AAIF) under the Linux Foundation standardizes three layers. We adopt them where mature and keep project-specific config where no standard exists yet.
| Standard | Governs | Our Adoption |
|---|---|---|
AGENTS.md | Project instructions | AGENTS.md at root (Codex, Copilot, Cursor, Gemini read it) |
| Agent Skills | Modular capabilities | .agents/skills/ with standard SKILL.md frontmatter |
| MCP | Tool connectivity | .mcp.json for server config |
What the standards don't cover yet: rules (always-loaded constraints), hooks (automated enforcement), commands (workflow triggers), writing voices, contexts. These stay in .ai/ until standards emerge.
Architecture
Three layers: AAIF standard, project-specific, agent adapters.
.agents/ AAIF STANDARD — cross-tool skills
└── skills/ 13 procedures with SKILL.md frontmatter
├── content-flow/
├── copywriting/
└── ...
.ai/ PROJECT-SPECIFIC — beyond standards
├── rules/ 14 enforcement rules
├── hooks/ 8 automated validators
├── commands/ 24 workflow triggers
├── agents/ Writing voices and archetypes
├── contexts/ Reusable context blocks
└── ...
AGENTS.md AAIF standard root file
CLAUDE.md ──@import──→ .ai/rules/* Claude Code reads this
GEMINI.md ──@import──→ .ai/rules/* Gemini CLI reads this
.claude/rules/ → symlinks to .ai/rules/ (auto-loaded by Claude Code)
.claude/commands/ → proxies to .ai/commands/ (slash commands)
.cursor/rules/ → generated .mdc files (needs frontmatter wrapper)
.windsurf/rules/ → symlinks to .ai/rules/ (same format)
Why Two Directories
| Directory | What | Standard | Edited By |
|---|---|---|---|
.agents/skills/ | Procedures any agent can discover | AAIF Agent Skills spec | Human + AI |
.ai/rules/ | Constraints auto-loaded per session | No standard yet | Human |
.ai/hooks/ | Shell scripts that fire on events | No standard yet (Claude-specific) | Human |
.ai/commands/ | Workflow triggers | No standard yet | Human + AI |
.ai/agents/ | Writing voice definitions | No standard yet | Human |
.ai/contexts/ | Reusable context blocks | No standard yet | Human |
Decision: Adopt .agents/skills/ for skills because it's the AAIF standard — Codex reads it natively, Copilot is adopting it, other tools will follow. Keep .ai/ for everything else because no standard covers rules, hooks, or commands yet. When standards emerge, migrate.
Root Entry Points
Each agent reads one root file. Keep these thin — route to shared content, don't duplicate it.
| File | Agent | Import Support | Strategy |
|---|---|---|---|
AGENTS.md | Codex, Copilot, Cursor, Gemini | None (Codex) / varies | AAIF standard. Self-contained for Codex. |
CLAUDE.md | Claude Code | @path inlines file | Router: orientation + @.ai/rules/* imports |
GEMINI.md | Gemini CLI | @path inlines file | Router: orientation + @.ai/rules/* imports |
.github/copilot-instructions.md | GitHub Copilot | #file: references | Generated from .ai/ sources |
Decision: AGENTS.md is the cross-tool standard (60,000+ repos, 20+ tools). Claude Code hasn't adopted it yet (feature request #6235, 2,777+ upvotes). So we maintain both AGENTS.md and CLAUDE.md — when Claude adds support, CLAUDE.md shrinks to Claude-specific settings only.
Decision: GEMINI.md was the first to use @-imports to .ai/rules/. This became the template for CLAUDE.md. Gemini led, Claude followed.
Config Layers
Rules
Rules set the frame. Passive — loaded into context, depends on the agent applying them.
Rules (always loaded) → inform → Skills (loaded on demand)
→ enforced by → Hooks (automated)
| Rule | Prevents | Hook | Why |
|---|---|---|---|
page-flow | Content before visual, missing context section | docs-post-edit.sh | Readers need validation (visual) before trusting content |
content-standards | Preachy voice, long headings, no Tight Five link | docs-post-edit.sh | Voice consistency across 200+ pages |
content-quality | Filler words, passive voice, spelling | docs-post-edit.sh | Every paragraph earns its place |
fact-and-star-architecture | Implementation on index pages | docs-post-edit.sh | Index pages define (hubs). Domain pages implement (stars). Mixing creates dead-end nav. |
mdx-patterns | Raw < > { } in prose, broken frontmatter | mdx-post-edit.sh | MDX parser errors are silent until build |
build-process | Local build commands | PreToolUse block | WSL constraint: Docusaurus builds kill the environment |
git-workflow | Commits to main, branch switching | — | Single-branch keeps history linear |
src-pages-gates | Marketing pages without demand clarity | — | Every entry page needs: job, objection, promise, CTA |
matter-first-pages | Venture pages that explain instead of deciding | — | Decision surfaces, not documentation |
design-checklist | UI without JTBD connection | src-post-edit.sh | Components that don't serve a job are waste |
design-verification | Code that looks right but doesn't render | src-post-edit.sh | Tailwind v3-v4 migration proved this: every token resolved to transparent |
skill-execution | Invoking a skill but eyeballing the gates | — | False confidence is worse than no skill |
decision-transparency | Hidden reasoning, unstated confidence | — | Chain reasoning visibly. State conviction. |
Decision: 14 separate files, not one. Each rule pairs independently with a hook. "Everything in one file" fails when you need to pair rule 7 with hook 3.
Decision: Rules without hooks are suggestions under cognitive load. If it matters, pair it. The page-flow rule existed for weeks before its first violation was caught — by a hook, not by the rule.
Hooks
Hooks fire on events. They validate or block without asking.
| Event | Hook | What It Does | Why |
|---|---|---|---|
SessionStart | session-context.sh | Injects navigation frame | Every session starts oriented |
UserPromptSubmit | user_prompt_submit.py | Routes /commands and /skills | Connects slash commands to .ai/commands/ and .agents/skills/ |
PreToolUse (ExitPlanMode) | truth-seeking-gate.sh | Requires evidence before implementation | Plans without evidence produce confident wrong code |
PreToolUse (Bash+build) | Inline block | Hard-blocks local builds | Not a preference — a constraint. WSL dies. |
PreToolUse (Bash+commit) | docs-pre-commit.sh | Checks content-flow was run | Quality gate before commit |
PostToolUse (md/mdx edits) | mdx-validator.py | Heading word count | Deterministic: headings over 3 words flagged |
PostToolUse (mdx edits) | mdx-post-edit.sh | MDX syntax check | JSX errors caught at edit time |
PostToolUse (docs/meta edits) | docs-post-edit.sh | Flow, standards, quality, fact/star | The comprehensive one |
PostToolUse (src edits) | src-post-edit.sh | Design anti-patterns | Accessibility and design system violations |
Stop | stop-uncommitted.sh | Warns about uncommitted changes | Prevents work loss at session end |
Decision: PostToolUse for content validation, not PreToolUse. You need to see what actually changed. PreToolUse is reserved for blocking dangerous actions.
Decision: truth-seeking-gate.sh on ExitPlanMode specifically. One shell script prevents hours of rework from plans that skipped evidence.
Skills (.agents/skills/)
Multi-step procedures with numbered quality gates. Stored in .agents/skills/ per AAIF Agent Skills spec. Loaded on demand, not always in context.
| Skill | Purpose | Key Gate |
|---|---|---|
content-flow | Full content audit | 5 ordered checks with line-number evidence |
content-uniqueness | Conceptual overlap detection | Insight collision map |
copywriting | Ogilvy+Sutherland persuasion | Headline, opening, body, close |
linkedin-posting | Distribution assets | ICP targeting, hook, CTA, character limits |
deep-research | Multi-source investigation | Source diversity, claim verification |
prompt-architecture | Reusable prompt design | Input/output contracts, edge cases |
sell-the-dream | Meta article voice | Heroes Journey arc, question-first |
venture-launch | New venture pages | Matter-first, commissioning, demand evidence |
design-audit | UI/UX review | Token usage, accessibility, visual hierarchy |
frontend | Component development | Design system, render verification |
landing-page | Landing page sections | Narrative arc, CTA clarity, responsive |
matrix-thinking | Cross-domain patterns | Connection density, insight quality |
matter-first-pages | Venture page governance | Decision surface enforcement |
Decision: Skills moved from .ai/skills/ to .agents/skills/ to adopt AAIF standard. Each SKILL.md has standard frontmatter (name, description). Codex discovers them natively. Other agents follow via adapter or direct path reference.
Decision: Gates require line-number evidence to pass. After a skill was invoked, eyeballed, and declared "all pass" — while missing preachy text, wrong table order, and 7-column tables — the skill-execution rule was added. Quote evidence or don't claim the gate passed.
Commands
Simple prompts in .ai/commands/. If it needs quality gates, it's a skill in .agents/skills/.
| Prefix | Domain | Examples |
|---|---|---|
bd- | Business development | bd-icp-profile-research, bd-linkedin-post, bd-venture |
mm- | Mental model content | mm-alignment, mm-systems-thinking, mm-extract-patterns |
vvfl- | Architecture loops | vvfl-flow, vvfl-skills, vvfl-marketing |
_ | Internal/meta | _improve (post-mortem), _ssc-review (quality) |
| (none) | Core workflows | ship, sync, writers-room, eng-priorities |
Decision: Claude Code reads .claude/commands/ natively. Proxy files in .claude/commands/ redirect to .ai/commands/ — one source of truth, agent-specific entry point.
Writing Voices
Four-voice transform for content. Each writes a complete draft from a different lens, then merge the best.
| Voice | Lens | Question |
|---|---|---|
| Lennon | The Dream | What collective imagination does this serve? |
| Naval | The Leverage | What compounds? Asymmetric upside? |
| Wilde | The Paradox | What truth hides in contradiction? |
| Hemingway | The Truth | What's left when you strip the fancy words? |
Plus: Ogilvy (selling), Sutherland (behavioral), Wathan (UI), Singer (product).
Decision Log
| Decision | Alternative | Why This Way |
|---|---|---|
.agents/skills/ for skills | Keep in .ai/skills/ | AAIF standard. Codex reads natively. Cross-tool discovery. |
.ai/ for rules, hooks, commands | Move everything to .agents/ | No standard covers these yet. Premature standardization. |
Both AGENTS.md and CLAUDE.md | AGENTS.md only | Claude Code doesn't read AGENTS.md yet (#6235). Need both until it does. |
Proxy commands in .claude/commands/ | Symlinks or copies | Proxies can add agent-specific preamble ("Read, Reflect, Execute"). |
| Symlinks for rules | Copy files | Edit once, every agent sees the change. |
| Rules + hooks | Rules only | Rules under cognitive load become suggestions. Hooks don't forget. |
| PostToolUse validation | PreToolUse | Need to validate what changed, not what might change. |
alwaysThinkingEnabled | Default off | Complex reasoning benefits from thinking tokens. Cost justified. |
| Block local builds | Allow with warning | Not preference — constraint. WSL dies. Hard block. |
| Truth-seeking gate on ExitPlanMode | No gate | Plans without evidence produce confident wrong code. |
| Self-contained AGENTS.md | Reference-based | Codex has no @-import. Drift risk mitigated by sync. |
| 14 separate rule files | One RULES.md | Each concern independently testable, hookable, referenceable. |
| Skill gates need line numbers | Checkbox pass/fail | Caught declaring "all pass" while missing obvious violations. |
Model Selection
Which model for which agent? Apply situational wisdom — match cognitive demand to model capability.
| Agent | Model | Task | Why This Model |
|---|---|---|---|
| Claude Code (primary) | Opus | Architecture, complex refactors | Deepest reasoning + thinking tokens |
| Claude Code (fast) | Sonnet | Feature building, content editing | Balanced speed/quality |
| Claude Code (batch) | Haiku | Quick fixes, simple generation | Cost efficiency |
| Gemini CLI | Pro 2.5 | Repo-wide analysis, audits | 1M+ context window, free tier |
| Codex CLI | GPT-4o / o3 | Second opinion, verification | Different model family catches different bugs |
Decision: Write with one family, verify with another. Claude reviewing Claude code shares training biases. Gemini reviewing Claude code catches different things. See LLM Selection Framework for the full decision matrix.
Per-Agent Setup
| Agent | Guide | Key Config |
|---|---|---|
| Claude Code | Hooks, plugins, settings | CLAUDE.md + .claude/settings.json |
| Gemini CLI | Hierarchical context, memory | GEMINI.md + @-imports |
| Codex CLI | AGENTS.md, manual hooks | AGENTS.md + scripts/codex-hooks-check.sh |
| Cursor | .mdc rules, agents | .cursor/rules/*.mdc |
Context
- AI Agent Config Standards — AAIF, Agent Skills spec, MCP, adoption matrix
- AI Coding — Principles and playbook
- LLM Selection — Model decision matrix
- Situational Wisdom — Context-dependent decisions
- Data Flow — The fuel for prediction models
- Clean Architecture — Structure AI can navigate
- Model Context Protocol — Agent-to-tool communication