Claude codeとCodexのスキルを共通化する方法

AIエージェントを複数使っていると、同じスキルやコンテキストファイルをどこに置くかで迷いやすくなります。特に Claude Code と Codex の両方を使う場合、スキルをコピーして持つとどちらが最新か分からなくなりがちです。

この記事では、スキルの実体を .agent/skills に集約し、.claude/skills と .codex/skills からはシンボリックリンクで参照する構成への整理をまとめます。Codexを再起動すれば、プロジェクトごとの .codex/skills シンボリックリンクでもスキル一覧に認識されることが分かりました。

この記事で分かること

Windowsでスキル置き場を1か所にまとめる構成
.agent/skills を正本にするメリット
.claude と .codex をどう共存させるか
シンボリックリンク作成時の権限エラーへの対処
プロジェクトごとの .codex/skills でも認識される条件
Gitで管理するものとローカル専用にするものの分け方

なぜスキルを共通化したのか

もともとはリポジトリ直下に skills/your-skill-name/ のような構成でスキルを置いていました。ただ、この形だと運用が進むほど次の問題が出ます。

Claude用とCodex用で参照先の考え方がずれる
スキルを複製すると、正本が分からなくなる
片方だけ更新して、もう片方が古いまま残る
コンテキストファイルとスキル本体の責務が混ざる

要するに、スキルの本体を複数箇所に置く構成は保守しにくいです。そこで、編集対象を .agent/skills に1本化し、ツール側はそこを参照するだけに寄せました。

採用したディレクトリ構成

最終的には次の構成にしました。

MyProject/
├── .agent/
│   └── skills/
│       └── your-skill-name/
│           ├── SKILL.md
│           └── references/
├── .claude/
│   ├── CLAUDE.md
│   └── skills -> ../.agent/skills
├── .codex/
│   ├── AGENTS.md
│   └── skills -> ../.agent/skills

ポイントは次の3つです。

スキル本体は .agent/skills/ にだけ置く
.claude/skills は Claude 用の入口にする
.codex/skills は Codex 用の入口にする

この形なら、スキル更新時は .agent/skills/ だけ編集すれば済みます。

Windowsで実際にやった作業

今回の移行は次の流れで進めました。

.agent/skills を作成する
既存のスキルを移動する
.claude/skills をシンボリックリンクに置き換える
.codex/skills をシンボリックリンクとして作成する
CLAUDE.md と AGENTS.md を新構成に合わせて整理する
Codex を再起動して、プロジェクトごとの .codex/skills が一覧に反映されるか確認する

コマンドのイメージは次のようになります。

mkdir C:\Users\<YOUR_USERNAME>\MyProject\.agent\skills
mklink /D C:\Users\<YOUR_USERNAME>\MyProject\.claude\skills C:\Users\<YOUR_USERNAME>\MyProject\.agent\skills
mklink /D C:\Users\<YOUR_USERNAME>\MyProject\.codex\skills C:\Users\<YOUR_USERNAME>\MyProject\.agent\skills

検証して分かったこと

今回の検証で大事だったのは、認識元は1つに固定されているとは限らず、セッション再起動の影響が大きい という点です。

途中の観測だけで結論を出すと誤ることがある

一度は、Codex のスキル一覧がグローバル C:\Users\<YOUR_USERNAME>\.codex\skills だけを見ているように見えました。その後に Codex を再起動して確認したところ、プロジェクトごとの .codex/skills シンボリックリンクでもスキル一覧に認識される ことが確認できました。

今回の最終結論

プロジェクト内 .codex/skills にスキルが見えていれば認識される
その実体がシンボリックリンク先でも問題ない
ただし、反映確認には Codex の再起動が必要なことがある

この構成にしたメリット

1. スキルの正本が1つになる

SKILL.md や reference 群を複数コピーで持たなくてよくなります。

2. ClaudeとCodexで役割を分けやすい

.claude/CLAUDE.md は Claude 用のコンテキスト
.codex/AGENTS.md は Codex 用のコンテキスト
スキル本体は .agent/skills/ に集約

3. Git履歴がきれいになる

移設をGit履歴上で rename として認識させやすくなり、履歴が追いやすいまま移設できます。

ウィンドウズで詰まりやすいポイント

Windowsでシンボリックリンクを作ると、環境によっては次のようなエラーになります。

You do not have sufficient privilege to perform this operation.
Administrator privilege required for this operation.

対処の考え方

まずは次のどちらかを確認します。

管理者権限のターミナルで実行しているか
Windows の開発者モードが有効か

ただし、エラーメッセージだけで判断しない方が安全です。PowerShell で LinkType を確認し、リンク先が .agent/skills を向いているかを見て判断するのが確実です。

Gitで管理するもの、しないもの

Gitで管理するもの

.agent/skills/**
.claude/CLAUDE.md
.codex/AGENTS.md
新構成を説明するドキュメント

Gitで管理しないもの

.claude/settings.local.json
.claude/skills のリンク実体
.codex/skills のリンク実体
個人ローカル設定

共有すべき知識は Git に残し、環境依存のものはローカルに閉じ込める方針です。

まとめ

WindowsでClaude CodeとCodexのスキルを共通化するなら、.agent/skills を正本にして .claude/skills と .codex/skills から参照する構成はかなり有効です。

スキルの正本は .agent/skills に集約する
.claude と .codex は入口として使い分ける
プロジェクトごとの .codex/skills シンボリックリンクでも、再起動後にスキル一覧へ認識される

シンボリックリンク周りは Windows 特有の権限差に少し注意が必要ですが、構成自体はシンプルで、保守性は高いです。AIエージェントの設定が増えてきたら、早めに一本化しておくと後でかなり楽になります。