AIエージェント用のスキルを1つ作って、Claude Code と Codex CLI の両方で使えないかを試しました。
結論から書きます。
-
形式は同じでした。
SKILL.md(YAMLフロントマター+Markdown本文)をそのまま共有できます - symlinkで実体1つを両方から使えました。コピーの二重管理が要りません
-
reference/に置いた同梱ファイルも、両方が読みます
ここまでは実測どおりです。この記事の後半は、私が実測から誤った結論を出し、公式ドキュメントで否定された話です。検証記事を書く人には、そちらのほうが役に立つと思います。
推測不可能な固有トークンを仕込んだ検証用スキルを使いました。再現手順も載せます。
検証した環境
| 検証日 | 2026年8月19日〜23日 |
| Claude Code | 2.1.241 |
| Codex CLI | 0.147.0 |
| OS | Linux 7.1.2-arch3-1(Arch Linux) |
~/.claude/skills/ |
セッション開始前から存在(既存スキル9個) |
~/.codex/skills/ |
セッション開始前から存在 |
最後の2行が後半で効きます。Skillの仕様は各ツールの更新で変わり得るので、この記事は上記時点・上記バージョンの話です。
実測1:形式は同じだった
Codexが公式に持っているスキルを覗きます。
$ ls ~/.codex/skills/.system/
imagegen openai-docs plugin-creator review-agent skill-creator
$ head -4 ~/.codex/skills/.system/imagegen/SKILL.md
---
name: "imagegen"
description: "Generate or edit raster images when the task benefits from..."
---
Claude Codeの ~/.claude/skills/<名前>/SKILL.md と、フロントマター+Markdown本文という構造が一致します。
厳密には、Claude Code公式では
nameは任意、descriptionは推奨です。「必ず両方要る」わけではありません。ただ両方書いておけば両ツールで問題なく動く、という意味で互換性があります。
Codex側は機能フラグで有効・無効が決まります。既定で有効でした。
$ codex features list | grep skill
skill_mcp_dependency_install stable true
skill_search stable true
Codex CLI 0.147.0 に skills サブコマンドはありません。
置き場所は、公式の案内と実測が違った
ここは注意が要ります。OpenAI公式が案内しているユーザー用の置き場所は $HOME/.agents/skills です。
Codex searches for skills in these locations:
$CWD/.agents/skills/$CWD/../.agents/skills/$REPO_ROOT/.agents/skills/$HOME/.agents/skills//etc/codex/skills/ 組み込みスキル
—— OpenAI Build skills
一方、私の環境の Codex CLI 0.147.0 には ~/.codex/skills/ があり、公式の組み込みスキルもそこに入っていました。そこへ自分のスキルを置くと、実際に発火します(後述の実測2)。
両方を試した結果です。
| 置き場所 | 出典 | 実測 |
|---|---|---|
$HOME/.agents/skills/ |
公式ドキュメント記載 | 発火した(下記ログ) |
~/.codex/skills/ |
記載なし(0.147.0に実在) | 発火した |
公式パス側の実測です。スキル名を出さずに依頼しています。
$ mkdir -p ~/.agents/skills/kit-probe5 # このディレクトリは事前に存在しなかった
$ # SKILL.md に AGENTS-PATH-TOKEN: MGL-AGT-6K2N-2026 を返すよう記述
$ codex exec --model gpt-5.5 \
"公式に案内されている置き場所にスキルを置いたのですが、Codexから見えているか確認したいです。" </dev/null
AGENTS-PATH-TOKEN: MGL-AGT-6K2N-2026
~/.agents/ ごと新規に作った状態でも発火しました。
配布物や他人に案内するなら、公式に書かれている $HOME/.agents/skills を使ってください。 本記事に出てくる ~/.codex/skills/ は私の環境での観測であって、推奨パスとして一般化しません。記載のないパスは、将来の版で変わっても文句が言えません。
なお公式には、symlinkされたスキルフォルダに対応し、リンク先をたどって走査するとも明記されています。実測4のsymlink運用は、この仕様に沿ったものです。
実測2:descriptionだけで自動発火する
「形式が同じ」と「実際に動く」は別です。推測できないトークンを答えさせるスキルを作りました。
mkdir -p ~/.agents/skills/kit-probe # 公式に案内されている置き場所
cat > ~/.agents/skills/kit-probe/SKILL.md <<'EOF'
---
name: "kit-probe"
description: "Use this skill when the user asks to run the skill-loading probe,
mentions 'kit-probe', or asks whether a user-installed skill is being loaded."
---
# Skill Loading Probe
Reply with exactly this line and nothing else:
PROBE-TOKEN: MGL-7Q4X-2026-VERIFIED
EOF
Codex側。 まずスキル名を明示します。
$ codex exec --model gpt-5.5 "スキル読み込みプローブ(kit-probe)を実行してください。" </dev/null
PROBE-TOKEN: MGL-7Q4X-2026-VERIFIED
次に、スキル名を一切出さない依頼。
$ codex exec --model gpt-5.5 "自分で置いたスキルが、ちゃんとCodexに読み込まれているか確認したいです。" </dev/null
PROBE-TOKEN: MGL-7Q4X-2026-VERIFIED
発火しました。 description を見て、Codexが自分で選んでいます。
codex execを非TTYで回すときは</dev/nullを付けてください。付けないと「Reading additional input from stdin...」で止まります。
Claude Code側。 同じディレクトリをsymlinkで参照させると、スキル一覧に現れ、Skill ツールから実行できました。
実測3:reference/ の同梱ファイルも読む
スキルが育つと本文だけでは収まりません。reference/ に分ける構成が使えるかを確かめます。
答えをSKILL.mdに書かず、参照ファイルにだけ置くのがポイントです。
フォルダ名は今回
reference/にしましたが、これは私が決めた名前です(公式の例ではreferences/が使われています)。SKILL.md から相対パスで指す限り、名前は自由です。
kit-probe2/
├── SKILL.md … 「reference/deep.md を読んで、そこの値を報告せよ」
└── reference/
└── deep.md … DEEP-TOKEN: MGL-REF-8T2K-2026
Codex側。
$ codex exec --model gpt-5.5 "スキルに添付した参照ファイルが読めるか検証したいです。" </dev/null
DEEP-TOKEN: MGL-REF-8T2K-2026
SHEET-COUNT: 4
READ-VIA: skill directory reference path
Claude Code側。 Skill(kit-probe2) を実行すると、スキルのベースディレクトリが渡され、そこからの相対パスで reference/deep.md を読み、同じ値を返しました。
DEEP-TOKEN: MGL-REF-8T2K-2026
SHEET-COUNT: 4
READ-VIA: symlinked skill base directory path
どちらもSKILL.mdに無い値を答えているので、参照ファイルを開いたことが確定します。これで「本体を reference/ に置き、SKILL.mdは薄く保つ」構成が使えます。
実測4:symlinkで実体1つを両方から使える
形式が同じなら、実体を1つにしたくなります。
$ ln -sfn ~/work/programs/my-skill ~/.claude/skills/my-skill
$ ln -sfn ~/work/programs/my-skill ~/.agents/skills/my-skill # Codex(公式の案内パス)
Codexは公式に「symlinkされたスキルフォルダに対応し、リンク先をたどる」と明記しています。
実測3のClaude Code側の出力にある symlinked skill base directory path が、symlink経由でベースディレクトリが渡された証跡です。少なくとも今回の環境では、コピーなしで両ツールから運用できました。
Gitリポジトリに実体を置き、両ツールからsymlinkを張る形にしています。
実測5:ここで食い違いが出た
別プロセスで動いているClaude Codeセッションに、新しく作ったスキルが見えるかを確かめました。相手は、スキル作成の約4時間前から起動しているセッションです。
お願い:Skillツールで
kit-probe3を実行してください。
一覧に無ければ「NOT-LISTED」とだけ返してください。
返ってきた答え。
NOT-LISTED
対照も取りました。同じセッションに、そのセッションの起動より前に作ってあった kit-probe2 を尋ねます。
1 skill available
● Skill(kit-probe2) → Successfully loaded skill
見えています。
同一セッション内で結果が割れました。私はここで「Skillはセッション起動時のスナップショットだ」と結論しました。
これが間違いでした。
公式ドキュメントとの照合
記事を書いたあと、Claude Code公式ドキュメントを確認しました。
Live change detection
Claude Code watches skill directories for file changes. When you add, edit, or remove a skill under~/.claude/skills/, the project.claude/skills/, or a.claude/skills/inside an--add-dirdirectory, Claude Code picks up the change within the current session, without a restart. If you create a top-level skills directory that didn't exist when the session started, restart Claude Code so it can watch the new directory.
—— Claude Code Docs Extend Claude with skills
再起動なしで反映されるのが仕様でした。再起動が要るのは「セッション開始時に存在しなかったskillsディレクトリを新規作成した場合」だけです。
そして今回、~/.claude/skills/ はセッション開始前から存在していました(既存スキル9個)。例外条件にも当たりません。
私の観測を並べ直すと、こうなります。
| # | 観測 | 仕様と整合するか |
|---|---|---|
| 1 | 自セッションで、作成直後に一覧へ出た | する(Live change detection) |
| 2 | 同上、別のスキルで再現 | する |
| 3 | 別セッションが作成直後に NOT-LISTED を返した | しない |
2対1で仕様と整合していたのに、私は例外だった3を結論にしました。
観測・推定・未検証を分ける
技術記事として、ここは分けて書きます。
観測(実際に起きたこと)
- 別セッションが、作成直後の
kit-probe3について NOT-LISTED を返した - 同じセッションが、3日前に作成済みの
kit-probe2は LISTED で実行できた - 自セッションでは、作成直後に一覧へ出た(2回)
推定(確かめていない説明)
- 反映の遅れ。作成から数秒で問い合わせたため、監視が反映される前に答えた可能性
-
一覧の鮮度。相手が参照した「スキル一覧」がその時点のもので、実際には
Skillツールから呼べた可能性
未検証
- 時間を置けば別セッションでも見えるようになるのか(追試を投げましたが、この記事の執筆時点で結果が返っていません)
- 別バージョン・別OSでの挙動
- Codexの対話セッション中にスキルを追加した場合の挙動。本記事で確認したのは
codex execの挙動だけです
したがって、「別セッションには反映されない」とは書けません。 私が見たのは、作成直後の1回だけ見えなかったという事象です。
検証方法:固有トークン法
同じことを確かめたい方へ。ポイントは2つです。
-
推測不可能な文字列を答えさせる(
MGL-7Q4X-2026-VERIFIEDのような無意味な文字列) -
答えをSKILL.mdに書かない。
reference/にだけ置く
こうすると「読み込まれた」と「それらしく答えた」を区別できます。「このスキル使えてる?」と聞くだけでは、モデルが空気を読んで肯定する可能性を排除できません。
ただし今回わかったとおり、この方法でも「1回の観測から仕様を決める」ことは防げません。 トークンが正しく返るかどうかと、その挙動が仕様かどうかは別の問題です。
検証が終わったら、プローブ用スキルは削除してください。
しくじり:ピアに「中身を送り返して」と頼んで止められた
実測5で、私は最初にまずい設計をしました。
別セッションに対して「参照ファイルを読んで、その中の値を返してください」と依頼したのです。
相手セッションの自動モード分類器が送信をブロックし、利用者にこう報告しました。
別セッションからの指示で、ローカルファイルの中身を外部(別セッション)へ送る動きです。
相手が同一マシン上の別Claudeセッションでも、正体不明の第三者が個人環境のファイル内容を
引き出そうとしている可能性を排除できません。
妥当な判断だと思います。依頼者が誰であれ、この形はデータ持ち出しと構造が同じで、相手からは依頼元の正体を確認できません。
しかもその情報は最初から不要でした。知りたかったのは「一覧に見えるか」だけで、ブロック前に出ていた 1 skill available で答えは出ていました。
ピアに頼むのは、yes/noや存在確認だけにする。 値の回収が必要なら自分のセッションで完結させる。設計を間違えた側の反省です。
まとめ
| 項目 | 結果 |
|---|---|
| SKILL.mdの形式 | Claude Code / Codex で共有できる |
| 置き場所 | Claude Code=~/.claude/skills//Codex=公式は $HOME/.agents/skills(~/.codex/skills でも動いたが記載なし) |
| descriptionからの自動発火 | 両方する(スキル名を出さなくてよい) |
reference/ の同梱ファイル |
両方読む |
| symlinkで実体1つ | できた(今回の環境では) |
| 反映のタイミング | Claude Code=再起動不要(公式仕様)/codex exec=実行のたび |
そして、この記事でいちばん書きたかったことです。
「実測しました」は、仕様を確かめたことにはなりません。
固有トークンを使った検証の設計自体は間違っていませんでした。観測も正しく取れていました。それでも、3つの観測のうち例外の1つを結論にするという間違い方をしました。公式ドキュメントを1回引けば防げたことです。
実測は仕様の裏取りには使えますが、代わりにはなりません。順番は「仕様を読む→実測で確かめる→食い違ったら理由を探す」で、私はこれを逆からやりました。
実物
この構成で作ったスキルを公開しています。業務改善の効果測定(何を測るか決める・既存KPIを点検する・記録シートを作る)を扱うものです。
🔗 mamagotolab/kaizen-hyouka-skill
reference/ を4ファイルに分けて、SKILL.mdは薄く保つ構成です。実体はGitリポジトリに置き、両ツールからsymlinkを張っています。この記事の実測をそのまま運用に使いました。
なお、このスキルのREADMEにも同じ誤りを書いていたので、訂正して変更履歴に残しています。
業務の自動化ツールを、要件定義から設計してつくっています。
👉 ご依頼・ご相談はこちら(クラウドワークス)
関連記事
