OpenAI CodexのAgent Skillsとは？SKILL.mdの書き方と使い方を解説

OpenAIの開発者向けツール「Codex」でも、Anthropic発のオープン標準である「Agent Skills」に対応したスキル機能が利用できます。
SKILL.mdを中心としたフォルダ構成でワークフローを定義しておくことで、Codexに特定タスクの手順・リソース・スクリプトをまとめて渡し、安定した実行を任せられるようになります。
本記事では、CodexのAgent Skillsについて、基本概念・SKILL.mdの書き方・CLI/IDEでの使い方、Claude SkillsやGitHub Copilotとの違いまでを整理して解説します。

CodexにおけるAgent Skillsとは？

Agent Skillsは、Anthropicが提唱した**オープンなスキル仕様「Agent Skills standard」**に基づく、「エージェントに業務フローを教えるためのスキルフォルダ」です。

OpenAIのCodexでは、このAgent Skillsを使うことで、Codex CLI や Codex IDE拡張に「特定タスクのやり方」を教え込むことができます。

対象リポジトリやユーザーディレクトリにスキルフォルダを用意しておけば、Codexはその内容を読み取り、コード編集・テスト・スクリプト実行などと組み合わせて、同じワークフローを何度も再現できるようになります。

Codex版Agent SkillsのSKILL.mdとフォルダ構成

スキルは、基本的に「1つのフォルダ = 1スキル」です。

典型的なフォルダ構成の例は次のとおりです。

my-skill/
├── SKILL.md        (required: スキルのメタ情報と手順書)
├── scripts/        (optional: 実際に呼び出すスクリプト群)
├── references/     (optional: 設計書・ガイドライン・仕様書など)
└── assets/         (optional: テンプレートやサンプルファイル)

SKILL.md には、次のような情報をまとめておきます。

• フロントマター（name / description / metadata など）
• スキルの目的・前提
• 入力（Inputs）・出力（Outputs）
• ステップ（Steps）
• スタイルガイド・注意点
• 具体的なプロンプト例

<Br>Codex 側は、この「SKILL.md」を読み込んで「何をどうするスキルか」を理解し、必要に応じて scripts や references の中身にアクセスしながらタスクを進めます。

人間から見ても、「このスキルは何をしてくれるのか」が一目で分かるようにしておくことが重要です。

SKILL.mdのフォーマット例

SKILL.md は、YAML フロントマター＋任意の本文という構成になっています。YAML部分では、少なくとも次の2つのフィールドが必須です。

• 「name」：スキル名（必須・1行・100文字以内）
• 「description」：Codex がいつ／どんなときにこのスキルを使うべきかを説明する文（必須・1行・500文字以内）

これに加えて、ユーザー向けの短い説明を「metadata.short-description」として付けることもできます。
本文には、Codex が従うべき手順や入力例などを Markdown で自由に書けます。

例えば、「Conventional Commits形式のコミットメッセージを下書きする」スキルの 「SKILL.md」は次のように書けます。

---
name: draft-commit-message
description: Draft a Conventional Commits-style message when the user asks for help writing a commit message.
metadata:
  short-description: Draft an informative commit message.
---

Draft a conventional commit message that matches the change summary provided by the user.

Requirements:
- Use the Conventional Commits format: `type(scope): summary`
- Use the imperative mood in the summary (for example, "Add", "Fix", "Refactor")
- Keep the summary under 72 characters
- If there are breaking changes, include a `BREAKING CHANGE:` footer

Codex は起動時に 「name」と「description」のみをコンテキストに読み込み、スキルが実際に使われるときにだけ本文と関連ファイルを参照します。

「name」と「description」が複数行になっていたり、文字数制限を超えていたりすると、スキル全体が無視される点には注意が必要です。

Skillsの読み込み場所とスコープ

Codexでは、スキルの配置場所によって「どの範囲から利用できるか」が決まり、REPO / USER / ADMIN / SYSTEM といったスコープごとに整理されています。

