Codex Skillsの作り方｜繰り返す開発手順をSKILL.mdへまとめる

Codexへ何度も同じ作業順、判断基準、完成条件を説明しているなら、Skillにまとめる候補です。最初からscriptや大量の資料を詰め込まず、一つの目的に絞ったSKILL.mdだけで実タスクを通すところから始めます。

よいSkillは「万能な開発支援」ではありません。いつ使い、何をし、どこまで扱わないかが明確なworkflow（再利用する作業手順）です。本記事では、最小構成、descriptionの設計、保存場所、呼び出し方、AGENTS.md・Plugin・MCPとの違いまで整理します。

3行まとめ

• Skillはdirectoryと必須のSKILL.mdで作り、frontmatterへnameとdescriptionを書きます。
• descriptionは自動選択の手掛かりになるため、「何をする」「どんな依頼で使う」「扱わない範囲」を短く具体化します。
• 常時守る規約はAGENTS.md、再利用手順はSkill、配布単位はPlugin、外部能力への接続はMCPと役割を分けます。

Codex Skillとは

Skillは、Codexが必要なときに読み込む再利用可能なworkflowです。OpenAI公式のBuild skillsによると、指示、参考資料、任意のscriptを一つのdirectoryへまとめます。形式はAgent Skills specificationを基礎にしています。

最小構成は次のとおりです。

review-release/
└── SKILL.md

必要になった場合だけ資源を追加できます。

review-release/
├── SKILL.md              # 必須: metadataと作業手順
├── scripts/              # 任意: 決定的に実行したい処理
├── references/           # 任意: 必要時だけ読む資料
├── assets/               # 任意: 出力に使うtemplateや素材
└── agents/
    └── openai.yaml       # 任意: UI表示用metadata

Codexは最初から全Skillの本文を読むわけではありません。まずnameとdescriptionを読み、依頼に合うSkillが選ばれた後でSKILL.md本文を読みます。これがprogressive disclosure（必要な情報を段階的に読み込む仕組み）です。

この仕組みにより、すべての手順を常時contextへ入れずに済みます。一方、入口になるdescriptionが曖昧だと、必要なときに選ばれない、または無関係な依頼で選ばれる原因になります。

Skillにする仕事・しない仕事

Skillに向くのは、何度か繰り返し、毎回ほぼ同じ判断と順序を使う仕事です。

作成前に、実際の依頼を2〜3個書き出します。たとえばrelease reviewなら「mainとの差分を確認」「対象testを実行」「migrationとbreaking changeを確認」「結果を重要度順に返す」です。具体例がないまま抽象的なSkill名を決めると、境界が広がりやすくなります。

最小SKILL.mdを作る

ここでは、release前のread-only reviewを行うreview-releaseを例にします。

---
name: review-release
description: リリース前のブランチを、差分、テスト、migration、互換性の観点で読み取りレビューする。公開可否の確認やリリース前チェックを依頼されたときに使う。コード変更、commit、push、deployには使わない。
---

# Release Review

1. repositoryのAGENTS.mdとrelease手順を読む。
2. mainとの差分と変更file一覧を確認する。
3. 変更範囲に対応するtestを特定して実行する。
4. migration、公開API、設定値、rollback手順を確認する。
5. 結果をcritical、warning、passed、unverifiedに分けて返す。

## Safety

- fileを変更しない。
- commit、push、deployを行わない。
- secretや.envの内容を出力しない。
- 実行できなかったtestを成功として扱わない。

## Completion

- 確認したcommitと比較対象を示す。
- 実行したcommandと終了statusを示す。
- 未確認事項を空にせず、なければ「なし」と書く。

frontmatterで必須なのはnameとdescriptionです。本文には実行順、判断基準、安全境界、完了条件を置きます。長い背景説明より、別のCodex instanceが迷う判断を優先して残します。

この例ではcodeを変更しないため、実装用のscriptはまだ不要です。SkillはMarkdownだけでも成立します。

descriptionを発火契約として書く

descriptionは一覧表示用の紹介文だけではありません。Codexが暗黙にSkillを選ぶときの主要な手掛かりです。本文へ「いつ使うか」を詳しく書いても、Skillが選ばれる前には本文が読まれないため、入口の問題を解決できません。

悪い例と改善例を比較します。

設計時は次の3点を一文ずつ考えます。

1. 何を入力として、何を出力するか
2. ユーザーがどんな言葉で依頼したときに使うか
3. 似ているが対象外の仕事は何か

対象外を増やしすぎるとdescriptionが読みにくくなります。誤発火しやすい隣接taskだけを明示し、細かな安全規則は本文へ置きます。

配置と呼び出し

2026年8月28日時点の公式資料では、主な探索場所は次のとおりです。

repository Skillは、現在の作業directoryからrepository rootまでの.agents/skillsで探索されます。同じnameのSkillが複数見つかっても内容はmergeされません。意図しない重複を避けるため、名前とscopeを定期的に確認します。

Codex CLIとIDEでは/skillsから選ぶか、$review-releaseのように明示できます。ChatGPTでは@メニューから選べます。明示しない場合も、依頼がdescriptionと一致すると選ばれることがあります。

最初の動作確認では明示呼び出しを使います。

$review-release 現在のbranchをmainと比較し、リリース前レビューをしてください。

次に、Skill名を含めない自然な依頼で暗黙選択を確認します。

