Codex Skillsの使い方とは？SKILL.mdの書き方からおすすめスキル・Claude Code Skillsとの違いまで解説

最終更新日:2026/08/03

「AIに毎回同じ前提条件を説明するのが面倒…」「メンバーによってコードレビューやテスト自動生成の品質にバラつきがある」開発現場でAIエージェントを活用する際、このような属人化や手間の壁にぶつかっていませんか？

その悩みを解決するのが、Codexの『Codex Skills（コーデックス スキルズ）』です。

本記事では、Codex Skillsの基本概念から「SKILL.md」の具体的な書き方、Claude Code Skillsとの違いまで徹底解説。プロンプトの手間を大幅に減らし、出力のブレをなくす「チームの資産」としてのAI活用法をお伝えします。

Codex Skillsとは

Codex Skillsの基本概念

Codex Skillsとは、特定の作業の手順・ルール・参考情報をひとまとめにして、AIエージェントに渡すための仕組みです。1つの「スキル」は、指示書・スクリプト・参考資料をまとめたフォルダとして管理します。スクリプトは、必要に応じて自動実行する小さなプログラムを指します。

中心になるのは「SKILL.md」というファイルです。ここに「何をするスキルなのか」「どんなときに使うのか」と、実際の作業手順を記載します。Codexは依頼内容をもとに、必要だと判断したスキルだけを読み込んで実行します。一度作っておけば、同じ作業のたびに再利用できます。

プロンプトやAGENTS.mdとの違い

その場限りの依頼を伝えるのがプロンプト（AIへの指示文）で、プロジェクト全体に共通する前提やルールをまとめておくのがAGENTS.md（プロジェクト単位でCodexに読ませる設定ファイル）です。

スキルは、このどちらとも役割が異なります。スキルが受け持つのは「特定の作業をどう進めるか」という手順や判断の部分で、それを切り出して再利用できる形にしたものです。常に意識させたい全体ルールはAGENTS.mdに、特定の作業の進め方はスキルに、と書き分けます。

利用できる環境

Codex Skillsは、CLI・IDE拡張・Codexアプリのいずれでも利用できます。CLIはコマンドラインで操作する環境、IDE拡張はコードエディタに組み込んでCodexを使うための拡張機能です。どの環境で作ったスキルも、基本的な考え方は共通です。

導入で得られるメリット

スキルを用意しておくと毎回同じ前提を書き直す必要がなくなり、依頼プロンプトを短く保てます。Codexが手順に沿って動くので出力のばらつきが減り、作業品質が安定します。

さらに、属人化していた手順や判断基準もスキルとして書き出せば、チーム全体で共有できます。個人レベルの作業効率化だけでなく、組織の標準化にもつながる点がスキルを使う大きなメリットです。

たとえば、コードレビュー・テストコード作成・README更新の手順をスキル化すると、導入前後で次のような変化が期待できます。

対象作業	導入前	導入後
コードレビュー	レビューのたびに確認項目をプロンプトへ書き、担当者によって指摘の観点が変わる	セキュリティ・例外処理・可読性・テスト不足など、共通の観点で確認しやすくなる
テストコード作成	正常系だけで終わるなど、担当者によってテストケースの範囲に差が出る	正常系・異常系・境界値を確認する手順を共通化し、ケースの抜けを抑えやすくなる
README更新	セットアップ方法や環境変数など、記載する項目が担当者によって異なる	必要環境・インストール・起動方法・テスト方法などを同じ構成で記載しやすくなる

定型作業であれば、依頼時は「この変更をレビューして」「この機能のテストを追加して」といった短い指示から始められます。ただし、短縮できる時間や差し戻しの削減率は、対象作業・既存ルール・スキルの内容によって異なります。

Codex Skillsの仕組み

SKILL.mdを中心としたディレクトリ構成

スキルは、SKILL.mdファイルを必ず含むフォルダとして作成します。SKILL.mdにはname・description・作業手順を書き、必要に応じてスクリプトや参考資料、出力に使うテンプレートなどを同じフォルダにまとめます。基本的な構成は次のとおりです。