ざっくり整理すると、次のようなイメージです。

Codexは起動時にこれらの場所をスキャンし、利用可能なスキルの一覧を構築します。

スキル名が重複している場合は、スコープごとの優先順位にしたがって上書きされるため、「リポジトリ固有のスキルで、共通スキルを上書きする」といった構成も可能です。

CodexでAgent Skillsを作成・管理する基本ステップ

ここからは、実際に Codex 上で Agent Skills を定義・管理する流れを、ざっくり3ステップに分けて整理します。

ステップ1：skill-creatorでたたき台を作る

Codex には、スキル作成を支援するビルトインスキル($skill-creator)が用意されています。

スキル化したいタスクの概要をCodexに説明すると、次のようなアウトプットが得られます。

• SKILL.md の骨組み
• 必要になりそうなサブフォルダ構成
• 例示的な手順書やプロンプト例

最初から手書きするよりも、「skill-creator に要件を語る → 生成された SKILL.md を読んで手直しする」という流れで進めた方が、標準仕様に沿ったスキルを作りやすくなります。

ステップ2：SKILL.mdとフォルダを手動で整える

たたき台ができたら、実際の運用に合わせて内容を詰めていきます。

具体的には、次のような作業を行います。

• SKILL.md で、目的・入力・出力・ステップ・スタイルガイドを自社のやり方に合わせて書き換える
• scripts フォルダに、テスト実行やログ集約、レポート生成などのスクリプトを配置する
• references や assets に、設計書・チェックリスト・テンプレートファイルを置く

このときのコツは、「人間のオンボーディング資料として読んでも分かりやすいか」を基準に書くことです。

スキルはエージェントだけでなく、人間の開発者も読む前提で設計しておくと、メンテナンスしやすくなります。

ステップ3：skill-installerで公開スキルを取り込む

Codexには、外部リポジトリからスキルをダウンロードするための仕組みも用意されています。

代表的な流れは、次のようになります。

• skill-installer を利用して、GitHub 上の公開スキルを取得する
• 取得したスキルを、自分たちのリポジトリやユーザーディレクトリのスコープに配置する
• 必要であれば SKILL.md や scripts を自チーム向けにフォーク・カスタマイズする

コミュニティ製スキルをそのまま使うのではなく、「中身を理解したうえで、自社のルールに合わせて少し手を入れてから使う」くらいのスタンスでいると、安全性と再利用性のバランスを取りやすくなります。

Codex×Agent Skillsでできること

Codex の Agent Skills は、「開発者の仕事の塊」をそのままワークフローとして切り出しておくと、威力を発揮します。

ここでは、実務でイメージしやすいユースケースをいくつか紹介します。

1. プロジェクト雛形の自動生成・初期セットアップ

新規サービスやマイクロサービスを作る際に、毎回同じような作業をしている場合は、プロジェクトスキャフォールド用スキルとしてまとめておくと便利です。

• 言語・フレームワークごとのディレクトリ構成
• ベースとなる CI 設定ファイル
• Lint / Format / Test の標準スクリプト
• README や CONTRIBUTING などの雛形

といった要素を SKILL.md ＋テンプレートにまとめておくことで、「このリポジトリに、いつもの構成で新しいマイクロサービスを追加してといった指示で、Codex に初期セットアップを任せやすくなります。

2. CI失敗時のログ解析・再実行スキル

CI が失敗したときの「いつもやっている調査手順」をスキル化しておくパターンです。

• 対象ブランチ・PR に紐づく最新の CI 実行ログを取得
• 失敗ジョブのログを要約し、エラー原因の候補を抽出
• 必要に応じてテストコマンドをローカルで再実行
• 再発防止の観点を README や Runbook に追記

といった流れを、「SKILL.md」と「scripts」に落とし込み、Codex に半自動で回してもらうイメージです。

GitHub Actionsやその他 CI ツールとの連携は別途必要ですが、「ログのとり方・見る順番・よくあるパターン」をスキル化しておくことで、対応品質の標準化に役立ちます。

