From 255f6d7a26c8e353a2d1e56d931c783c4fceb331 Mon Sep 17 00:00:00 2001 From: Benedikt Eickhoff Date: Mon, 27 Jul 2026 12:12:42 +0200 Subject: [PATCH] FCIS RFC 0001: skills must exist as identical copies in .codex/skills and .claude/skills MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Found in practice, not in theory. A Live Drive runbook was authored into `.codex/skills/live-drive/` per the current rule and was then INVISIBLE to Claude Code, which discovers skills only under `.claude/skills/`. The agent that could not see it re-derived the same procedure from scratch across multiple sessions — the exact waste the skills layer exists to prevent. The underlying rule was always "a procedure lives in the skills layer". What the standard did not say is that agent runtimes DO NOT SHARE A DISCOVERY PATH: Codex reads `.codex/skills/`, Claude Code reads `.claude/skills/`. Naming only one path silently scoped every skill to one agent. Amendment: a skill MUST be discoverable by every agent runtime the repository supports, and therefore MUST exist as an identical copy at both paths. With three constraints that each come from a real failure mode: - COPIES, NOT SYMLINKS. A symlink bridge was tried first. Symlink discovery is not guaranteed across runtimes, and a link is silently broken by an archive export, a worktree, or a filesystem that does not carry it. - NEITHER PATH MAY BE GITIGNORED. The same bridge lived under a `.claude/` entry in `.gitignore`, so it did not ship with the clone. A skill that does not survive `git clone` is not a skill. - BYTE-IDENTICAL CONTENT. Divergence is worse than absence: two agents then follow different steps while both believe they are compliant. Also updates the audit step to compare both paths and check `.gitignore`, and the PR checklist to require both copies — so the rule is enforced where compliance is actually assessed, not only stated. Co-Authored-By: Claude Opus 5 --- compliance-check.md | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/compliance-check.md b/compliance-check.md index 9111961..f1fe329 100644 --- a/compliance-check.md +++ b/compliance-check.md @@ -57,7 +57,8 @@ Must include: The PR MUST: - Add/adjust `AGENTS.md` - Add/adjust `PLANS.md` (or declare `PLAN.md` in `AGENTS.md` if you keep it) -- Add `.codex/skills//SKILL.md` for any runbooks currently embedded in AGENTS/PLAN docs +- Add `.codex/skills//SKILL.md` AND its identical copy at `.claude/skills//SKILL.md` for any runbooks currently embedded in AGENTS/PLAN docs +- Ensure `.gitignore` excludes neither skills path, so both copies ship with the clone - Remove orthogonality violations by moving content to the correct layer - Not require any MCP server presence for correctness @@ -65,6 +66,11 @@ The PR MUST: - `AGENTS.md` = behavioral law. MUST define invariants and routing. MUST NOT contain step-by-step procedures or tool configuration. - `PLANS.md` = long-task intent protocol. Must be required by AGENTS.md for multi-step/high-risk work. - Skills = execution technique modules. Each skill directory MUST contain `SKILL.md` with: purpose, when-to-use, steps, output contract. +- **Skill parity (RFC 0001 amendment).** A skill MUST be discoverable by EVERY agent runtime the repository supports, and agent runtimes do not share a discovery path: Codex reads `.codex/skills/`, Claude Code reads `.claude/skills/`. A skill present in only one is invisible to the other agent, so the runbook silently gets reinvented by whichever agent cannot see it — the exact waste skills exist to prevent. Therefore each skill MUST exist as an IDENTICAL copy at `.codex/skills//SKILL.md` and `.claude/skills//SKILL.md`. + - Copies, not symlinks: symlink discovery is not guaranteed across runtimes, and a link is silently broken by an archive export, a worktree, or a filesystem that does not carry it. + - Neither path may be excluded by `.gitignore`. A skill that does not ship with the clone is not a skill. + - Content must be byte-identical. Divergence is drift, and drift in a procedure is worse than no procedure: two agents then follow different steps while both believe they are compliant. + - The skill is authored once and copied; the repository states which path is the editing origin so the copy direction is never ambiguous. - MCP = capability only. MUST NOT encode workflow/policy; MUST be configured outside repo; repo must not depend on MCP for correctness. - Each layer answers exactly one question: - AGENTS: What is allowed? @@ -80,7 +86,8 @@ Locate and read: - `README.md` (and any referenced policy docs) - `AGENTS.md` (and any nested equivalents) - `PLANS.md` and/or `PLAN.md` -- `.codex/skills/**/SKILL.md` (if present) +- `.codex/skills/**/SKILL.md` and `.claude/skills/**/SKILL.md` (if present) — compare them; a skill in only one path, or differing content between them, is a parity violation +- `.gitignore` — confirm it excludes neither skills path Search for instruction spillover keywords: - "how to", "steps", "run", "command", "config", "MCP", "policy", "workflow"