Codexの設定 - SKILL

概要

Agent Skills (以降、Skills) は、OpenAI Codex CLIに特定のタスクを実行するための専門的な手順、コンテキスト、スクリプトをパッケージ化して提供する仕組みである。

スキルは SKILL.md ファイルを中心として、オプションの scripts/、references/、assets/ ディレクトリを含むフォルダ構成を採用している。

スキルの主な目的を以下に示す。

繰り返しワークフローの再利用
プロジェクト固有の手順やチェックリスト等、何度も実行するワークフローをスキルとして定義し、一貫して再利用する。
専門知識のパッケージ化
ドメイン固有の知識や手順をスキルとして文書化し、Codexが確実に追えるようにする。
チーム標準の統一
チーム全体で同じスキルを共有することにより、作業手順の標準化を実現する。

Skillsは、Anthropicが起源となったオープン標準であるSKILL.md形式を採用しており、Claude Code、Gemini CLI、GitHub Copilot、Windsurf、Cline等、25を超えるツールで互換動作する。
Codex 用に作成したスキルは、他の対応ツールのスキルディレクトリにコピーするだけでそのまま利用できる。

設計哲学

単一責任の原則

スキルの設計において最も重要な原則は、1つのスキルに1つの仕事のみを担わせることである。

汎用的なスキルを1つ作るよりも、明確に絞り込んだスキルを複数作る方が望ましい。

具体的なユースケースの例を以下に示す。

推奨構成の例
code-review、test-generation、pr-checklist の3つのスキルに分割する。
非推奨構成の例
development-tools という汎用的な1つのスキルにまとめる。

新しくスキルを作成する際は、具体的なユースケースを2から3個程度から始めることを推奨する。
その後、実際の運用経験を経てエッジケースを追加対応していく方が、最初から網羅的に設計するよりも実用的なスキルになる。

段階的公開 (Progressive Disclosure)

Codexはコンテキストウィンドウの効率的な利用のため、スキルの情報を2段階で読み込む設計を採用している。

第1段階 (常時ロード)
フロントマターの name と description のみをシステムプロンプトに追加する。

この段階では本文は読み込まれない。
第2段階 (トリガー時のみ)
Codexがスキルを使用すると判断した時点で、初めて SKILL.md 本文とバンドルリソースを読み込む。

この設計により、多数のスキルをインストールしている場合でも、コンテキストウィンドウを効率的に使用できる。

常時ロードされるスキルリストの初期サイズはモデルのコンテキストウィンドウの約2[%]、またはコンテキストウィンドウが不明な場合は8,000文字を上限とする。

スキル数が多い場合は description が短縮されることがあり、スキル数が極端に多い場合はリストから一部が省略され警告が表示される。

ファイル構造

スキルは、以下に示すディレクトリ構造を持つフォルダとして管理する。

skill-folder/
├── SKILL.md              # 必須: フロントマター + 本文指示
├── scripts/              # オプション: CLIスクリプト (bash / python / javascript)
├── references/           # オプション: 詳細ドキュメント、仕様書、APIリファレンス
├── assets/               # オプション: テンプレート、設定ファイル、アイコン等
└── agents/
      └── openai.yaml     # オプション: Codex App UI設定とMCP依存宣言

各ファイル・ディレクトリの役割を以下に示す。

SKILL.md
必須ファイル

YAMLフロントマターとMarkdown本文で構成される。
scripts/
決定論的な動作が必要な処理をスクリプトとして格納する。

validation、変換、解析等、Codexへの指示だけでは再現性が確保しにくい処理に使用する。
references/
詳細な仕様書、API定義、例示ドキュメント等を格納する。

SKILL.md本文を簡潔に保ちながら、詳細情報はここに集約する。
assets/
スキルが生成・使用するテンプレートや静的リソースを格納する。
agents/openai.yaml
Codex App向けのUI設定、暗黙的呼び出しポリシー、MCP依存宣言を定義する。

配置場所