このbranchを公開してよいか、差分、test、migration、互換性を読み取りだけで確認してください。

選ばれない場合は、本文を増やす前にdescriptionと実際の依頼語が対応しているか見直します。変更が自動検出されない場合はCodexを再起動して確認します。

scripts、references、assetsへ育てる

最小Skillを実タスクで使うと、毎回繰り返している部分が見えます。その時点で資源を分けます。

scriptは、AIへ考えさせる必要がない定型処理に向きます。たとえばYAML schema検証やfile一覧の集計です。一方、「breaking changeかどうか」のように文脈依存の判断まで単純なscriptへ押し込むと、例外条件を見落とします。

referencesは置くだけでは不十分です。SKILL.mdへ「migrationを確認するときはreferences/migration-policy.mdを読む」のようにrouting（必要な資料を選ぶ指示）を書きます。全資料を毎回読む設計ではprogressive disclosureの利点が薄れます。

Skill、AGENTS.md、Plugin、MCPの違い

似た仕組みを、内容と適用時点で分けます。

公式資料では、Skillはworkflowを設計し、Pluginはそれをinstall・distributionする仕組みと整理されています。個人または一repositoryだけで使う小さな手順なら、まずstandalone Skillで十分です。複数のSkill、MCP、app、Hookを利用者へまとめて届ける段階でPluginを検討します。

MCPは「何ができるか」を増やし、Skillは「その能力をどの順番と判断で使うか」を教えます。たとえばissue trackerへ接続するMCPがあっても、release reviewでどのlabelを確認し、どの形式で報告するかはSkill側のworkflowにできます。

検証と改善

Skillの完成条件は、SKILL.mdが書けたことではありません。現実的な依頼で意図どおりに選ばれ、境界内で成果を返せることです。

次の順で確認します。

1. directory名とnameを一致させる
2. YAML frontmatterにnameとdescriptionがあることを検証する
3. 明示呼び出しでhappy pathを一度通す
4. Skill名を含めない自然な依頼で暗黙選択を確認する
5. 隣接する対象外taskで誤発火しないか確認する
6. 完了条件、失敗status、未確認事項がreportに残るか確認する
7. 迷った判断だけをSKILL.mdまたはreferencesへ追加する

一度の実行で不足が出ても、すぐ巨大なmanualにしない方が保守しやすくなります。Codexが迷った箇所、毎回書き直したcode、参照を探し直した資料を記録し、次の反復で対応する資源へ移します。

複雑なSkillを複数担当で検証する場合は、Codexサブエージェントの使い方で扱った「読み取りを並列化し、変更を一担当へ集約する」型が使えます。複数担当が同じSKILL.mdを同時編集しないようにします。

失敗しやすい設計

万能Skillを作る

「開発全般」「文書作成全般」のようなscopeでは、通常のCodex能力と重なり、いつ選ぶべきか判断できません。一つの成果物または完了条件へ絞ります。

すべてをSKILL.mdへ入れる

長いschema、全API仕様、巨大な例を本文へ置くと、選択後のcontextが重くなります。必要時だけ読む資料はreferences/へ分け、routingを明記します。

descriptionを本文の要約だけにする

「高品質なreviewを行う」だけではtriggerがありません。ユーザーの依頼語と対象外taskまで含めて発火境界を作ります。

scriptの失敗を成功扱いする

検証scriptが依存関係不足や権限で動かなかった場合、未確認として報告させます。終了codeを無視して「問題なし」とする手順を書いてはいけません。

秘密情報や環境固有値を埋め込む

Skillは共有、配布、version管理され得ます。API key、password、private URLのcredentialを本文やassetへ置かず、環境変数や承認済みconnectorから受け取ります。

同名Skillを上書き前提で置く

同名Skillはmergeされません。user Skillとrepository Skillに同じ名前を使うと、どちらを選ぶか分かりにくくなります。scopeが違うなら名前を分けます。

作成チェックリスト

• [ ] 実際に繰り返した依頼例が2件以上ある
• [ ] 一つの成果物または完了条件へscopeを絞った
• [ ] directory名とnameが一致している
• [ ] descriptionに行うこと、trigger、隣接する非対象を含めた
• [ ] 本文に実行順、判断基準、安全境界、完了条件がある
• [ ] 常時規約をSkillへ重複させずAGENTS.mdへ残した
• [ ] 秘密情報と環境固有credentialを含めていない
• [ ] referencesを読む条件とscriptsを実行する条件を明記した
• [ ] 明示呼び出し、暗黙選択、非対象taskで動作を確認した
• [ ] 実行できなかった検証を未確認として報告できる

Skillは、過去のpromptを保存する箱ではありません。うまくいった作業から、再利用できる順序、判断、安全境界、完了条件を抽出する仕組みです。最小のSKILL.mdを一度使い、実行中に生じた迷いだけを次の版へ戻すと、過剰な手順書にせず再現性を上げられます。

Skillを置いたrepositoryでCodexがfileを書けない場合は、Skillを変更する前にCodexがファイルを編集できないときの対処法でsandboxとapprovalを確認してください。Skillは権限範囲を広げません。

参考資料

• Build skills – OpenAI Docs（2026年8月28日確認）
• Agent Skills specification（2026年8月28日確認）
• Build plugins – OpenAI Docs（2026年8月28日確認）