Claude Code と Codex のスキルの違い：SKILL.md の作り方・置き場所・呼び出し方（2026 年 10 月）

スキルは SKILL.md を入れたフォルダで、Claude Code も Codex も同じ Agent Skills の形式を使い、ふだんは名前と説明だけを読み込んで、使うときに本文を読み込みます。違うのは置き場所（Claude Code は .claude/skills/、Codex は .agents/skills）、自分で呼ぶ書き方（/名前 と $名前）、そして各ツールが独自に足した設定（Claude Code のフロントマターの項目と、Codex の agents/openai.yaml）です。

毎回同じ手順や注意書きをチャットに貼っているなら、それはスキルにできます。この記事では、Claude Code と Codex を日常で使う開発者に向けて、スキルの仕組み、2 つのツールの違い、作り方、置き場所と共有、説明の書き方、ほかの仕組みとの違い、各社が勧める書き方を並べます。とくに、allowed-tools は制限ではなく事前承認であること、Claude Code が一覧で説明を切るのは description と when_to_use を合わせて 1,536 文字から（仕様の description の上限は 1,024 文字）であること、Codex の置き場所が .agents/skills であることは、いまのドキュメントのとおりに書きます。

対象は Claude Code 2.1.306 と Codex CLI 0.163.0（この記事を書いたマシンで claude --version と codex --version が返した版）です。書いてあることは、2026 年 10 月 21 日に読んだ公式ドキュメント（Claude Code の skills、Anthropic の Agent Skills の概要とベストプラクティス、Agent Skills の仕様、learn.chatgpt.com の Codex のスキル関連のページ）にもとづきます。どちらのツールでもスキルを実際に動かして確かめてはいないため、ドキュメントに書かれていないことは「書かれていない」と書きます。

スキルとは（Claude Code と Codex に共通の仕組み）

スキルとは、ある作業の手順や知識を SKILL.md というファイルにまとめ、必要なときだけ AI に読ませる仕組みです。Claude Code のドキュメントは "Claude Code skills follow the Agent Skills open standard"、Codex のドキュメントは "Skills build on the open agent skills standard" と書いており、土台は同じ Agent Skills の仕様です。

仕様の上では、スキルは少なくとも SKILL.md を 1 つ持つフォルダで、そこに scripts/（実行するコード）、references/（資料）、assets/（テンプレートなど）を足せます。SKILL.md は YAML のフロントマターと Markdown の本文でできていて、仕様の必須項目は name（64 文字まで、小文字・数字・ハイフン、フォルダ名と同じ）と description（1,024 文字まで）です。

読み込みは 3 段階です。仕様によると、まず全スキルの name と description（1 つにつき約 100 トークン）を起動時に読み、スキルを使うと決めたときに SKILL.md の本文（5,000 トークン未満を推奨）を読み、scripts/ などのファイルは必要になったときに読みます。だからスキルをいくつ入れても、使わないスキルの本文は文脈を圧迫しません。Claude Code のドキュメントは、CLAUDE.md と比べて "a skill's body loads only when it's used" と説明しています。

Claude Code と Codex のスキル比較

形式の芯は同じですが、置き場所、呼び出し方、自動で使われないようにする設定、ツールの扱いは別々に作られています。

Claude Code でスキルを作る

Claude Code では、置き場所にフォルダを作って SKILL.md を書けば、それがそのまま /フォルダ名 のコマンドになります。フロントマターはなくても動きますが、Claude が自分で使うかどうかは description で決まるので、これだけは書きます。

ドキュメントにある例を、プロジェクトの .claude/skills/deploy/SKILL.md に置いた場合で見ます。

---
name: deploy
description: Deploy the application to production
disable-model-invocation: true
---

Deploy $ARGUMENTS to production:

1. Run the test suite
2. Build the application
3. Push to the deployment target
4. Verify the deployment succeeded

/deploy staging と打つと、$ARGUMENTS に staging が入って動きます。disable-model-invocation: true があるので、Claude が「準備ができたようなので」と自分から本番に出すことはありません。ドキュメントは、/commit や /deploy のように外に影響する作業にこの設定を勧めています。

よく使う項目は次のとおりです。