3. インシデント対応・運用ルンブックの自動化

SRE や運用チームにとっては、「障害発生時の最初の 10〜15 分でやること」をスキルとしてまとめておくと、有事の初動が安定します。

• アラートの内容に応じて、対象サービスやダッシュボードを特定
• 代表的なメトリクス／ログの確認手順
• 既知のワークアラウンドの有無
• エスカレーション先・報告フォーマット

といった内容を Agent Skills で定義しておけば、Codex に「このアラートに対して標準手順を実行して」と依頼するだけで、最低限の調査・情報整理を任せられます。

4. 仕様・設計レビューの観点標準化

設計レビューや仕様レビューの観点も、スキル化しやすい領域です。

• API 設計レビューの観点（命名・バージョニング・認可・エラーハンドリングなど）
• データモデルレビューの観点（正規化、インデックス方針、履歴管理など）
• パフォーマンス・セキュリティのチェック項目

などを SKILL.md に落とし込み、対象の設計書やコードを渡してCodexに一次レビューをお願いする、という使い方が考えられます。

最終判断は人間のレビュアーが行う前提にしつつ、「観点漏れの防止」と「初期レビューの時間短縮」を目的に使うとバランスが良いです。

Claude Skills・GitHub CopilotのAgent Skillsとの関係と使い分け

最後に、Codex の Skills が Claude Skills や GitHub Copilot のエージェントスキルとどう関係しているのかも、ざっくり整理しておきます。

open Agent Skills standardとしての共通構造

CodexのSkills は、Anthropicが提唱した「open Agent Skills standard」をベースにしており、SKILL.md＋フォルダ構成という共通フォーマットを採用しています。

そのため、次のような考え方ができます。

• Claude Skills（Claude 側の Agent Skills 実装）
• GitHub Copilot のエージェントスキル
• OpenAI Codex の Skills

これらは、いずれも「Agent Skills 仕様に沿ったスキル」を解釈できるエコシステムを構成しているイメージです（詳細な対応状況や挙動は、それぞれの公式ドキュメントを確認する必要があります）。

もっとも、同じスキルフォルダを各ツールにそのまま持ち込んだ場合でも、利用できる外部ツール、認証の前提、実行環境（インストールされているライブラリやコマンドなど）はそれぞれ異なります。
「構造は共通でも動作は必ずツールごとに検証する」、という前提で設計しておくと安全です。

そのまま動くケースもありますが、パスやコマンド名、利用可能なAPIなどの環境依存部分は、ツールごとに調整が必要になることが多い点も意識しておくとよいでしょう。

ツールごとの得意領域と併用イメージ

ざっくりとした使い分けのイメージは次のとおりです。

Claude Skills

• ドキュメント生成・業務フロー・社内手順書など、業務全般のワークフロー標準化に強い
• Excel / PowerPoint / Word / PDF などオフィス系アーティファクトの生成にも向く

GitHub Copilot のエージェントスキル

GitHub 上のリポジトリ／Actions／Issue などと密に連携した、コード中心のワークフロー自動化に強い

Codex の Agent Skills

• CLI と IDE の両方から、ローカル環境や任意リポジトリにアクセスしやすい開発者ローカル寄りのエージェント
• コマンドラインでの実験・スクリプト実行・マルチリポジトリ横断など、開発環境の柔軟な操作に向く

Agent Skills は仕様レベルで共通化されているため、

• 「スキルのアイデアと骨組み」自体は、どのツールでもほぼ共通
• 実際の配置場所・利用チャンネル（ブラウザ／CLI／IDE）や、使えるツール群がツールごとに異なる

<brという整理で捉えておくと、導入戦略を立てやすくなります。

CodexでAgent Skillsを導入するときのベストプラクティス

最後に、Codex 側で Agent Skills を導入する際のポイントを、設計・運用の両面から簡潔にまとめます。

どんなときにスキル化するか

