One canon. Every agent.

What is agentcanon?

Most AI tools have settled on a standard: skills live in .agents/skills/ and instructions live in AGENTS.md. Codex, Cursor, and most newer tools read them natively. But a few holdouts (ahem, Claude Code) still look in their own locations instead, so you end up with duplicate skill folders, a CLAUDE.md here and an AGENTS.md there, copies that drift apart, and no idea which one is real.

agentcanon is the simplest possible fix: everything lives in the standard locations, and symlinks point the holdouts at them. It’s a convention rather than a tool — nothing to install, nothing to run, no dependency to keep updated. One real copy, every tool reading it.

The convention

Everything real lives in the open-standard .agents locations. Everything else is a pointer:

~/.agents/skills/             ← your global skills, the ONE real copy
~/.claude/skills              → symlink to ~/.agents/skills

any-project/
  AGENTS.md                   ← the real agent instructions
  CLAUDE.md                   → symlink to AGENTS.md
  .agents/skills/             ← the project's real skills
  .claude/skills              → symlink to .agents/skills

Why .agents and AGENTS.md as the canon? They’re the vendor-neutral Agent Skills and AGENTS.md standards that Codex, Cursor, and a growing list of tools already read natively. Claude Code reads its own .claude locations, which is what the two symlinks are for. When a new tool ships with its own opinionated path, that’s one more symlink — never another copy.

The agentcanon repo practices the convention itself: its CLAUDE.md and .claude/skills are committed symlinks.

Setup

Any agent

Nothing here is Claude Code-specific. The canonical locations are the open standards, so Codex, Cursor, and most newer tools read them natively with no symlink at all — Claude Code just happens to be the holdout that needs the two symlinks above. If you use a tool with yet another path, add a symlink for it using the same form and the canon stays a single copy.

Learn to build

Want a step-by-step tutorial on how to plan, prompt, and ship real apps with AI — with conventions like agentcanon holding the whole workflow together? That’s exactly what I teach in my Become the Builder course, included with Builder Methods Pro. You’ll learn how I plan, prompt, and ship full-stack apps end-to-end — alongside direct support from me and the rest of the community.

Going forward

The convention only holds if new skills land in the right place. Four rules:

• Install skills into the canon. A skill is a folder with a SKILL.md inside. Global skills go in ~/.agents/skills/; project-specific ones go in that repo’s .agents/skills/. Same for skills you write yourself. Claude Code (and every other tool you’ve symlinked) picks them up normally.
• Never put a skill folder inside a .claude/skills/ path — or any other tool-specific skills path. Those are symlinks to the canon, not storage.
• Write agent instructions to AGENTS.md. CLAUDE.md is a symlink to it, so there’s only ever one file to edit.
• Bake it into your template repo. If you start new projects from a template, run the setup prompt there once so every project you spin up is already on the convention. My Build New starter ships this way.

Repo converter skill

Optional. The setup prompt above already converts the repo you’re in. If you convert repos often, install agentcanon-repo as a global skill instead: run it inside any repo and it finds skills living outside .agents/skills/, moves them there, turns the old folders (like a real .claude/skills) into symlinks, and merges CLAUDE.md into AGENTS.md with a symlink back. It always shows you the plan — every move, merge, and symlink — and waits for your approval before touching anything.

To install it, tell your agent:

Install the agentcanon-repo skill from
https://github.com/buildermethods/agentcanon: copy
.agents/skills/agentcanon-repo/ into ~/.agents/skills/.

Then, inside any repo: “convert this repo to the agentcanon convention”.

Sync across machines

Git handles this; no sync service needed. For global skills, make ~/.agents/ a git repo and push it to a private remote, then clone it on your other machines — syncing is a push and a pull. For projects, commit the repo’s .agents/ folder and the symlinks normally. Git tracks symlinks, so they travel with the project like any other code.

Skills manifest

A nicety, not part of the convention — skip it freely. The manifest is a single dependency-free HTML page at ~/.agents/skills-manifest.html that lists every skill on your machine (name, description, location, created date), sortable and filterable by global or project, plus a list of your skills folder symlinks. Open it in any browser.

If you want it, tell your agent:

Install the agentcanon-manifest skill from
https://github.com/buildermethods/agentcanon: copy
.agents/skills/agentcanon-manifest/ into ~/.agents/skills/, then use it
to install the skills manifest.

Refresh it any time with “update the skills manifest”.

Next steps

• View the source on GitHub
• Explore other Builder Methods tools