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.

When to invoke

• New project: right after git init or git clone, before adding any project-specific skills or agent guidance.
• Auditing an existing project: when you suspect drift — symptoms include .claude/skills or .agents/skills containing real directories instead of being symlinks, both CLAUDE.md and AGENTS.md existing with different content, or skills appearing under more than one path.
• Migrating from Claude-only to multi-runtime: when a project that started life with just CLAUDE.md needs to also work cleanly under Codex/Pi.

If the project genuinely has no agent guide and no project-level skills (e.g. a repo that only ever runs in Claude Code with the user's global skills), this skill is still safe to run — it'll just create the canonical shells and exit, no destructive moves.

How to apply

The skill bundles a single idempotent script. It's safe to run repeatedly; the no-op path is the same as the migration path when there's nothing to migrate.

# 1. Always preview first
bash "$SKILL_DIR/scripts/ensure-canonical-skills.sh" --dry-run [path]

# 2. Review the planned actions, then commit
bash "$SKILL_DIR/scripts/ensure-canonical-skills.sh" [path]

$SKILL_DIR is the directory containing this SKILL.md. The path argument defaults to the current working directory.

The script prints one line per action it would take or has taken, plus a final migration complete / already canonical line. Re-running on a fully canonical project produces only the latter.

What the script will and won't auto-fix

It will:

• Create <project>/skills/ if missing.
• Add <project>/skills/.gitkeep when initializing an otherwise empty project skills directory, so the canonical directory survives git checkouts before the project has real skills.
• Convert <project>/.claude/skills from a real directory into a symlink, moving any existing entries into <project>/skills/ first. Tracked entries move via git mv so history follows; in-tree redundant symlinks (e.g. .claude/skills/X → ../../skills/X) are dropped instead of moved.
• Convert <project>/.agents/skills from a real directory into a symlink, moving any existing entries into <project>/skills/ first. Tracked entries move via git mv so history follows; in-tree redundant symlinks are dropped instead of moved.
• Copy CLAUDE.md → AGENTS.md and replace CLAUDE.md with the one-line @AGENTS.md import, in the cases where this is unambiguous.

It will refuse and ask for manual resolution when:

• <project>/skills is itself a symlink pointing somewhere else — likely intentional, the script can't guess where.
• An entry inside .claude/skills/ or .agents/skills/ would collide with an existing entry in skills/ that has different content.
• Both CLAUDE.md and AGENTS.md exist with different real content. The script prints a diff --stat hint; merge into AGENTS.md by hand, then re-run. (Refusal is per-step, not per-project — other steps still progress.)
• The project has uncommitted changes (the migration should be one reviewable diff, not a mix).

AGENTS.md / CLAUDE.md decision table

The script picks an action by reading both files. @AGENTS.md here means a CLAUDE.md whose first non-empty line is exactly the literal string @AGENTS.md and which is short enough to plausibly contain only that import.

CLAUDE.md	AGENTS.md	Action
absent	absent	no-op
@AGENTS.md import	present	already canonical, no-op
absent	present	create CLAUDE.md containing @AGENTS.md\n
present (real content)	absent	move CLAUDE.md → AGENTS.md, then write CLAUDE.md = @AGENTS.md\n
present (real content)	present, byte-identical	overwrite CLAUDE.md = @AGENTS.md\n
present (real content)	present, divergent	REFUSE. Print diff hint, skip this step, continue with the rest.

Runtime notes

Claude Code reads project skills from <project>/.claude/skills and reads <project>/CLAUDE.md, following the @AGENTS.md import to load the canonical guide.

Codex and Pi Agent both read <project>/AGENTS.md directly per the agents.md spec. Codex and Pi source personal skills from their respective user-home locations (see references/runtime-paths.md); Codex and agents.md-compatible workflows can additionally discover project-local skills through <project>/.agents/skills.