my-skill/

SKILL.md          # 必須：指示とメタデータ

scripts/          # 任意：実行スクリプト

references/       # 任意：参考資料

assets/           # 任意：テンプレートなど

agents/

openai.yaml     # 任意：表示名や依存関係の設定

OpenAIのCodex Skills公式ドキュメントでは、スキルはSKILL.mdと任意のscripts・references・assetsなどを含むディレクトリとして説明されています。

段階的に読み込む仕組み

Codexはスキルが増えても動作が重くならないように、情報を段階的に読み込みます。はじめは各スキルの名前・説明・ファイルの場所だけを把握しておき、実際にそのスキルを使うと判断したときに、SKILL.mdの全文を読み込みます。必要に応じてreferencesやscriptsも参照します。

この最初に持っておく一覧には上限があり、現時点の仕様では、モデルが扱える情報量の最大で2%、不明な場合は8,000文字までに収められます。スキルをたくさん入れていても必要になるまでは本文全体を読み込まないため、コンテキストを節約しながら使用できるのです。

スキルの呼び出し方

作成したスキルの呼び出し方には2通りあります。1つは、依頼文の中でスキルの名前を直接指定する方法で、もう1つは、依頼の内容がスキルの説明と合致したときにCodexが自動で選ぶ方法です。

自動で選ばれるかどうかは、SKILL.mdに書いた説明文の内容に左右されます。そのためどんなときに使いたいスキルなのかを、説明文の前半に具体的な言葉で書いておくことが大切です。

SKILL.mdの書き方

YAMLフロントマターの基本

SKILL.mdは、「先頭の設定部分（YAML）」と「本文」の2パートで構成されます。 設定部分には、スキルの名前（name）と説明（description）を必ず記載します。

nameの記述ルール

• 親フォルダ名と完全に一致させる

• 小文字の英数字とハイフン（-）のみを使用する

【記述例】

name: skill-name

description: このスキルをいつ使い、いつ使わないかを具体的に書く

descriptionの書き方とトリガー設計

descriptionは、SKILL.mdの中で最も重要な項目です。Codexはこの説明文を手がかりに、依頼の内容と合うスキルを選びます。説明が曖昧だと、使ってほしい場面で呼び出されません。

説明には、そのスキルが「何をするのか」を一文で示し、続けて「どんなときに使うのか」を具体的に書きます。トリガーになる言葉を前半に置くと、自動で選ばれやすくなります。

本文の設計ポイント

本文には、Codexに実行してほしい手順を書きます。書き方は命令形で統一し、判断が必要な場面では「この場合はこうする」と基準を明記します。

本文が長くなりすぎると読み込む情報量が増えるため、詳しい資料はreferencesなどの別ファイルに分けて必要なときだけ参照できる形にします。手順やコマンドは文章で説明するよりも、そのまま実行できる形で示すほうが確実です。

【記述例】

名前と説明、本文をそろえた一例を示します。手動で作成する場合は、この形のSKILL.mdをスキル用のフォルダに置けば認識されます。

---
name: pr-summary
description: 変更内容からPRの説明文を作成する。コミットやPR作成を頼まれたときに使う
---

# PR説明文の作成

## 目的

ステージした変更から、定型のPR説明文を生成する。

## 手順
1. 変更差分を確認する
2. 種別（feat / fix など）を判定する
3. 定型フォーマットで説明文を出力する

現場で使いやすいSKILL.mdのユースケース例

SKILL.mdは、毎回ほぼ同じ確認項目や出力形式を使う作業に向いています。ここでは、コードレビュー・テストコード自動生成・README作成の例を紹介します。以下は書き方の見本であり、使用する言語・フレームワーク・社内ルールに合わせて項目を調整してください。

コードレビューを共通の観点で行う例

