Claude Code と Codex に同じルールとスキルを読ませる symlink 構成
このブログのリポジトリでは Claude Code と Codex を併用しています（経緯は乗り換え記事に書きました）。併用してすぐ困ったのが、ルールとスキルの置き場がエージェントごとに違うことです。同じ内容のファイルを2箇所に置くとどちらかが古くなるので、正本を一つ決めて symlink で配る形にしました。1ヶ月半ほど運用して安定しているので、構成を書き残しておきます。
課題: エージェントごとに設定の置き場が違う
Claude Code と Codex は、それぞれ別の場所を読みに行きます。
| Claude Code | Codex | |
|---|---|---|
| プロジェクトのルール | CLAUDE.md | AGENTS.md |
| スキル（SKILL.md） | .claude/skills/ | .agents/skills/ |
ルールもスキルも中身はただの Markdown なので、内容自体はどちらのエージェントでも通用します。問題は置き場だけです。
最初は .agents/skills/ にスキル一式を丸ごとコピーしていたんですが、これが失敗でした。片方だけ直して片方が古いまま、という状態が普通に起きます。実際、このリポジトリでも .claude/skills/ 側の SKILL.md を直したあと .agents/skills/ 側のコピー（228行 + データファイル一式）が放置されていて、symlink に切り替えるときにまとめて削除しました。
方針: 正本を一つ決めて symlink で配る
やることは2つだけです。
- ルールの正本を
AGENTS.mdに決めて、CLAUDE.mdを symlink にする - スキルの実体を
.claude/skills/に置いて、.agents/skills/から symlink を張る
コピーと違って symlink なら編集箇所が常に一つなので、乖離が構造的に起きません。git は symlink をそのまま追跡できるので、clone した先でもこの構成は維持されます。
正本をどちら側にするかは好みですが、ルールは AGENTS.md 側に寄せました。AGENTS.md は Codex 専用ではなく複数のエージェントが読む共通の慣習になっているので、正本として据えるならこちらかなという判断です。逆にスキルの実体は .claude/skills/ 側にしています。先にスキル群を整備したのが Claude Code だったのと、/write のようなスラッシュコマンド起動が .claude/skills/ を前提にしているためです。
ルールの共有: CLAUDE.md を AGENTS.md への symlink にする
もともと .claude/CLAUDE.md にあったルールを AGENTS.md に統合して、ルートの CLAUDE.md を symlink に置き換えました。
# ルート CLAUDE.md を AGENTS.md への symlink に置き換えるrm CLAUDE.mdln -s AGENTS.md CLAUDE.mdこれで Codex は AGENTS.md を直接読み、Claude Code は CLAUDE.md 経由で同じファイルを読みます。ルールの追記・変更は AGENTS.md だけを編集すれば両方に反映されます。
AGENTS.md の冒頭には「このファイルが正本で、CLAUDE.md は symlink。編集はこのファイルだけ」と明記しています。エージェント自身がルールを更新することもあるので、どちらを編集すべきかをルール自体に書いておかないと、symlink 側を実ファイルで上書きされる事故が起こり得ます。
スキルの共有: .agents/skills から symlink を張る
スキルは .claude/skills/{スキル名}/SKILL.md を実体にして、.agents/skills/ からディレクトリ単位で symlink を張ります。
# 相対パスでディレクトリごと symlink（例: /write スキル）ln -s ../../.claude/skills/write .agents/skills/writeTIPsymlink は絶対パスではなく相対パスで張ります。絶対パスだと clone した環境や CI でパスが変わって壊れます。
新しいスキルを追加するときの手順もこれで固定されました。.claude/skills/ にスキルを作って、symlink を1本追加するだけです。この構成にしてから /reach・/suggest-posts・/write-external の3スキルを追加しましたが、Codex 対応のためにやったことは毎回 ln -s 1回だけです。
SKILL.md はツール中立に書いておく
置き場を共有できても、SKILL.md の中身が特定エージェントのツール名だらけだと使い回せません。Claude Code の WebSearch や WebFetch は Codex には存在しないツールです。
このリポジトリでは、個別の SKILL.md を書き換える代わりに AGENTS.md 側に読み替えルールを1行置いています。
SKILL.md 内のツール名（WebSearch / WebFetch など）は「同等の機能」と読み替える。Web 検索・取得の手段がない環境では
curl -sLを使うか、ユーザーに情報提供を依頼する
スキルごとに書き換えるより、正本のルールで一括して吸収するほうが楽でした。SKILL.md 側は Claude Code 前提の語彙のままで書けます。
1ヶ月半運用してみて
効果をいちばん感じているのは、ルールを直す場所が1箇所になったことです。文体ルールや frontmatter の規約はけっこうな頻度で育てているので、二重管理のままだったら確実に乖離していたと思います。
一つだけ罠があって、スキルを追加するときに .agents/skills/ への symlink を忘れると、Claude Code では動くのに Codex からだけスキルが見えない状態になります。エラーが出るわけではないので気づきにくいです。これも AGENTS.md に「新規スキルには .agents/skills/ に symlink を追加する」と手順を書いて、エージェント自身に守らせる形で対処しました。
Agent Skills はオープンな標準として複数ツールに広がっているので、対応エージェントが増えても「実体は1箇所 + symlink を1本足す」の延長で対応できる見込みです。