スキルは、以下に示す4つのスコープのいずれかに配置する。

スキルの配置スコープ一覧
スコープ	パス	用途
リポジトリ (プロジェクト固有)	.agents/skills/ (カレントディレクトリまたはリポジトリルート)	特定プロジェクト内でのみ使用するスキルチームで共有する場合はリポジトリにコミットする。
リポジトリ (組織全体)	<repo>/.agents/skills/	リポジトリ全体に適用するスキル複数サブディレクトリから共通利用する場合に配置する。
ユーザ個人	$HOME/.agents/skills/	全プロジェクトで個人的に使用するスキル自分だけが使う汎用スキルを配置する。
システム全体	/etc/codex/skills/	システム上の全ユーザに共通するスキル管理者が配置する。

ロード順序については、プロジェクトレベルのスキルがユーザレベルのスキルよりも優先される。
同じ name を持つスキルが複数存在する場合、Codexはマージせずにどちらもスキルセレクタに表示する。

なお、Codexはスキルフォルダを .agents/skills/ と .codex/skills/ の両方から自動的に検出する。

SKILL.mdフォーマット

Frontmatter (YAML)

SKILL.md ファイルは、YAMLフロントマターとMarkdown本文で構成される。

下表に、フロントマターで設定できる全フィールドを示す。

SKILL.md フロントマターフィールド一覧
フィールド	必須/任意	説明
`name`	必須	スキルの識別子 64文字以下、小文字・数字・ハイフンのみ使用可能フォルダ名と一致させる必要がある。省略した場合はフォルダ名が使用される。
`description`	必須	スキルの説明暗黙的呼び出しのトリガー条件として機能する。何をするか・いつ使うかの両方を記述する。
`when_to_use`	任意	明示的なトリガー条件のリスト「Use when...」「Don't use when...」の形式で記述する。
`argument-hint`	任意	スラッシュコマンド呼び出し時にユーザへ表示するプレースホルダーテキスト例: `[issue-number]`
`arguments`	任意	スラッシュコマンド呼び出し時の構造化された引数スキーマ定義
`allowed-tools`	任意	スキル実行時に事前承認するツールのホワイトリスト例: `Bash(git:*)`、`Read`、`Write` ツールを制限するものではなく、事前承認するものであることに注意する。
`disable-model-invocation`	任意	`true` に設定すると、 Codexがdescriptionに基づいてスキルを自動選択しなくなる。明示的呼び出しのみが有効になる。
`paths`	任意	スキルが対象とするファイルのglobパターン例: `["package.json", "/.env", "/Dockerfile"]`
`model`	任意	スキル実行時に使用するモデルを上書き指定する。
`effort`	任意	拡張思考の努力レベルヒント `low`、`medium`、`high` のいずれかを指定する。

フロントマターの記述上の注意事項を以下に示す。

YAMLではタブが使用できない。
インデントは必ずスペースで記述する。
タブを使用するとパースエラーとなる。
フロントマターブロックは、--- のみの行で開始・終了する必要がある。
user-invocable: false と disable-model-invocation: true を同時に設定すると、スキルへのアクセスが完全に遮断される。

本文 (Markdown)

フロントマターの後にMarkdown形式でスキルの実行手順を記述する。

本文の記述方針を以下に示す。

実行手順は命令形で記述する。
「読み込む」「確認する」「実行する」のように、Codexへの指示として明確に記述する。
「When to Use This Skill」セクションを本文に記述しない。
本文はトリガー後にのみ読み込まれるため、トリガー条件の説明はフロントマターの description に記述する。
scripts/、references/、assets/ へのリンクで本文を簡潔に保つ。
詳細情報は各ディレクトリに格納し、本文からパスで参照する。
コンテキストウィンドウは公共財である。
不要な説明を避け、実行可能なコンテンツに集中する。

descriptionの記述

description フィールドはスキルの暗黙的呼び出しにおける主要なトリガーメカニズムである。
この記述の質が、triggering reliability (呼び出し精度) に直結する。

