Keep one skill folder in sync for Codex and Claude Code
You maintain a single skills directory in git that both Codex and Claude Code are pointed at, with a short compatibility note for each tool.
One folder, one SKILL.md per job, and a README that says how each agent should load it so you are not maintaining two copies.
- 1
Pick one git root for skills
Delete or stop updating the second copy the day you migrate. Two folders is how teams lie to themselves about sync.
- 2
Add the compatibility README
One page next to the skills: load paths for each tool, updated when someone upgrades the CLI.
- 3
Run the same skill from both tools
Trigger the identical job once in Codex and once in Claude Code. Compare done checklist items, not prose style.
The prompt to paste
Design a shared agent skills layout for one repository used by both Codex and Claude Code. Repo facts: [languages, package manager, test command, existing .claude or .cursor paths] Skills we need (list 1-3 job names): [e.g. release notes, dependency bump review, port tests] Return: ## Folder layout Tree under a single root (e.g. agent-skills/ or .agents/skills/). One subdirectory per skill with SKILL.md. ## SKILL.md template A template with sections both tools can honor: purpose, when to use, inputs, steps, pitfalls, done checklist. Keep tool-specific syntax out of the body; put tool notes in a sidecar if needed. ## Tool wiring For each tool: - Where Claude Code expects skills (path + any config file name you know; else [verify in docs]) - Where Codex or the OpenAI coding agent expects instructions (path or env; else [verify in docs]) - One sentence on what to do when the tools disagree on path (default: git path wins) ## Drift prevention A pre-commit or CI check described in plain language: what file must exist, what must not be duplicated in personal config, and how to fail the check with a readable message. Do not invent proprietary flags. Do not claim feature parity where you are unsure — mark [verify].
Tool-specific magic paths change between releases. Pin the load instructions in the README and re-run the pairing test after upgrades.
Sample case written by Hidden Logic Lab. Not affiliated with Codex or Claude Code.
More in Coding
Get new cases in your inbox
Weekly notes on new use cases and agent workflows. No product pitches.