AI Hub

Codex

Codex Skillsの使い方｜SKILL.mdの書き方とAGENTS.mdとの違い

公開: / 更新: ・読了目安8分

#Skills #カスタマイズ

Codex Skillsの使い方｜SKILL.mdの書き方とAGENTS.mdとの違い

先に結論: Codex Skillsは、繰り返す作業手順をSKILL.mdにまとめて再利用する仕組みで、フロントマターにはnameとdescriptionが必須です。配置場所はプロジェクト用.agents/skills/、個人用~/.agents/skills/です。

Codex Skillsは、繰り返し行う作業手順をSKILL.mdにまとめ、Codexに再利用させる仕組みです。1つのフォルダが1つのスキルに対応し、指示文だけでなくスクリプトや参考資料も渡せるため、AGENTS.mdより踏み込んだ「手順のパッケージ化」に向いています。

この記事では、SKILL.mdの書き方と配置場所、呼び出され方、AGENTS.md・MCP・カスタムプロンプトとの役割分担を整理します。

この記事の要点

  • Codex Skillsは、繰り返し行う作業手順をSKILL.mdにまとめ、Codexに再利用させる仕組みです。
  • 1フォルダにつき1スキルとして扱われ、SKILL.md以外のscripts・references・assetsはすべて任意です。
  • SKILL.mdのフロントマターはnameとdescriptionの2項目が必須です。
  • 配置場所はプロジェクト用が.agents/skills/、個人用が~/.agents/skills/です。
  • 呼び出しは$skill-nameによる明示的指定と、descriptionをもとにした自動発火の2通りがあります。

前提・動作環境

この記事はCodexにSkills機能が搭載されている前提で解説します。起動方法や設定ファイルの扱いは「Codexの使い方完全ガイド」でまとめています。

Skills機能は2026年8月時点でも仕様更新が続いているため、手元の挙動と異なる場合は公式サイト(developers.openai.com/codex)で確認してください。

Codex Skillsとは何か

Skillsは、指示文(Markdown)とスクリプトや参考資料を1つのフォルダにまとめ、Codexが必要に応じて読み込んで実行する機能です。1フォルダにつき1スキルとして扱われ、フォルダ内には次のようなファイルを置けます。

my-skill/
├── SKILL.md          # 必須。フロントマターと手順本文
├── scripts/          # 任意。決まった処理を実行するスクリプト
├── references/       # 任意。参照用のドキュメントやチェックリスト
├── assets/           # 任意。テンプレートなど
└── agents/
    └── openai.yaml   # 任意。表示名やMCP連携などのメタデータ

SKILL.md以外はすべて任意です。単純な作業ならMarkdownの指示文だけで十分で、手順を確実に再現したい場合だけscriptsにコードを置きます。Claude CodeのSkillsは「Claude Code Skillsの作り方」で仕組みを解説しています。

SKILL.mdの書き方と配置場所

SKILL.mdは、YAML形式のフロントマターとMarkdown本文で構成します。フロントマターに書くのはnameとdescriptionの2つで、この2項目は省略できない必須のフロントマターです。

---
name: fix-merge-conflicts
description: GitHubのPRをチェックアウトしてbaseブランチに追従させ、コンフリクトを解消する。マージ関連の依頼が来たときに使う。
---

1. 対象PRをチェックアウトする
2. baseブランチを取り込み、コンフリクトを確認する
3. コンフリクトを解消し、diffを提示する
4. 実行すべきpushコマンドを提示する(pushは自動実行しない)

配置場所はスコープによって決まっています。

Codex Skillsの配置場所4種: プロジェクト用の.agents/skills/はチーム共有、ユーザー用の~/.agents/skills/は個人利用、管理者用の/etc/codex/skills/は組織管理、システム同梱の.system配下はCodex本体にバンドルされることを示す図

チーム共有はリポジトリの.agents/skills/、個人用は~/.agents/skills/が基本です。

スキルの呼び出され方

呼び出し方は2通りあります。ひとつは$skill-nameのように明示的に指定する方法、もうひとつはCodexがプロンプトの内容とdescriptionを照合して自動的に発火させる方法です。

スキルの呼び出され方2通りの対比図。明示的指定は$skill-nameで確実に発火させたい場合向き、自動発火はdescriptionとの照合で選ばれるためdescriptionの書き方が肝心であることを示す図

