This directory is the canonical source for baseline agent rules and supporting command references. The primary workflow is to symlink files from here into each agent runtime/config location.

What this directory contains

AGENTS.md: global baseline rules for coding agents.
evals/global-rules.md: behavioral scenarios for validating changes to the global rules.
install-rules.py: installs the baseline by creating symlinks in supported agent config dirs.
test_install_rules.py: regression tests for file preservation and independent target handling.
install-cli.md: curated CLI install/update command snippets.
install-skills.md: curated npx skills command snippets.

Core workflow

Maintain shared rules in agents/AGENTS.md.
Configure permissions directly in the agent runtime; auto-approval is generally used.
Run install-rules.py to refresh symlinks in local agent homes.
Use install-cli.md and install-skills.md as reference snippets when needed.

Install baseline rules (symlink-based)

Run:

python3 agents/install-rules.py

Current targets:

Codex: AGENTS.md -> ${CODEX_HOME:-~/.codex}/AGENTS.md
OpenCode: AGENTS.md -> ${XDG_CONFIG_HOME:-~/.config}/opencode/AGENTS.md
Claude Code: AGENTS.md -> ~/.claude/CLAUDE.md
Generic cross-tool (read by Kimi Code): AGENTS.md -> ~/.agents/AGENTS.md

Behavior:

Each target is handled independently.
Target errors are reported while remaining targets are attempted; any error yields a nonzero exit.
Missing destination directories are skipped.
Existing regular files are preserved as .bak backups (numbered when a backup already exists).
Destination links are replaced atomically; a failed link creation leaves the destination intact.

The installer links only AGENTS.md; it does not install permission configuration, skills, or CLIs. The repository-root AGENTS.md contains guidance for this Nix configuration repository. It is not the global rules source and is not installed by this script.

Auto-approval controls tool prompting. The global rules still define task authorization, safety, and secret handling.

Run installer regression tests without changing installed rules:

python3 -B -m unittest discover -s agents -p test_install_rules.py

About `install-cli.md` and `install-skills.md`

Use them as snippet libraries:

review the commands
select what you need
run selected commands manually

TODO

Ideas worth adopting once a concrete need appears; nothing here is implemented yet, and the install scripts above do not cover it.

Shared instructions and skills. Deploy one rules body plus declared skills to every agent (Claude Code, Codex, OpenCode) instead of maintaining a copy per agent. Reference: mirkolenz/infra options/home-manager/agents.nix (custom programs.agents, follows the Agent Skills spec) and khaneliman/khanelinix modules/common/ai-tools/.
Single-source permissions. Keep allow/ask/deny command lists and agent role definitions in one place and render them per harness. Reference: khaneliman/khanelinix modules/common/ai-tools/{permissions,agents}.nix.
MCP from one definition. Define MCP servers once and project them into each client. Home Manager ships programs.mcp (writes $XDG_CONFIG_HOME/mcp/mcp.json), but consumers still render it per agent. References: Home Manager modules/programs/mcp.nix, jevy/home-manager-nix-config modules/dev/mcp.nix, dryvist/nix-ai modules/mcp/.

Conventions

Keep files portable and reviewable.
Keep secrets and machine-specific credentials out of this directory.
Keep guidance generic enough to reuse across multiple agent environments.

Goal

Maintain one reusable source of truth for agent setup that stays simple to sync and easy to evolve.

README.md

agents