• description：何をするスキルで、いつ使うか。when_to_use と合わせて 1,536 文字で切られるので、いちばん大事な使い道を先頭に書きます。
• disable-model-invocation：true にすると、自分で /名前 と打ったときだけ動きます。説明も文脈に入らなくなるので、一覧の予算も空きます。
• allowed-tools：そのスキルを呼んだターンのあいだ、確認なしで使えるツールです。ドキュメントは "It does not restrict which tools are available: every tool remains callable" と書いています。制限したいときは disallowed-tools か、権限の設定の deny を使います。
• context: fork と agent：スキルを新しいサブエージェントで動かします。そのサブエージェントは "doesn't see your conversation history" なので、本文だけで指示が通じるように書きます。
• paths：ファイルのパターンを書くと、合うファイルを扱うときだけ自動で読み込まれます。

本文には ! とバッククォートで囲んだコマンドを書くと、Claude に渡す前にそのコマンドを実行して結果に置き換える機能もあります（ドキュメントの最初の例は git diff HEAD の出力を入れています）。セッション中に ~/.claude/skills/ やプロジェクトの .claude/skills/ を書き換えると、再起動しなくても反映されます。

Codex でスキルを作る

Codex では、組み込みの作成用スキルに頼むか、.agents/skills にフォルダを作って SKILL.md を書きます。作成用スキルは次のように呼び、何をするスキルか、いつ使うか、指示だけにするかスクリプトを入れるかを聞いてきます（既定は指示だけ）。

$skill-creator

手で作るときの最小の形は、ドキュメントでは次のとおりです。name と description はどちらも必須です。

---
name: skill-name
description: Explain exactly when this skill should and should not trigger.
---

Skill instructions for ChatGPT or Codex to follow.

呼び出しは、CLI と IDE 拡張で /skills を開くか、$ でスキルの名前を指定します。依頼が description に合えば、Codex が自分で選ぶこともあります。Codex はスキルの変更を自動で見つけ、反映されないときは再起動するよう案内されています。

Codex に固有なのは、スキルのフォルダに置く agents/openai.yaml です。ChatGPT のデスクトップアプリでの表示名やアイコン、呼び出しの方針、必要なツールを書けます。自動で使われないようにするには次のように書き、そのあとも $ で呼べば動きます。

policy:
  allow_implicit_invocation: false

スキルを消さずに止めるには、~/.codex/config.toml に次のように書いて Codex を再起動します。

[[skills.config]]
path = "/path/to/skill/SKILL.md"
enabled = false

ほかの人が作ったスキルを入れるには $skill-installer を使います。ドキュメントの例は $skill-installer linear で、$linear スキルが入ります。

スキルの置き場所と共有（個人・プロジェクト・プラグイン）

自分だけで使うスキルはホームのフォルダに、チームで使うスキルはリポジトリにコミットし、リポジトリの外の人にも配るならプラグインにします。この考え方は 2 つのツールで同じで、フォルダの名前が違います。

どちらも、起動したフォルダからリポジトリのルートまでの各階層を探すので、packages/frontend/ で起動してもルートのスキルが使えます。Claude Code は、起動したフォルダより下の .claude/skills/ を、Claude がそのフォルダのファイルを読むか編集したときに読み込みます。

同じ名前のスキルが 2 か所にあるときの扱いは違います。Claude Code は「エンタープライズ > 個人 > プロジェクト」の順で 1 つだけを /名前 で動かし、Codex は "If two skills share the same name, Codex doesn't merge them; both can appear in skill selectors" と、両方を残します。

Claude Code の個人のスキル（~/.claude/skills/）は、Cowork とクラウドのセッションでは読み込まれません。そちらで使うには、スキルを claude.ai のアカウントで有効にします（アップロードできるフロントマターは仕様の 6 項目だけ）。Codex のプラグインは ChatGPT の Chat と Work、ChatGPT デスクトップアプリの Codex、Codex CLI で使えますが、IDE 拡張では使えません。

~/.codex/skills は、いまの Codex のドキュメントの置き場所の一覧にありません。0.163.0 がまだそこを読むかどうかは確かめていないので、新しく作るなら $HOME/.agents/skills に置くのが確かです。

