はじめに
普段、Claude CodeとCodexを両方使っています。
どちらにもスキルの機能があって、よく使う作業の手順をSKILL.mdにまとめておくと、エージェントが必要だと判断したときに読んで使ってくれます。
便利なのでいくつもスキルを作っていたのですが、Claude Code用とCodex用で置き場所が別々なので、同じスキルを2か所で管理する状態になっていました。
今回、スキルを1か所にまとめて、Claude CodeとCodexの両方から使えるようにしたので、そのやり方を紹介します。同じように両方のツールを使っている人の参考になればと思います。
以前の状態
スキルは、それぞれのツールの置き場に置いていました。
- Claude Code →
~/.claude/skills/ - Codex →
~/.codex/skills/
同じ作業をどちらのツールからも頼みたいので、同じスキルを両方に置くことになります。そうすると、片方だけ直して、もう片方は古いまま、ということが起きます。
整理しようと数えてみたら、それぞれの置き場に置いていたスキルは合わせて20本以上ありました。そのうち7本は両方に置いていて、5本は中身がずれていました。どっちが新しいのかは、見比べないと分からない状態です。
~/.agents/skillsにまとめた
やったことはシンプルで、スキルの本体を~/.agents/skillsの1か所に置いて、そこから各ツールに見せるようにしました。
~/.agents/skills/ ← スキルの本体はここだけ
├── sample-skill/
│ └── SKILL.md
└── demo-skill/
└── SKILL.md
~/.claude/skills/sample-skill → ../../.agents/skills/sample-skill ← シンボリックリンク
~/.codex/skills/ ← 何も置かない
- Codexは
~/.agents/skillsを最初から読みにいくので、何もしなくていい - Claude Codeは
~/.agents/skillsを読まないので、~/.claude/skillsにシンボリックリンクを張る
これで、スキルを直すときは~/.agents/skillsだけを触ればよくなりました。
なぜ~/.agents/skillsなのか
自分で新しく決めた場所ではなく、Codexが最初から探しにくる場所だからです。Codexの公式ドキュメントでも、ユーザー個人のスキルの置き場として$HOME/.agents/skillsが紹介されています。
それに、スキルをインストールするCLI（npx skills）で入れたスキルが、もともとここに入っていて、Claude Codeからもリンクで使っていました。新しく場所を作るより、すでにある場所に寄せたほうが手間が少ないので、ここにまとめることにしました。
Codexがどこを読んでいるかは、次のコマンドで確認できます。
codex debug prompt-input | grep -o '`r[0-9]` = `[^`]*`'
`r0` = `/Users/you/project/.codex/skills`
`r1` = `/Users/you/.agents/skills`
`r2` = `/Users/you/.codex/skills/.system`
ここに出ていれば、そのフォルダのスキルはCodexに認識されています。実際にどのスキルを使うかは、そのときの依頼内容を見てCodexが判断します。
設定方法
スキルを置く
~/.agents/skills/<スキル名>/SKILL.mdを作ります。
---
name: sample-skill
description: サンプル用のスキル。〇〇をするときに使う。△△のときは使わない。
---
# Sample Skill
## 手順
1. 対象のファイルを読む
2. 〇〇の形式に整える
3. 結果を表示する
descriptionは、どのスキルを使うかをエージェントが判断するときの材料になるので、いつ使うのか（いつ使わないのか）を具体的に書いておきます。
nameやdescriptionの役割、本文の書き方は、以前に書いた記事
CodexのSkillsについて でもまとめています。
1つ気をつけているのは、本文に/sample-skillのようなツール専用の呼び出し方を書かないことです。同じファイルを両方のツールが読むので、どちらで読んでも通じる書き方にしています。
Claude Codeから使えるようにする
Claude Codeは~/.claude/skillsを読むので、そこにシンボリックリンクを張ります。
ln -s ../../.agents/skills/sample-skill ~/.claude/skills/sample-skill
リンクは相対パスで張っています。こうしておくと、ユーザー名が違うMacに~/.agentsごと持っていっても、リンクがそのまま使えます。
Claude Codeは、スキルのフォルダがシンボリックリンクでも読んでくれます（公式ドキュメントにも書かれています）。
Codex側は何もしない
Codexは~/.agents/skillsを読むので、設定はいりません。
気をつけるのは、~/.codex/skillsに同じスキルを置かないことです。同じ名前のスキルが両方にあると、Codexはどちらかを優先するわけではなく、両方を一覧に出します。中身がずれていると、どちらが使われたのか分かりにくくなるので、~/.codex/skillsは空にしています（最初から入っている.systemはそのままで大丈夫です）。
片方のツールだけで使いたいとき
ツール専用の機能を使うスキルは、もう片方に見せても使えないので、見せる相手を分けています。
- Claude Codeに見せたくない → リンクを張らない
- Codexに見せたくない →
~/.codex/config.tomlで無効にする
[[skills.config]]
path = "/Users/you/.agents/skills/sample-skill/SKILL.md"
enabled = false
config.tomlを変えたら、Codexの再起動が必要です。
勝手に使われたくないとき
呼んだときだけ使ってほしいスキルは、ツールごとに書く場所が違います。
---
name: sample-skill
description: サンプル用のスキル。
disable-model-invocation: true
---
policy:
allow_implicit_invocation: false
CodexはSKILL.mdのdisable-model-invocationを設定として扱わないので、Claude Code側だけ書いても、Codexでは自動で使われることがあります。両方書いておくと安心です。Codexでも$sample-skillと打てば呼び出せます。
使ってみて
置き場をまとめても、新しいスキルが別の場所に作られることがありました。各ツールのスキル作成機能を使うと、そのツールの置き場に作られることがあるためです。Codexの$skill-creatorは、場所を指定しないと~/.codex/skillsに作りますし、手で作るときに置き場を間違えることもあります。
そのため、起動時に置き場をチェックするようにしています。~/.claude/skillsにリンクではない実体が置かれていないか、空にしているはずの~/.codex/skillsに何か入っていないか、を見て件数を出すだけのものです。ずれが見つかったら、~/.agents/skillsに移し、Claude Code用のリンクを整えます。
普段はClaude Codeをメインで使っているので、チェックを動かすのはClaude Codeの起動時だけにしています。Codexにも起動時に動くフックの仕組みはあるので、Codex中心の人は同じチェックをそちらに入れると同じことができます。
まとめ
Claude CodeとCodexのスキルを~/.agents/skillsにまとめて、
- Codexはそのまま読む
- Claude Codeにはシンボリックリンクで見せる
という形にしました。スキルを直す場所が1か所になったので、どっちが新しいのかを気にする必要がなくなりました。
設定自体はリンクを張るくらいで、ほとんど手間はかかりません。ただ、置き場を決めただけだと新しいスキルがまた散らばるので、ときどき置き場を確認するか、起動時にチェックする仕組みを入れておくと安心です。
なお、ここにまとめたのは、どのプロジェクトでも使う個人用のスキルです。特定のプロジェクトでしか使わないスキルは、これまでどおりそのプロジェクトの配下に置いています。
Claude CodeとCodexを両方使っていて、同じスキルを2か所で直している人は、試してみてください。