Cross-project agent configuration maintained once.

Define AI preferences once instead of repeating them in every CLAUDE.md. Skills, agents and global rules as a versioned repo — symlinked into Claude Code and Codex.

GitHub

Define AI preferences once instead of repeating them in every CLAUDE.md. Skills, agents and global rules as a versioned repo — symlinked into Claude Code and Codex.

GLOBAL.md 18 Skills Claude Code Codex Pre-commit Hook Auto-generated TOML MIT License


git clone git@github.com:casoon/ai-agent-config.git ~/ai-agent-config

Define once — effective everywhere

Working across multiple projects means repeating yourself: working style, quality rules, commit conventions — somewhere in every CLAUDE.md again. When something changes, every project needs to be touched individually.

ai-agent-config centralizes exactly these cross-cutting preferences. Project-specific CLAUDE.md files become shorter and more focused — they only describe what makes this project special. Everything else comes from the central repo, maintained once, immediately effective in all projects.

Repo structure

One GLOBAL.md for both tools. Agents maintained as Markdown, automatically generated as TOML for Codex. Update via git pull.

ai-agent-config/

ai-agent-config/
├─ GLOBAL.md ← Claude Code & Codex
├─ agents/ ← source files (Markdown)
│  ├─ planner.md
│  ├─ implementer.md
│  └─ reviewer.md
├─ codex-agents/ ← auto-generated (TOML)
│  └─ planner.toml ...
├─ codex-config.toml
├─ skills/ ← 18 domain skills
│  ├─ astro-architecture/
│  ├─ tailwind-ui/
│  └─ ... (16 more)
└─ install/
 └─ link-all.sh

The 4-layer model

Each layer holds exactly what belongs there. No mixing, no context bloat.

Global = Behavior

Personal working style

How you work: analyze before changing. Small diffs. No new dependencies without reason. Applies the same way in every project.

GLOBAL.md → ~/.claude/CLAUDE.md & ~/.codex/AGENTS.md

Skill = Domain knowledge

Stack-specific knowledge

18 curated domain skills: Astro, Tailwind, Biome, SEO, Accessibility, Playwright, Dark Mode and more — loaded only when needed.

skills/astro-architecture/SKILL.md

Repo = Truth

Project-specific rules

Folder structure, commands, architecture boundaries, naming conventions — what is specific to this repo belongs in the repo.

CLAUDE.md (in project)

Agent = Role

Specialized roles

Planner, Implementer, Reviewer as Markdown source files — automatically generated as TOML for Codex. Maintain once, both tools use it.

agents/reviewer.md → codex-agents/reviewer.toml

GLOBAL.md – one file for both tools

Short enough to always be loaded. Linked as CLAUDE.md and AGENTS.md.

GLOBAL.md

## Core principles
- Do exactly what is asked — no more, no less.
- Prefer modifying existing code over adding new files.
- Minimize surface area of changes.
 
## Working style
- Start non-trivial tasks with a brief plan.
- Break work into small, reviewable steps.
- State assumptions explicitly when requirements are unclear.
 
## Scope control
- Do not fix unrelated issues.
- Do not reformat unrelated code.
- Do not refactor outside the task scope.
 
## Validation
- Run targeted checks first: typecheck, lint, focused tests.
- Mention what was validated and what was not.

Stack knowledge goes into skills. Repo rules into the repo. The global file stays lean.

The pre-commit hook scans every commit with nosecrets — secrets never reach version history.

Five specialized roles

Agents are roles, not knowledge databases. The domain knowledge lives in skills.

planner

Breaks tasks into steps, identifies risks, suggests the smallest sensible implementation path.

implementer

Implements precisely. Small diff, preserves existing architecture, no silent restructuring.

reviewer

Checks correctness, regressions, maintainability, and architecture violations. Results grouped by severity.

explorer

Searches the codebase in context isolation. Returns a direct answer with file:line references — without loading raw file content into the main context.

security-auditor

Checks defensively for injection, authn/authz, secret handling, and input validation. Distinguishes Critical / Warning / Hardening. Does not write exploits.

Set up in two steps

Clone and link. Update via git pull.

install/link-all.sh

# Clone
git clone git@github.com:casoon/ai-agent-config.git ~/ai-agent-config
 
# Set symlinks (Claude Code + Codex)
cd ~/ai-agent-config && ./install/link-all.sh
 
# Enable pre-commit hook
git config core.hooksPath .githooks
 
# Update later
cd ~/ai-agent-config && git pull

The concept in detail

The 4-layer model, the difference between Claude Code and Codex, why skills are better than huge global files — explained in depth in the Insights blog (German).

Read article