Skills は、「一度きりの試行的なプロンプト」や軽い相談内容を保存しておくための仕組みではありません。どちらかというと、

• チームで共有したいワークフロー
• 組織として統一したいチェック項目・ベストプラクティス
• 何度も発生する分析・運用タスク

といったものを、一度定義しておいて 何度も再利用するための入れ物 として使うのが前提です。

逆に、単発の検証や思いつきレベルのタスクは通常のプロンプトで済ませ、「毎回ほぼ同じ手順になる仕事」だけをスキルとして切り出した方が、スキルカタログが肥大化しにくくなります。

設計のベストプラクティス

設計面では、次のようなポイントを押さえておくとスキルが長生きしやすくなります。

• 「人間が読む手順書」として書く
  SKILL.md は、Codex だけでなく人間の開発者も読む前提で、目的・入力・出力・ステップを丁寧に書きます。
  
  
• ワークフロー単位でスキルを分割する
  「やれること全部」ではなく、「このスキルはこのタスク専用」という粒度で分けた方が、再利用性が高くなります。
  
  
• 入力・出力フォーマットを明確にする
  CSV / JSON / ログファイルなど、期待する形式を SKILL.md で明示しておきます。
  
  
• スクリプトは小さく・再利用可能に
  scripts 配下のスクリプトは、「単体でも意味が分かる単位」で分け、必要に応じて他スキルからも呼び出せるよう意識します。

これらを最初から意識しておくと、「一度作ったものの誰も読めない・使えないスキル」になりにくく、Agent Skills をチーム資産として育てやすくなります。

運用のベストプラクティス

運用面では、次のような点を意識しておくとトラブルが起きにくくなります。

スキルのスコープ設計を決める

• プロジェクト固有のスキルは REPO スコープ
• 個人の好みは USER スコープ
• 組織共通ルールは ADMIN スコープ

といった方針を最初に決めておくと整理しやすくなります。

レビューと承認のフローを用意する

本番で使うスキルは、PR ベースでレビューし、責任者が承認してから有効化するルールにしておくと安心です。

ログと検証用プロンプトを用意する

トラブルシュートしやすいように、スクリプトのログ出力やテスト用プロンプトの例を SKILL.md に残しておきます。

小さく始めて徐々にスケールさせる

いきなり全業務のスキル化を狙うのではなく、週次で必ず発生するタスクなどから 1〜2 スキルを作り、効果を測りながら広げていきます。

特に、スコープ設計とレビュー体制を最初に固めておくと、あとからスキルが増えたときにも混乱を抑えやすくなります。

セキュリティ・権限設計のポイント

CodexのAgent Skills は、ローカルやリモートの実行環境に対して実際のコマンドやスクリプトを実行する前提の仕組みです。安全に運用するためには、次のような観点もあらかじめ決めておくと安心です。

• 危険な操作をスキルに埋め込まない
  ファイルの削除・強制上書き・本番DBへの直接クエリなど、取り扱いを誤ると致命的になりうる操作は、スキルの中で安易に自動化しないようにします。
  
  
• APIキーやシークレットを直書きしない
  環境変数やSecret管理機構を前提にし、SKILL.md やスクリプト内にキー情報をハードコードしないルールを明示します。
  
  
• ADMINスコープのスキルにはオーナーを付ける
  組織全体で共有されるスキル（ADMINスコープ）は、メンテナーとレビュー責任者を明確にしておきます。
  
  
• 本番操作系スキルは「人間の最終確認」を必須にする
  デプロイや本番データ更新系のタスクは、Codexが提案 → 人間が確認して実行、という二段構えにしておくと安全側に振れます。

このあたりを「Agent Skillsの設計ポリシー」として最初から決めておくと、スキルが増えたあとも破壊的な操作が紛れ込みにくくなります。

Codex Skillsのトラブルシューディング

Agent Skills を Codex に載せて使い始めると、最初は次のようなポイントでハマる可能性があります。原因と確認ポイントをざっくりまとめておきます。

