FCIS RFC 0001: skill parity — identical copies in .codex/skills and .claude/skills - #2
Merged
Conversation
… and .claude/skills 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 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
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 several sessions — precisely the waste the skills layer exists to prevent.The underlying intent was always "procedures live 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 one path silently scoped every skill to one agent.What changes
A skill MUST exist as an identical copy at
.codex/skills/<name>/SKILL.mdand.claude/skills/<name>/SKILL.md, with three constraints, each from an observed failure:.claude/gitignore entry and did not ship with the cloneThe repository states which path is the editing origin, so copy direction is never ambiguous.
Where it is enforced
Not only in the rules section — also in Step 1 (Audit), which now compares both paths and checks
.gitignore, and in the PR checklist, which now requires both copies. A rule stated but not assessed is not enforced.