description には以下の2つを必ず含める。

何をするか
スキルが実行する具体的なタスクの説明
いつ使うか
どのようなプロンプトや状況でスキルが呼び出されるべきかのトリガー条件

良い例と悪い例を以下に示す。

descriptionの良い例と悪い例
評価	記述例	問題点
良い例	Performs code reviews for staged git changes, focusing on security vulnerabilities, logic errors, and style issues. Use when asked to review code, check for issues before a pull request, or audit recent changes.	何をするかと、いつ使うかの両方を明確に記述している。
悪い例	A code review tool.	何をするかしか分からない。トリガー条件が不明確のため、自動選択されにくい。
良い例	Runs the full test suite and summarizes failing tests with suggested fixes. Use when running tests, debugging test failures, or checking test coverage.	動作とトリガー条件がともに具体的である。
悪い例	Test runner skill.	抽象的すぎて自動選択されない。

また、段階的公開の仕組みにより、スキルリストが大量になった場合は description が短縮される。
重要なキーワードとトリガーワードをできるだけ文頭に配置することにより、短縮された場合でも適切に機能する記述を心がける。

スキルの呼び出し方法

明示的呼び出し

ユーザがスキルを直接指定して実行する方法である。

Codex CLI および IDEでは、以下のいずれかの方法でスキルを明示的に呼び出す。

codex /<スキル名>

またはプロンプト中で $ を使用してスキルをメンションする方法もある。

$<スキル名> を使って依存ライブラリの脆弱性をチェックして

disable-model-invocation: true を設定したスキルは、明示的呼び出しのみが有効となる。

暗黙的呼び出し

ユーザのプロンプトが description フィールドの内容と一致すると判断された場合に、Codexがスキルを自動的に選択して実行する。

ユーザはスキルの名前を知らなくても、自然言語でタスクを依頼するだけで適切なスキルが自動実行される。

暗黙的呼び出しの例を以下に示す。

ユーザのプロンプト
「このPRのコードを確認してほしい」
Codexの動作
description に "Use when asked to review code... before a pull request" と記述された code-review スキルを自動選択して実行する。

agents/openai.yaml で allow_implicit_invocation: false を設定したスキルは、暗黙的呼び出しが無効となり明示的呼び出しのみが有効になる。

scripts/ディレクトリの活用

スキルの動作は原則としてMarkdown本文への指示で実現するが、決定論的な動作が必要な処理はスクリプトとして scripts/ ディレクトリに格納する。

スクリプトを使用すべきケースを以下に示す。

validation (入力値の検証)
特定の形式に合っているかを確認する処理
変換
ファイル形式の変換や構造の変換等
解析
ログ解析、依存関係の抽出等

利用可能な言語は、bash、python、javascript (Node.js) 等である。

SKILL.md本文からスクリプトを参照する例を以下に示す。

 ## 実行手順
 
 1. `scripts/validate-input.sh` を実行して入力値を検証する。
 2. 検証に失敗した場合は、エラーメッセージを表示して処理を中断する。
 3. 検証に成功した場合は、`scripts/transform.py` を実行してファイルを変換する。

MCP統合

agents/openai.yamlによる依存宣言

スキルがMCPサーバを必要とする場合、agents/openai.yaml の dependencies セクションにMCPサーバを宣言する。

この宣言により、Codexはスキル使用時に必要なMCPサーバが利用可能かどうかを確認し、適切に接続できる。

agents/openai.yaml のサンプルを以下に示す。

 interface:
   display_name: "OpenAI Docs Search"
   short_description: "OpenAI開発者ドキュメントを検索する"
   icon_small: "./assets/small-logo.svg"
   icon_large: "./assets/large-logo.png"
   brand_color: "#3B82F6"
   default_prompt: "OpenAIドキュメントを参照しながら回答してください"
 
 policy:
   allow_implicit_invocation: false
 
 dependencies:
   tools:
     - type: "mcp"
       value: "openaiDeveloperDocs"
       description: "OpenAI Docs MCP server (streamable HTTP)"
       transport: "streamable_http"
       url: "https://developers.openai.com/mcp"
     - type: "mcp"
       value: "localFileSystem"
       description: "Local filesystem MCP server (stdio)"
       transport: "stdio"
       command: "mcp-server-filesystem"
       args: ["--root", "/workspace"]