スキルが一覧に出てこない

まずは、skills 機能が有効かどうかと、「SKILL.md」の名前・パスを確認します（例：「~/.codex/skills/<skill-name>」や「.codex/skills/<skill-name>」）。

Codex は、シンボリックリンク配下のディレクトリや、YAML が壊れている「SKILL.md」 を自動的にスキップする可能性があります。この場合、構造に問題があるスキルは一覧に出てこないことがあります。

スキルが自動で発火しないとき

多くの場合は、「description」がふわっとし過ぎていて、Codex が「どんな依頼のときに使えばいいか」をうまく判断できていない可能性があります。

実際に投げるプロンプトを想定しながら 「〇〇のときにこのスキルを使う」という条件を 1 行でハッキリ書き直し、あわせて「このプロンプトで試すとよい」というサンプル文も「SKILL.md」に残しておくようにすると、改善につながりやすくなります。

起動時にバリデーションエラーが出るとき

「name」や「description」が複数行になっていたり、文字数上限（それぞれ 100 / 500 文字）を超えていると、Codex がスキルを無効化する可能性があります。

まずはこの2つのフィールドを見直し、YAML として正しいかを確認してから Codex を再起動してみましょう。ここに問題があるとスキル丸ごと読み込まれないことがあるため、最初にチェックしてみるポイントとしておすすめです。

導入前に決めておきたいチェックリスト

最後に、Codex の Agent Skills を導入する前に決めておくとスムーズなポイントを、チェックリスト形式でまとめます。

詳細な設計・運用の前に、まずは次の項目をチーム内でざっくり合意しておくと、その後の展開が楽になります。

• 最初に対象とするスコープ（REPO / USER / ADMIN）はどこか
• どのワークフローを「最初の1〜2スキル」としてスキル化するか
• 共通で使う SKILL.md テンプレート（sections構成）を決めているか
• スキルのレビュー／承認フローを誰がどう回すか
• 機密データや本番操作を含むスキルについて、禁止事項・例外ルールを明文化しているか
• Codex・Claude・GitHub Copilot など、どのツールにどのスキルを持たせるかの大まかな方針を決めているか

このチェックリストを埋めながら進めていくと、「とりあえず作ってみたが運用が追いつかない」という状況を避けやすくなります。

まとめ：Codexに「いつもの開発フロー」を覚えさせる

Codex の Agent Skills を使うと、単なる対話やコード生成にとどまらず、**「このリポジトリでは、こういう流れで作業する」**という開発フローそのものを Codex に覚えさせていくことができます。

ひとつひとつのスキルは、「SKILL.md」とフォルダ構成で定義された小さなワークフロー単位です。これらを REPO / USER / ADMIN / SYSTEM といったスコープに分けて配置することで、

• プロジェクト雛形の生成や初期セットアップ
• CI 失敗時のログ解析や再実行の手順
• インシデント初動対応や運用ルンブックの参照
• 仕様・設計レビューの観点をそろえるチェック

といった「よくある仕事の塊」を、Codex 経由である程度パターン化していくことができます。

Agent Skills 自体は共通の仕様（Agent Skills standard）に基づいており、Claude Skills や GitHub Copilot のエージェント機能とも世界観を共有しています。ただし、実際にアクセスできるリポジトリや実行環境、連携するツールはプロダクトごとに異なるため、同じスキルを持ち回す場合でも、動作確認はツール単位で行う前提にしておくと安心です。

最初から大掛かりなカタログを作ろうとする必要はありません。まずは「毎週必ず発生していて、手順がほぼ決まっている作業」を 1〜2 個スキル化してみて、そこから少しずつスコープ設計やレビュー体制を整えていくと、「スキルの資産」を無理なく育てていきやすくなります。

この Codex 版の記事とあわせて、Claude Code 版や GitHub Copilot 版の記事も並べて読めるようにしておくと、どのツールに、どの種類のスキルを任せるかという設計も整理しやすくなるはずです。