1 つの SKILL.md を両方のツールで使う方法は、どちらのドキュメントにも書かれていません。Claude Code は .agents/skills を、Codex は .claude/skills を読むとはどこにも書かれていないので、置き場所はそれぞれに必要です。ただ、どちらのドキュメントも、自分の置き場所にあるシンボリックリンクのフォルダをたどると書いているので、スキルのフォルダ（<名前>/）を、もう片方の置き場所からシンボリックリンクで指す方法はとれます（試してはいません）。両方で使うスキルのフロントマターは仕様の項目（name と description など）にとどめるのが無難です。Claude Code は知らない項目を黙って無視しますが、Codex が Claude Code 独自の項目をどう扱うかはドキュメントにありません。

description の書き方と、スキルが自動で使われないとき

自動で使われるかどうかは、おもに description で決まります（Claude Code では when_to_use と paths も効きます）。両社とも、何をするか、いつ使うかを、依頼に出てくる言葉で、いちばん大事な使い道から書くよう勧めています。

Codex のドキュメントは "Front-load the key use case and trigger words so a host can still match the skill if descriptions are shortened" と書きます。スキルが多いと説明が短くされるので、先頭の言葉で合わせられるようにする、という意味です。Anthropic のベストプラクティスは、説明を三人称で書くこと（"Always write in third person"）と、"Helps with documents" のようなあいまいな説明を避けることを挙げています。仕様にも、良い例として「PDF からテキストと表を取り出し、フォームを埋め、結合する。PDF を扱うとき、ユーザーが PDF やフォームに触れたときに使う」という形の説明が載っています。

Claude Code でスキルが使われないとき、ドキュメントは次の順で確かめるよう書いています。

1. 説明に、ユーザーがふつうに使う言葉が入っているか
2. What skills are available? と聞いて、スキルが一覧に出るか
3. 依頼の言い方を説明に近づけると使われるか
4. /スキル名 で直接呼べるか

フロントマターの YAML が壊れていると、本文は読み込まれても説明が空になり、/スキル名 では動くのに自動では使われません。claude plugin validate .claude/skills（v2.1.233 以降）で、読めない SKILL.md を探せます。スキルが多すぎて説明が落ちているときは、/doctor で一覧の大きさを、/skill-doctor（v2.1.252 以降）で各スキルのコストと使われた回数を見られます。Codex は、スキルが多くて一部を一覧から外したときに警告を出すので、/skills で一覧を見ます。

逆に、使ってほしくないときに使われるなら、説明を具体的にするか disable-model-invocation: true を足します。「毎回必ず守らせたい決まり」はスキルに書くより、フックにするようドキュメントは勧めています。Claude がスキルの指示から外れても、フックはイベントのたびに必ず動くからです。フックでコマンドを止める例は Claude Code のフックでエージェントの push を止める方法にまとめています。

スキル・カスタムコマンド・サブエージェント・フック・MCP の違い

スキルは「手順を必要なときだけ読ませる」もので、ほかの仕組みとは役割が分かれています。Codex のドキュメントは "skills define repeatable workflows, and MCP connects them to external tools and systems" と、スキルと MCP を組み合わせる前提で書いています。

Claude Code のドキュメントは、CLAUDE.md の一部が「事実」ではなく「手順」に育ったら、スキルに移すよう勧めています。カスタムコマンドとの関係は、.claude/commands/deploy.md と .claude/skills/deploy/SKILL.md がどちらも /deploy になり、同名ならスキルが動くというものです。Codex のカスタムプロンプトは ~/.codex に置くのでリポジトリで共有できず、共有したいならスキルを使うよう書かれています。

サブエージェントとの違いと、Claude Code のエージェントチームまで含めた比べ方は、Claude Code と Codex のサブエージェントの違いで表にしています。MCP そのものの仕組みは MCP とは何かを見てください。

スキルのベストプラクティス（Anthropic と OpenAI の推奨）

両社の勧めは「短く絞る」と「呼ばれ方を試して確かめる」の 2 点で重なります。以下は各社のドキュメントの推奨をまとめたもので、英語の部分はドキュメントからそのまま引いています。