コードレビュー用のスキルでは、確認する項目と指摘の出し方を決めておきます。担当者によって見落としやすい観点が変わる場合でも、同じ基準で確認しやすくなります。

---
name: code-review
description: 変更差分をコードレビューし、バグ・セキュリティ・可読性・テスト不足を確認する。PRレビューや変更内容の確認を頼まれたときに使う
---

# コードレビュー

## 手順
1. 変更差分と関連ファイルを確認する
2. 仕様との不一致、例外処理、境界値、セキュリティ上の問題を確認する
3. 命名、重複、可読性を確認する
4. テストの追加や修正が必要か判断する
5. 指摘を「要修正」「提案」「確認」に分ける

## 出力形式
- 対象ファイルと行
- 問題点
- 理由
- 修正案

たとえば「このPRをcode-reviewで確認して」と依頼すると、SKILL.mdに記載した観点と形式に沿ったレビューを実行できます。

テストコードを自動生成する例

テストコード作成では、既存テストの記法に合わせることや、正常系だけでなく異常系・境界値も確認することを明記します。

---
name: generate-tests
description: 既存コードとテスト方針を確認し、必要なテストコードを作成する。テスト追加や不具合の再発防止を頼まれたときに使う
---

# テストコードの作成

## 手順
1. 対象コードと既存テストを確認する
2. 使用中のテストフレームワークと記法に合わせる
3. 正常系・異常系・境界値のケースを洗い出す
4. 既存機能を壊さない範囲でテストを追加する
5. テストを実行し、失敗した場合は原因を確認する

## 注意点
- 外部APIは必要に応じてモックする
- 実行順序に依存するテストを作らない
- 不具合修正では再発を検知できるケースを追加する

この例では、対象コードを確認してから既存のテスト方針に合わせるため、プロジェクトと異なる書き方のテストが追加されるのを防げます。

READMEを作成・更新する例

README作成では、記載する項目を決め、コードや設定ファイルから確認できない内容を推測しないように指示します。

---
name: update-readme
description: リポジトリの内容を確認し、READMEを新規作成または更新する。セットアップ手順や使い方の文書化を頼まれたときに使う
---

# READMEの作成・更新

## 手順
1. ソースコード、設定ファイル、既存ドキュメントを確認する
2. プロジェクト概要と主な機能を記載する
3. 必要環境、インストール、環境変数、起動方法を記載する
4. テストとビルドの実行方法を記載する
5. 不明な内容は推測せず、確認事項として示す

## 出力項目
- 概要
- 必要環境
- セットアップ
- 使い方
- テスト・ビルド
- 注意事項

READMEの項目と確認手順をスキル化しておくと、担当者が変わっても必要な情報を同じ構成にまとめられます。

Codex Skillsの作り方

用意されたスキルから作成する

Codexには、スキル作成を支援する機能がはじめから用意されています。入力欄に半角で「/skills」と入力すると、利用できるスキルの一覧が表示されます。一覧から「Skill Creator」を選ぶと、対話形式でスキルを作成できます。

Skill Creatorで対話的に作る

先ほどの一覧にある「Skill Creator」が、対話形式でスキルを作るためのスキルです。CLIやIDEでは、入力欄に次のコマンドを入力しても呼び出せます。

$skill-creator

このスキルは何をするスキルか、どんなときに使うか、スクリプトを含めるかどうかを順に尋ねながら、対話形式でスキルを組み立てられます。OpenAI公式ドキュメントでも、スキルを説明しながら作る方法として$skill-creatorが紹介されています。

Record & Replayで実演から作る

手順を説明するより実際にやって見せるほうが早い場合は、Record & Replay（操作を記録して再現する機能）が使えます。Codexが一連の操作を記録し、その内容をもとに、再利用できるスキルの下書きを作ります。

手動でフォルダを作成する

仕組みに慣れてきたら、フォルダとSKILL.mdを自分で用意する方法でも作成できます。スキル用のフォルダを作り、先ほどの記述例のようなSKILL.mdを置けば、Codexが自動で変更を検知します。反映されないときは、Codexを再起動します。

