はじめに

普段、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を作ります。

~/.agents/skills/sample-skill/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で無効にする

~/.codex/config.toml

[[skills.config]]
path = "/Users/you/.agents/skills/sample-skill/SKILL.md"
enabled = false

config.tomlを変えたら、Codexの再起動が必要です。

勝手に使われたくないとき

呼んだときだけ使ってほしいスキルは、ツールごとに書く場所が違います。

Claude Code（SKILL.mdの先頭）

---
name: sample-skill
description: サンプル用のスキル。
disable-model-invocation: true
---

Codex（スキルのフォルダ内のagents/openai.yaml）

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か所で直している人は、試してみてください。

参考リンク