Anthropic（Agent Skills のベストプラクティスと Claude Code のドキュメント）：

• "Concise is key"。文脈は "a public good" で、Claude がすでに知っていることは書かない。
• SKILL.md は 500 行未満にし、詳しい資料は別ファイルに分けて、SKILL.md から 1 段だけでたどれるようにする（"Keep references one level deep from SKILL.md"）。
• 名前は processing-pdfs のような動名詞の形を勧め、helper や utils のようなあいまいな名前を避ける。
• スキルを作る前に評価を作る（"Build evaluations first"）。Claude Code のドキュメントは、新しいセッションでスキルありとなしを比べるよう書いています。
• 大事な指示は SKILL.md の上のほうに書く。会話が圧縮されると、呼んだスキルは最初の 5,000 トークンだけが残り、残すスキル全体で 25,000 トークンまでだからです。
• 使わないスキルも毎ターン一覧の分だけ文脈を使うので、/skill-doctor で見直す。

OpenAI（Codex の Build skills）：

• "Keep each skill focused on one job."
• "Prefer instructions over scripts unless you need deterministic behavior or external tooling."
• "Write imperative steps with explicit inputs and outputs."
• "Test prompts against the skill description to confirm the right trigger behavior."

安全面では、Anthropic の概要が "Use Skills only from trusted sources" と書き、使う前にスクリプトや画像も含めて全ファイルを読むよう勧めています。Claude Code では、リポジトリのスキルの allowed-tools が "even in a -p run in a folder you've never trusted" で効くので、人のリポジトリで Claude Code を動かす前に .claude/skills/ を確かめます。

スキルでページを公開する（Convika の publish-page スキル）

スキルは手順を書く場所、MCP はツールにつなぐ道、という分け方の実例として、Convika の Claude Code プラグインにある publish-page スキルを紹介します。Convika は、AI が書いた HTML のページを保存し、非公開のプレビューのリンクを返し、頼まれたら公開し、フォームの送信と訪問を記録するサービスです。

プラグインは Convika のリモートの MCP サーバー（https://mcp.convika.com）への接続と、publish-page スキルを足します。Claude Code では次のように入れます。

/plugin marketplace add tomoyaf/convika-mcp
/plugin install convika@convika

/mcp から Convika を選んで Authenticate を押すと、ブラウザで Convika にログインします（OAuth なので API キーは使いません）。あとは /convika:publish-page landing.html と打つか、「landing.html を Convika で公開して」と頼みます。スキルの手順では、Claude はページを 1 つの HTML にまとめて保存し、非公開のプレビューのリンク（1 時間で開けなくなります）を見せ、「公開して」と言われていても、いったん止まって公開してよいかを聞きます。公開はプレビューを見たあとです。

publish-page スキルは Claude Code のプラグインで配っています。Codex からは、MCP サーバーを次のコマンドでつなぎ、「このページを Convika で公開して」と頼みます。

codex mcp add convika --url https://mcp.convika.com
codex mcp login convika

Claude Code からつなぐ手順、フォーム、独自ドメインは Claude Code で作ったページを公開する方法にまとめています。

よくある質問

スキルとカスタムスラッシュコマンドは何が違いますか？

Claude Code では、カスタムコマンドはスキルに統合されました。.claude/commands/deploy.md と .claude/skills/deploy/SKILL.md はどちらも /deploy になり、同じように動きます。今ある .claude/commands/ のファイルもそのまま動きますが、スキルなら補助のファイルを同じフォルダに置け、自分と Claude のどちらが呼べるかを決められ、Claude が必要なときに自分で読み込めます。同名なら、スキルのほうが動きます。

Claude Code のスキルと Codex のスキルは同じファイルで使えますか？

SKILL.md の形式は同じ Agent Skills の仕様なので、name と description と本文だけのスキルなら、同じ内容を両方の置き場所に置けます（両方で動かしてはいません）。ただし置き場所は Claude Code が .claude/skills/、Codex が .agents/skills で、どちらのドキュメントにも相手のフォルダを読むとは書かれていません。両方ともシンボリックリンクのフォルダをたどるので、スキルのフォルダ（<名前>/）を、もう片方の置き場所からシンボリックリンクで指す方法はとれます（試してはいません）。Claude Code 独自の項目（disable-model-invocation、context: fork など）と Codex の agents/openai.yaml は、それぞれのツールだけのものです。

