OpenAI Codex Skillsを調べてみた ~仕組み（段階的開示）・作成、呼び出し・Custom Promptsとの使い分け~

この記事でわかること

• Skillsは、タスク固有の手順・知識をSKILL.md中心にパッケージ化し、Codexに“必要なときだけ”読ませる仕組み

導入：.codex/skills を見つけた → 公式に追随する

ある日、いつもの様にCodexを触っているとリポジトリ内に .codex/skills/ が出てきて、「これ何？」となりました。公式changelogを確認すると、“Agent skills in Codex（2025-12-19）” としてSkillsが案内されていました。
新しく追加されたこの機能が気になり、今回はskillsについて調べました。

Skillsの概要

Skillsとは

Skillsは、今やAI Agentにおける標準的な機能拡張の仕組みです。
当初はAnthropicのClaudeの拡張機能として登場しましたが、2025年12月にオープンスタンダードとして公開され、現在では多くのAgentフレームワーク（Claude Code、GitHub Copilot、VS Code、Cursor、OpenAI Codex、Gemini CLI、Goose、Lettaなど）で採用されています。特定領域の専門知識（ドメイン知識）を外部化・パッケージ化する手法として業界標準となりつつあります。

具体的には、特定タスクの「指示（Markdown）＋必要に応じたスクリプト/リソース」を、ユーザーが明示的に指定しなくてもAgent が自動的に判断して利用できるようにするための仕組みです。
Codex CLIとIDE拡張の両方で利用できます。

ディレクトリ構造

Skillは「フォルダ」で表現され、SKILL.mdが必須です。必要に応じてスクリプトや参照資料を同梱します。

my-skill/
  SKILL.md        # Required
  scripts/        # Optional
  references/     # Optional
  assets/         # Optional

SKILL.mdの形式（YAML front matter）

SKILL.mdは YAML front matter + Markdown本文で構成されます。

• 必須：name（最大100文字。空ではない。一行以内。）
• 必須：description（最大500文字以内。空ではない。一行以内。）

例（ドキュメントの形式に合わせた最小例）：

---
name: skill名
description: このskillで何を実施するのか、どの様な文言をユーザーから言われた際にこのskillは実行されてほしいのか
---

# Instructions
ここに手順を書く

参照： https://developers.openai.com/codex/skills/create-skill

Skillsの探索場所（スコープと優先順位）

Codexは複数の場所からSkillsを読み、同名Skillは優先度の高いスコープが上書きします。優先度（高→低）は以下です。

優先順位	スコープ	パス (Linux/macOS例)	用途
高	REPO	$CWD/.codex/skills $CWD/**/.codex/skills $REPO_ROOT/.codex/skills	プロジェクト固有のルール （Lint規約、デプロイ手順など）
中	USER	$CODEX_HOME/skills (既定: ~/.codex/skills)	個人用の便利スキル （自分用のレビュー観点など）
低	ADMIN	/etc/codex/skills	組織・マシン全体で強制するポリシー
低	SYSTEM	(Codex同梱)	標準組み込みスキル

Progressive disclosure

まず、Progressive disclosure（段階的開示） について触れておきます。
これはUI/UXデザインの原則の一つで、「ユーザーの認知的負荷を減らすため、最初は重要な情報だけを提示し、ユーザーが求めたときだけ詳細を表示する」 という手法です。

Skillsでは、この概念をLLMのコンテキスト管理に応用しています。
自然言語で短くまとめた概要（name/description）だけを先に読み込み、必要になったSkillが選ばれた時点でそのSkillの詳細手順（本文）を追加で読み込むことで、初期のトークン消費を最小限に抑えています。

• Codexは起動時に、各Skillの name/description/path をロードします
• instructions body（SKILL.mdの本文）は、呼び出されるまでランタイムコンテキストに注入されません

---

SKILLSの作成と利用

1) 作成：$skill-creator

Codexにはスキル作成用の組み込みSkillがあり、CLI/IDE拡張から呼び出せます。

