0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

【実測】同じSKILL.mdをClaude CodeとCodexで共有する──そして「実測だけで仕様を断定した」失敗

0
Posted at

【実測】同じSKILL.mdをClaude CodeとCodexで共有する──そして「実測だけで仕様を断定した」失敗

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-dir directory, 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つです。

  1. 推測不可能な文字列を答えさせる(MGL-7Q4X-2026-VERIFIED のような無意味な文字列)
  2. 答えを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にも同じ誤りを書いていたので、訂正して変更履歴に残しています。


業務の自動化ツールを、要件定義から設計してつくっています。
👉 ご依頼・ご相談はこちら(クラウドワークス)

関連記事

0
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?