スキルが自動で使われません。どうすればいいですか？

まず description に、依頼でふつうに使う言葉と、いちばん大事な使い道が先頭に入っているかを見ます。Claude Code では What skills are available? と聞いて一覧に出るか、/スキル名 で動くかを確かめ、動くのに自動で使われないなら、フロントマターの YAML が壊れていないかを claude plugin validate .claude/skills で調べます。Codex では /skills で一覧を見て、説明に「いつ使い、いつ使わないか」をはっきり書きます。スキルが多いと説明が短くされたり一覧から外れたりするので、使わないスキルを止めるのも手です。

allowed-tools でツールを制限できますか？

できません。Claude Code の allowed-tools は、スキルを呼んだターンのあいだ、そのツールを確認なしで使えるようにする事前承認で、ドキュメントは "It does not restrict which tools are available" と書いています。使わせたくないツールは disallowed-tools に書くか、権限の設定の deny を使います。仕様では allowed-tools は "Experimental" で、Codex のスキルのドキュメントにこの項目はありません。

スキルはどこに置けばチームで共有できますか？

Claude Code は .claude/skills/、Codex は .agents/skills をリポジトリにコミットすれば、そのリポジトリで作業する人に共有されます。リポジトリの外の人に配るなら、どちらもプラグインにまとめる方法があります。Claude Code では組織の管理設定で全員に配ることもでき、Codex のプラグインは IDE 拡張では使えません。

スキルを入れすぎるとトークンを使いますか？

使います。本文は呼ばれたときだけ読まれますが、名前と説明の一覧は毎ターン文脈に入ります。Claude Code では一覧は文脈の 1% まで、Codex では既定で 2% までで、あふれると説明が落ちたり短くなったりします。Claude Code は /skill-doctor で各スキルのコストと使われた回数を見られ、disable-model-invocation: true にすると説明が一覧から消えて予算が空きます。

他人が作ったスキルを入れても安全ですか？

信頼できる作者のものだけにしてください。Anthropic のドキュメントは "Use Skills only from trusted sources"（自分で作ったものか、Anthropic から入手したもの）と書き、悪意のあるスキルはツールの呼び出しやコードの実行で、データの持ち出しなどにつながりうると注意しています。入れる前に SKILL.md、スクリプト、画像などの全ファイルを読み、外への通信やスキルの目的に合わない処理がないかを見ます。Claude Code では、リポジトリのスキルの allowed-tools は信頼していないフォルダでの -p の実行でも効くので、そこも確かめます。

スキルをサブエージェントで動かすには？

Claude Code では、フロントマターに context: fork と、使うサブエージェントの種類を agent に書きます。Claude Code は新しいサブエージェントを起動し、スキルの本文をその指示として渡します。名前に反して今の会話を分けるのではなく、サブエージェントは "doesn't see your conversation history" なので、本文だけで指示が通じるように書きます。既定ではバックグラウンドで動き、結果を待ちたいときは background: false（v2.1.218 以降）を足します。Codex のスキルのドキュメントには、この項目はありません。スキルとサブエージェントそのものの違いは Claude Code と Codex のサブエージェントの違いにまとめています。

出典

• Claude Code Docs: skills (2026 年 10 月 21 日に確認)
• Claude Docs: Agent Skills overview (2026 年 10 月 21 日に確認)
• Claude Docs: Skill authoring best practices (2026 年 10 月 21 日に確認)
• Agent Skills: Specification (2026 年 10 月 21 日に確認)
• Codex Docs: Build skills (2026 年 10 月 21 日に確認)
• Codex Docs: Skills & Plugins (2026 年 10 月 21 日に確認)
• Codex Docs: Customization (2026 年 10 月 21 日に確認)
• Codex Docs: Skill controls (2026 年 10 月 21 日に確認)
• Codex Docs: Custom Prompts (2026 年 10 月 21 日に確認)