• IDE拡張
  

• CLI

  $skill-creator
  

作成フローでは「何をするSkillか」「いつ自動発火させたいか」などを聞かれ、結果として SKILL.md（必要ならスクリプト雛形も）が生成されます。

2) 呼び出し

Agentはタスク実行中、必要に応じて目的に合致したskillを選択して利用します。
目的に合致しているかどうかは、skillに定義された description で判断します。

（ユーザーが明示的にコマンドを打つ必要はなく、会話の流れの中で自然に発火するのが特徴です）

---

Custom Prompts、MCPとの違い

ここまでSkillsを学んで来たところで、類似機能である Custom Prompts や、標準プロトコルである MCP (Model Context Protocol) との使い分けを整理しました。
使い分けとしては以下が考えられるのではないでしょうか？

結論としての使い分け:

• Skills: チームで共有したい「手順」や「ノウハウ」のパッケージ化（How-toの提供）
• Custom Prompts: 作業内容が明確で作業効率を上げるための定型ショートカット（Templateの提供）
• MCP: 外部ツールやデータベースとの動的な接続（Capabilityの提供）

比較表

観点	Skills	Custom Prompts	MCP (Model Context Protocol)
主な目的	専門知識の伝授 （ベストプラクティス、社内手順、組織コンテキスト）	定型文の挿入 （ショートカット、指示のひな形）	外部機能の拡張 （API連携、DB接続、Web検索、社内SaaS）
適用タイミング	必要時（関連すると判断したときに本文を読む）	ユーザーが呼び出したとき（テンプレ本文が会話に入る）	必要時（必要なときにツールを呼ぶ）
AIへの読み込み	段階的開示：起動時にname/descriptionを先読み → 必要時にSKILL.md 本文を読み込む → 必要なら同梱ファイルも読む	呼び出し時に会話コンテキストへ展開（挿入）	動的ディスカバリー (サーバーからツール定義を取得)
情報の性質	手順知・組織/チーム固有のコンテキスト・ベストプラクティス（比較的安定）	固まった文言・フォーマット・指示の型（人が選んで入れる）	外部システムへのアクセス（取得・計算・操作）／状況に応じて変動
アンチパターン	「常に敬語で」等、常時ルールをSkillsに置く（そのSkillが読まれない限り効かない）	巨大なテンプレを作る（挿入時にトークン圧迫・ノイズ化）／テンプレで“知識ベース”をやろうとする	固定手順をMCP化（過剰実装。手順はSkills/テンプレで十分なことが多い）

補足：MCPとの関係
MCPは「ツールをAIに接続するための標準規格」であり、サーバーを立てて外部システムと会話することに特化しています。一方、Skillsは「リポジトリ内にMarkdownを置くだけ」という手軽さがあり、ドキュメント（知識）をそのままAIの能力に変える点に特長があります。

ユースケース例

skillsのユースケースとしては以下が考えられます。

• リポジトリの開発ルール（lint/test/commit規約）をスキル化（属人化防止）
• CI失敗時のログ解析テンプレ（チームで観点を揃える＝再現性）
• 定型レビュー観点のスキル化（抜け漏れ削減）

(AGENTS.md、カスタムコマンド、skillsと、使い分けが増え、プロンプトのメンテナンスが益々複雑化していきそうです...)

まとめ

• Skillsは「SKILL.md中心に、手順/資材/スクリプトを束ねて再利用する」仕組み
• LLMが利用場面に応じて内容をコンテキストに読み込んでくれるため、トークン消費が比較的節約できる

参考リンク

• Codex Skills 概要： https://developers.openai.com/codex/skills
• Skills 作成： https://developers.openai.com/codex/skills/create-skill
• Codex changelog： https://developers.openai.com/codex/changelog/
• Custom Prompts： https://developers.openai.com/codex/custom-prompts
• CLI Slash commands： https://developers.openai.com/codex/cli/slash-commands
• IDE Slash commands： https://developers.openai.com/codex/ide/slash-commands