interface セクションのフィールドを以下に示す。

display_name
Codex App でユーザに表示される名前
short_description
ユーザ向けの短い説明文
icon_small / icon_large
アイコン画像ファイルへの相対パス
brand_color
ブランドカラーの16進数カラーコード
default_prompt
スキル使用時にデフォルトで付加されるプロンプト

policy セクションの allow_implicit_invocation をfalseに設定すると、Codexがプロンプトからスキルを自動選択しなくなる。
明示的な $<スキル名> 形式の呼び出しは引き続き有効である。

Feature Flagによる自動インストール

スキルが agents/openai.yaml でMCP依存を宣言している場合、Codexは不足しているMCP依存を自動的にインストールする機能を持つ。
この機能はデフォルトで有効となっている。

スキルをリポジトリにコミットすることで、チームメンバー全員がスキルを使用する際に必要なMCPサーバが自動的にセットアップされる。

config.tomlでのスキル設定

スキルを削除せずに無効化する場合は、~/.codex/config.toml に skills.config エントリを追加する。

 [[skills.config]]
 path = "/home/user/.agents/skills/my-skill/SKILL.md"
 enabled = false
 
 [[skills.config]]
 path = "/path/to/project/.agents/skills/log-triage/SKILL.md"
 enabled = false

設定を変更した後は、Codexを再起動して反映させる。

スキルのロード順序については、プロジェクトレベル (.agents/skills/) のスキルがユーザレベル ($HOME/.agents/skills/) のスキルよりも優先される。
同一名のスキルが存在する場合はマージされず、両方がスキルセレクタに列挙される。

SKILL.mdサンプル

最小限のサンプル

以下に最小限の構成のSKILL.mdサンプルを示す。

ログファイルを解析してトリアージレポートを生成するスキルの例である。

 ---
 name: log-triage
 description: Analyzes application log files to identify root causes, key errors, and suggests next debugging steps. Use when asked to analyze logs, debug errors, or investigate application issues.
 ---
 
 # Log Triage
 
 Analyze the provided log content and produce a triage report.
 
 ## Steps
 
 1. Scan the log for ERROR, WARN, and FATAL level entries.
 2. Identify the most frequent and critical errors.
 3. Determine the likely root cause based on error context and timestamps.
 4. Suggest the next three concrete debugging steps.
 
 ## Output Format
 
 - Root cause summary (1-2 sentences)
 - Top 3 errors with line references
 - Next debugging steps (numbered list)

詳細なサンプル

以下に詳細な構成のSKILL.mdサンプルを示す。

PRレビューチェックリストを実行するスキルの例であり、allowed-tools、arguments、スクリプト参照を活用している。

 ---
 name: pr-review-checklist
 description: Runs a comprehensive pull request review checklist covering security, logic correctness, test coverage, and code style. Use when asked to review a PR, check a pull request, or audit staged changes before merging.
 argument-hint: "[branch-name or PR number]"
 allowed-tools:
   - Bash(git:*)
   - Read
   - Grep
 effort: medium
 ---
 
 # PR Review Checklist
 
 Run a comprehensive review of the specified pull request or branch.
 
 ## Steps
 
 1. Execute `scripts/fetch-diff.sh` to retrieve the diff for the target branch or PR.
 2. Review the diff for the following concerns:
    - Security vulnerabilities (injection, authentication, sensitive data exposure)
    - Logic errors and edge cases
    - Missing or insufficient test coverage
    - Code style and naming conventions
 3. Consult `references/review-guidelines.md` for project-specific standards.
 4. Produce a structured review report.
 
 ## Output Format
 
 - Summary of changes
 - Issues found (grouped by severity: Critical / Major / Minor)
 - Suggested improvements
 - Pass / Fail verdict