スキルの配置と運用

スキルの保存場所

Codexはスキルが保存されている場所（ディレクトリ）によって、そのスキルを使える範囲が変わります。用途に合わせて以下の適切な場所に配置してください。

$CWD/.agents/skills         # 作業中のフォルダ

$CWD/../.agents/skills      # 作業中フォルダより上の階層

$REPO_ROOT/.agents/skills   # リポジトリの最上位

$HOME/.agents/skills        # ユーザー個人

/etc/codex/skills           # 管理者・全員共通

SYSTEM                      # Codexにバンドルされたスキル

Codexは、リポジトリ内では作業中のフォルダからリポジトリルートまでの.agents/skillsを読み込みます。プロジェクト単位の場所に置けば、そのプロジェクトを触る人が使え、ユーザー個人の場所に置けば、自分がどのプロジェクトを開いても使えます。組織全体に共有したいスキルは、管理者向けの場所に置きます。

スキルの有効化・無効化

使わなくなったスキルは、ファイルを削除しなくても無効にできます。Codex CLIでは、設定ファイル（~/.codex/config.toml）に次のように書き、対象のSKILL.mdを指定します。

[[skills.config]]

path = "/path/to/skill/SKILL.md"

enabled = false

設定を変えたあとはCodexを再起動します。スキルを残したまま一時的に止めたいときに便利です。

チームでの共有と運用のコツ（定期的な棚卸し）

作成したスキルを個人のものに留めず、チームの資産として長期的に活用・管理するためのポイントです。

目的に合わせたスキルの共有

• プロジェクト単位： リポジトリ内の共有領域（.agents/skills）に置くことで、メンバー全員が同じ手順・品質で作業できるようになります。
• 組織・部門全体： 管理者向けの共通ディレクトリに配置し、全社的な業務の標準化を図ります。

定期的な「棚卸し」の実施

運用を続けると、使われなくなったスキルや古い手順が蓄積し、かえってノイズになります。定期的にスキルの利用状況を見直し、不要なものは整理（削除や無効化）しましょう。

第三者に伝わる「名前」と「説明」の徹底

時間が経過した後や、新しいメンバーが参画した際でも管理しやすいよう、誰が見ても「何をするスキルか」が瞬時にわかる name と description を設定しておくことが運用の鍵です。

運用時の注意点と失敗回避

Codex Skillsを導入する際につまずきやすいのは以下2つのパターンです。回避方法と併せて把握しておきましょう。

• スキルが呼び出されない場合
  原因の多くは説明文（description）の曖昧さにあります。Codexが「どの場面で使うスキルか」を判定できるよう、「どんな依頼が来たら実行するか」を具体的に書き直してください。
• 作業品質が安定しない場合
  いつものプロンプトを別ファイルに移しただけでは、効果は出ません。スキル作成は「業務手順の設計」です。まずは毎回同じ基準で繰り返す定型作業を一つ選び、その判断基準を明確に切り出しましょう。

おすすめスキルとカタログ

公式カタログとskill-installer

ゼロから作らなくても、すでに公開されているスキルを取り込んで使えます。Codexに付属する取り込み用の機能を使い、スキルの名前を指定すると、用意されたスキルを追加できます。

$skill-installer linear

このようにスキルの名前を指定すると、用意されたスキルを追加できます。取り込み先として、ほかのリポジトリ（公開されたコードの保管場所）を指定することもできます。新しく入れたスキルは自動で認識されますが、表示されないときはCodexを再起動します。

代表的な実用スキル

公式が提供するスキルには、業務で使いやすいものが揃っています。たとえば、Linear（課題管理ツール）と連携して課題を扱うスキルがあります。OpenAIのドキュメントでは、$skill-installer linearを例に、curated skillsを追加する方法が紹介されています。自分の業務に近いものから少しずつ試すと、効果を実感しやすくなるでしょう。

コミュニティのスキル集