自動発火を狙う場合は、descriptionの記述が曖昧だと期待した場面で呼ばれない、あるいは無関係な場面で誤発火するため、「いつ使うべきか・使うべきでないか」を具体的に書く必要があります。

なお、起動時に読み込まれるスキル一覧はコンテキストウィンドウを圧迫しないよう上限が設けられており、モデルのコンテキストウィンドウの2%程度、不明な場合は8,000文字程度までに抑えられます。この段階で読まれるのは名前とdescriptionだけで、手順本文はスキルが選択された時点で読み込まれます。

自動発火だけを止めたい場合は、スキルフォルダにagents/openai.yamlを追加しpolicy.allow_implicit_invocation: falseと書けば明示的な呼び出しだけを受け付けます。

スキル自体を無効化したいときは~/.codex/config.tomlに次のように書いてCodexを再起動します。

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

キュレーション済みスキルを試すだけなら、$skill-installer経由でインストールする方法もあります。

AGENTS.md・MCP・カスタムプロンプトとの違い

Codexには指示や機能を拡張する仕組みが複数あり、役割が分かれています。

これらは競合せず補完し合う関係です。AGENTS.mdが挙動を形作り、Skillsが再現性のある処理を担当し、MCPが外部システムとの接続を担う、という役割分担で捉えると整理しやすくなります。

実用スキルの例

OpenAIのサンプル集には、実務でそのまま使えそうなスキルがいくつも並んでいます。

自作する際は、普段のチャットでうまくいった手順やレビュー基準、テストコマンドを材料に$skill-nameとして切り出すところから始めるとよいでしょう。

業界動向:Codexも対応する「Agent Plugins」共通規格

2026年8月6日、Vercelは複数ベンダーで使えるAIエージェント拡張の共通規格「Agent Plugins」を発表しました。

Vercel公式ブログの対応クライアント一覧にはChatGPT/Codexが含まれており、plugin.jsonというマニフェストでAgent SkillsやMCPサーバーをまとめてパッケージ化し、Cursor・GitHub Copilot・Kiro・VS Codeなど他クライアントとも共有できる仕組みになる見込みです。

技術運営委員会にはAWS・Cursor・Microsoft・OpenAI・Vercelが名を連ねています。

SKILL.md形式のCodex Skillsとの互換性(既存資産がそのまま使えるか、変換が必要か)は2026年8月時点で公式の詳細情報が確認できていないため、Codex公式サイト(developers.openai.com/codex)やVercelの発表を継続的に確認することをおすすめします。

なお、同発表の対応クライアント一覧にClaude Codeは含まれておらず、Claude Code Skillsは「Claude Code Skillsの作り方」で解説している独自形式のまま提供されています。

つまずきポイント

よくある質問

SKILL.mdだけでスクリプトなしのスキルを作ってもよいですか?

問題ありません。手順が言葉で説明できる内容であれば、Markdownの指示文だけで十分機能します。決定的な処理が必要な場合を除き、まずは指示文だけで組み立てるのがおすすめです。

既存のAGENTS.mdの内容をSkillsに移行すべきですか?

すべて移行する必要はありません。AGENTS.mdは常に守ってほしい前提知識、Skillsは特定の場面でだけ実行したい複数ステップの作業という住み分けです。「特定のタスクのときだけ詳しく実行してほしい」手順があれば、その部分だけをSkillsに切り出すとよいでしょう。

チームでSkillsを共有するにはどうすればよいですか?

リポジトリの.agents/skills/配下に置けば、チェックアウトした全員が同じスキルを使えます。より広く配布したい場合は、MCP連携もまとめられる「プラグイン」としてまとめる方法も用意されています。

まとめ

Codex Skillsは、SKILL.mdに指示文をまとめ、必要に応じてスクリプトや参考資料を添えて再利用できるようにする機能です。

配置場所はプロジェクト用の.agents/skills/と個人用の~/.agents/skills/が基本で、呼び出し方は明示的な$skill-nameと、description次第で自動発火する方式の2通りです。

常設のルールを書くAGENTS.md、外部ツールと接続するMCP、非推奨のカスタムプロンプトとは役割が異なり、互いに補完し合う関係です。

Codex全体の使い方は「Codexの使い方完全ガイド」、AGENTS.mdの書き方は「AGENTS.mdの書き方」もあわせてご覧ください。