agents/openai.yamlサンプル

以下に agents/openai.yaml のサンプルを示す。

 interface:
   display_name: "PR Review Assistant"
   short_description: "プルリクエストの包括的なレビューを実行する"
   icon_small: "./assets/icon-small.svg"
   icon_large: "./assets/icon-large.png"
   brand_color: "#0EA5E9"
   default_prompt: "以下のPRを包括的にレビューしてください"
 
 policy:
   allow_implicit_invocation: true
 
 dependencies:
   tools:
     - type: "mcp"
       value: "githubApi"
       description: "GitHub REST API MCP server"
       transport: "streamable_http"
       url: "https://api.github.com/mcp"
     - type: "mcp"
       value: "localShell"
       description: "Local shell execution MCP server"
       transport: "stdio"
       command: "mcp-server-shell"
       args: ["--allow-git"]

interface セクションはCodex Appでのスキル表示をカスタマイズするためのものであり、CLI環境では無視される。

CLI / IDE / Codex App共通動作

スキルは CLI、IDE拡張機能、Codex Appのいずれの環境でも共通して動作する。

各環境における動作の特徴を以下に示す。

CLI環境
/<スキル名> または $<スキル名> で明示的に呼び出す。

description に基づく暗黙的呼び出しも有効である。
IDE拡張機能
チャット入力欄で / または $ でスキルをメンションできる。
Codex App
agents/openai.yaml の interface セクションに基づいてスキルが表示される。

display_name や icon を設定することにより、視覚的に分かりやすいUIを提供できる。

全環境において、明示的呼び出しと暗黙的呼び出し (descriptionに基づく自動選択) の両方が共通して動作する。

推奨事項

1 skill = 1 job の維持

スキルは単一の明確なタスクに特化させる。
複数のタスクを1つのスキルにまとめると、description が曖昧になり自動選択精度が下がる。

具体的なユースケースから始める

まず、2〜3個の具体的なユースケースを想定してスキルを設計する。
実際の利用経験を経てから段階的にエッジケースへの対応を追加する方が、最初から包括的に設計するよりも実用的なスキルになる。

descriptionを具体的に記述する

description フィールドは何をするかと、いつ使うかの両方を具体的に記述する。
抽象的な説明はトリガー精度を低下させるため、重要なキーワードを文頭に配置することで短縮時でも機能する記述を心がける。

SKILL.md本文を簡潔に保つ

SKILL.md本文はコンテキストウィンドウを消費する。
詳細情報は、references/ や assets/ ディレクトリに格納し、本文からパスで参照する方式を採用することで本文を簡潔に維持する。

エッジケースは事後対応

スキルの初期設計では主要なユースケースのみをカバーする。
エッジケースや例外処理は、実際に問題が発生してから追加する方が効率的である。

Skillsとプラグインの関係

下表に、スキルとプラグインの役割の違いを示す。

Skillsとプラグインの比較
項目	Skill	Plugin
形式	ディレクトリ + SKILL.md	バンドルされたパッケージ
主な用途	ローカル開発、リポジトリスコープ、チーム内共有	配布、マーケットプレイス公開
複数スキルの管理	個別ディレクトリで独立管理	複数のスキルを1パッケージにバンドル
アプリ統合	agents/openai.yaml で個別設定	アプリマッピングとMCP設定を一括バンドル
配布方法	ディレクトリコピーまたはリポジトリへのコミット	パッケージマネージャ、マーケットプレイス

スキルをプラグインとしてパッケージ化する主なケースを以下に示す。

2つ以上のスキルをバンドルして配布したい場合
アプリ統合 (MCPサーバ設定等) と一緒に配布したい場合
マーケットプレイスを通じてコミュニティへ公開したい場合

ローカル開発段階ではスキルフォルダ形式を使用し、再利用可能な形で配布・公開する段階でプラグイン化することを推奨する。