公式以外にも、開発者が公開しているスキル集があります。実際の現場で使われているスキルを集めたものもあり、自分の目的に合うスキルを探す手がかりになります。ただし、第三者が作ったスキルは中身がそのままCodexの動きに影響するため、提供元が信頼できるかを確かめ、SKILL.md・付属スクリプト・外部連携の内容を確認してから使うことが大切です。

スキルとプラグイン・マーケットプレイスの関係

スキルは再利用する作業手順を設計する形式で、それを人に配れるようにまとめた単位がプラグインです。プラグインには複数のスキルに加えて、外部ツールとの連携やMCP（Model Context Protocol／外部のツールやデータと接続する共通規格）の設定なども含められます。

配布や入手は、マーケットプレイス（プラグインの公開・配布の場）を通じて行います。Codexアプリの「プラグイン」から、公式が選んだものや、社内で共有されたものを探して導入できます。なお、かつて公式が公開していたスキルのカタログ用リポジトリは現在は非推奨となり、プラグイン用のリポジトリへ移行しています。

Claude Code Skillsとの違い

スキルの仕組みは、OpenAIのCodexに限ったものではありません。AnthropicのClaude Code（クロードコード）にも同じ発想のスキル機能があり、両者は共通の標準をもとにしています。ここでは主な共通点と違いを解説します。

共通点

SKILL.mdというファイルを中心に、作業手順をまとめる点はどちらも同じです。説明文をもとに必要なスキルだけを読み込む段階的な仕組みも共通しています。スキルの基本的な書き方は、両者でほとんど変わりません。

ただし、フロントマターの扱いには違いがあります。CodexではSKILL.mdにnameとdescriptionが必須です。一方、Claude Codeの公式ドキュメントでは、フロントマターの各項目は任意で、Claudeがスキルを使う場面を判断しやすくするためにdescriptionが推奨されています。

フォーマットと機能の違い

違いの1つが、ツール権限に関する設定です。Claude Code側には、スキル実行中に一部ツールを事前承認できるallowed-toolsがあります。ただし、allowed-toolsは「使えるツールを限定する項目」ではありません。Claude Codeの公式ドキュメントでは、allowed-toolsは指定したツールを承認なしで使えるようにする項目であり、指定していないツールも通常の権限設定に従って利用できると説明されています。

ツールを使えないようにしたい場合は、Claude Codeではdisallowed-toolsや権限設定を使います。Codex側にもAgent Skills仕様上のallowed-toolsという項目はありますが、Codex公式ドキュメントでは、Claude Codeのallowed-toolsに相当するSKILL.md上の権限制御項目としては説明されていません。

呼び出しを制御する仕組みも、置き場所が異なります。Codexでは、agents/openai.yamlにallow_implicit_invocation: falseを指定すると、プロンプト内容に基づく暗黙呼び出しを抑制できます。一方、Claude Codeでは、SKILL.mdのフロントマターにdisable-model-invocation: trueを指定すると、Claudeがそのスキルを自動で読み込まないようにできます。

ツールをまたいで再利用する設計

両者が共通の標準にもとづいているため、片方向けに書いたスキルを、もう一方でも使い回せる場合があります。両方で動かしたいときは、それぞれに固有の項目を避け、共通部分だけで書いておくと、移植の手間を抑えられます。

ただし、保存する場所・呼び出し方法・独自のフロントマター項目はツールごとに異なります。共通部分は流用しつつ、各ツールの公式ドキュメントに合わせて最終調整することが大切です。

業務での活用アイデアと失敗回避

スキルは、開発の現場だけでなく非エンジニアのチームや部門の業務にも応用できます。ここでは、開発以外の部署で使う場合の考え方と、つまずきを避けるための要点を紹介します。

部門・職種別の活用例

開発の現場では、テストの実行手順・レビューの観点・コミットの書式といった、繰り返し発生する作業をスキルにできます。

