canonical-project-skills-layout
canonical-project-skills-layout
Apply a single, predictable layout to any project the user works in so Claude Code, Codex, and Pi Agent share one project guide and one project skill source of truth wherever the runtime supports project-local skills. Install this skill at the user level for the runtime you're using (e.g. npx skills@latest add memorysaver/skills --global, or via the Claude Code plugin marketplace); the bundled script then operates on whatever project directory you point it at.
The five invariants
| What | Where | Why it has to be this exact shape |
|---|---|---|
| Project skills source of truth | <project>/skills/ (real directory) |
One canonical place to add, edit, and review skills. Tracked in git as itself, not as an alias. |
| Claude Code project skills | <project>/.claude/skills → symlink to ../skills |
Claude Code reads project skills from this exact path. Pointing it at the canonical dir avoids dual-write and keeps git diffs honest. |
| Codex project skills | <project>/.agents/skills → symlink to ../skills |
Codex and agents.md-style tooling can discover project-local skills from .agents/skills while sharing the same canonical skills/ source. |
| Canonical agent guide | <project>/AGENTS.md (real file) |
Read by Codex, Pi Agent, and any agents.md-spec compatible tool. This is the single editable source. |
| Claude Code agent guide | <project>/CLAUDE.md containing exactly @AGENTS.md |
Claude Code follows the @import syntax to load AGENTS.md. Keeping CLAUDE.md as a one-line import means there's only one place to edit guidance — AGENTS.md — and Claude inherits everything Codex/Pi see. |
Codex and Pi still read personal skills from fixed user-home locations, but this project layout gives all three runtimes the same guide and keeps project-local skill files in the standard discovery paths that support them. See references/runtime-paths.md for the full per-runtime path table.