Agent Rules - Single Source of Truth
Every AI coding agent reads its own rules file and its own skills directory. This
skill keeps one real copy of each and points the rest at it with symlinks.
Quick Start
/agent-rules # create or repair links in the current project
/agent-rules --check # verify; exits 1 when something is broken
/agent-rules --status # report only, never fails
/agent-rules --minimal # skip links agents no longer need
/agent-rules --root <path> # operate on a project other than $PWD
The target project is the git toplevel of your working directory (or $PWD
outside a repo), not wherever this skill happens to be installed.
Single Source of Truth
Two sources, edited by hand:
- Rules —
AGENTS.md at the project root
- Skills —
.agents/skills/<skill-name>/SKILL.md
Everything else is a symlink into those two.
AGENTS.md ← edit rules here
.agents/skills/ ← edit skills here
↓ symlinks ↓
CLAUDE.md → AGENTS.md
.gemini/GEMINI.md → ../AGENTS.md
.github/copilot-instructions.md → ../AGENTS.md (legacy)
.cursor/rules/main.md → ../../AGENTS.md (legacy)
.kiro/steering/main.md → ../../AGENTS.md (legacy)
.claude/skills/ → ../.agents/skills
.kiro/skills/ → ../.agents/skills
.github/skills/ → ../.agents/skills (legacy)
.codex/skills/ → ../.agents/skills (legacy)
Agent Support
.agents/skills/ and AGENTS.md are now read natively by several agents, so
some links exist purely for older versions. --check treats a missing legacy
link as a warning and a missing required link as an error.
| Agent | Rules | Skills | Tier |
|---|
| Claude Code | CLAUDE.md → | .claude/skills/ → | required — reads neither AGENTS.md nor .agents/skills |
| Gemini CLI | .gemini/GEMINI.md → | N/A | required — AGENTS.md only via context.fileName in settings.json |
| Kiro | .kiro/steering/main.md → | .kiro/skills/ → | skills required; rules legacy (reads root AGENTS.md) |
| GitHub Copilot | .github/copilot-instructions.md → | .github/skills/ → | legacy — reads AGENTS.md and .agents/skills natively |
| OpenAI Codex | AGENTS.md | .codex/skills/ → | legacy — scans .agents/skills from CWD up to the repo root |
| Cursor | .cursor/rules/main.md → | N/A | legacy — reads AGENTS.md natively |
Verified against vendor documentation on 2026-09-07. Run --status to see which
links a project still carries.
Known quirk: some Kiro builds do not follow a symlinked steering file. If Kiro
ignores your rules, replace .kiro/steering/main.md with a real copy.
Usage
vim AGENTS.md # edit rules once, every agent sees it
mkdir -p .agents/skills/my-skill # add a skill once, every agent sees it
vim .agents/skills/my-skill/SKILL.md
Critical Rules
- ✅ Only edit
AGENTS.md — single source for rules
- ✅ Only edit
.agents/skills/ — single source for skills
- ❌ Never edit a symlinked file — you are editing the source through a
confusing alias
- ❌ Never copy instead of linking — copies drift
Safety
- Existing real files are never overwritten. If
CLAUDE.md holds hand-written
content, it is left alone and reported; --force moves it to CLAUDE.md.bak
first. (An exact copy of AGENTS.md is replaced silently — nothing is lost.)
- Missing parent directories are created.
- Re-running is idempotent.
- On Windows, symlinks need
git config core.symlinks true; --check warns when
the repo is configured otherwise.
What About MCP Configs?
Not symlinked. Formats differ (.json vs .toml), settings are
agent-specific, and the files may hold API keys.
- Claude:
.claude/mcp.json · Kiro: .kiro/mcp.json · Cursor: .cursor/mcp.json · Codex: .codex/config.toml
Sync them manually if you need to.
Scripts
scripts/agent-rules.sh — entry point (--check / --status / --fix)scripts/create-symlinks.sh — create and repair linksscripts/verify-architecture.sh — verify; exit code reflects the resultscripts/lib.sh — shared link table used by all threescripts/test-agent-rules.sh — self-test (bash scripts/test-agent-rules.sh)
Each script runs standalone and works on whichever project you are standing in.
Troubleshooting
| Symptom | Fix |
|---|
| Link broken or pointing elsewhere | /agent-rules |
A stray skills entry inside .agents/skills/ | /agent-rules removes it (planted by v4) |
--check fails on a link you do not want | --minimal layout, or drop the agent from scripts/lib.sh |
| Agent still cannot see a skill | confirm .agents/skills/<name>/SKILL.md exists |
Version: 5.0
Last Updated: 2026-09-07
Changes since 4.0:
- Target project resolved from your working directory instead of the skill's
install path —
--check used to inspect the wrong directory whenever the skill
was not vendored into the project
- Parent directories are created, so bootstrapping an empty repo works
- Directory links use
ln -sfn; re-running no longer plants a broken
.agents/skills/skills link inside the source directory
- Verification exits non-zero on failure, and no longer demands that
agent-rules
itself be vendored into the project it checks
- Real files are never clobbered;
--force backs them up
- Links are tiered required/legacy against what agents read natively today