コードレビュー・テストコード作成・README更新のように、確認項目や出力形式が決まっている作業は特にスキル化しやすく、担当者が変わっても同じ品質を保ちやすくなります。

開発以外でも、定型の文書づくりや、決まった手順のチェック作業など、毎回やり方が同じものはスキルに向いています。自社共通の進め方をスキルに書き出しておけば、部門をまたいで同じ基準で作業を進められます。

非エンジニアへ広げる際のポイント

スキルを技術者だけのものにせず、非エンジニアにも広げたい場合は、まず「何のためのスキルか」を全員が理解できる言葉で書くことが出発点です。専門用語を避け、使う場面と得られる結果を明記すると、技術に詳しくない人でも扱いやすくなります。

チームの進め方や判断基準をスキルとして共有できれば、AIの活用は一部の人にとどまらず、組織全体の取り組みへと広がります。

非エンジニアによくあるつまずきと対処

非エンジニアがつまずきやすいのが、「いい感じにまとめて」のように指示が曖昧なままスキルを登録してしまうケースです。スキルは、手順や判断の基準を具体的に書くほど安定しやすくなります。そのため、ふだん人に頼むときよりも一段詳しく書くことが大切です。

もう1つは、一度きりの作業までスキルにしようとすることです。スキルが効果を発揮するのは、日常的に同じ手順を繰り返す作業です。単発の依頼は通常チャットでも十分なので、繰り返す作業を見極めてからスキル化する方が業務効率化につながります。

AGENTS.md・MCP・サブエージェントとの使い分け

Codexには、スキル以外にも作業を助ける仕組みがあります。常に守る全体ルールはAGENTS.md、外部ツール・データとの接続はMCP、独立した作業を切り出して任せたいときはサブエージェント（個別の作業を担当する補助的なエージェント）というように、役割が分かれています。

この中でスキルが向いているのは、特定の作業の進め方を再利用したい場面です。それぞれの仕組みの得意分野を理解し、目的に合わせて使い分けると、CodexをはじめとするAIツールを扱いやすくなります。

まとめ

Codex Skillsは、繰り返しの作業手順をまとめて再利用できるようにする仕組みで、中心になるのはnameとdescriptionを書いたSKILL.mdです。作成にはCodexアプリ・対話形式・手作業など複数の方法があり、置く場所によって使える範囲が変わります。

公開されたスキルを取り込めば、ゼロから作らずに始められます。Claude Code Skillsとも共通の標準をもとにしているため、考え方を一度押さえれば、ツールをまたいで応用できます。

まずは、自分やチームが毎回同じように進めている作業を1つ選び、スキルとして切り出すところから始めてみてください。小さく始めて育てていく進め方が、定着への近道です。

アイスマイリーでは、AIエージェントのサービス比較と企業一覧を無料配布しています。課題や目的に応じたサービスを比較検討できますので、ぜひこの機会にお問い合わせください。

よくある質問

Codexのスキルとは何ですか？

特定の作業の手順・ルール・参考情報をまとめて、Codexに渡しておく仕組みです。中心となるSKILL.mdに「何をするか」「いつ使うか」と手順を書いておくと、Codexが必要なときに読み込んで、その手順どおりに作業します。

ChatGPTとCodexの違いは何ですか？

ChatGPTは文章での対話を中心とした幅広い用途のAIで、Codexはコードを書く作業に特化したAIエージェントです。Codexは依頼に応じて実際にコードを書いたり直したりするため、開発の現場で作業を任せる相手として使われます。

Codexでおすすめのスキルは何ですか？

Codexでは、Linear連携などのスキルが紹介されています。まずは自分の業務に近いスキルを1つ選び、取り込んで試すところから始めると、効果を確かめやすくなります。

SKILL.mdはどう書けばよいですか？

ファイルの先頭にYAML形式で名前（name）と説明（description）を書き、その下に作業手順を命令形で記します。とくに説明は、Codexがスキルを選ぶ手がかりになるため、どんなときに使うかを具体的に書くことが重要です。