Codex Skillsの作り方｜SKILL.mdで再利用できる手順を設計する

OpenAIの公式ドキュメントでは、Skillは特定の仕事を再現するための指示、リソース、任意のスクリプトをまとめたものです。リリース手順、レビュー観点、定期的なドキュメント更新など、入力や対象は変わっても判断順と成果物が繰り返される仕事に向きます。単発の依頼を保存する場所ではなく、次回も同じ完了条件で使える手順にします。

最初の候補は、チームで月に複数回行い、担当者によって確認漏れが出やすく、結果をテストできる仕事です。たとえばPR前検査なら、対象差分の確認、必要なテスト、禁止ファイルの検査、結果の報告までを一つのSkillにできます。製品全体の説明や、リポジトリのすべての規約を移すと呼び出し範囲が広がり、どの仕事を終わらせるSkillなのか分からなくなります。

リポジトリ全体で常に守る規約はAGENTS.md、今回だけの目的や制約はプロンプト、繰り返し使う一連の仕事はSkillへ置きます。外部サービスから最新データを読む必要がある場合は、手順だけをSkillに書き、接続自体はMCPなど適切なツールへ分けます。

公式仕様では、SkillはSKILL.mdを必須とするディレクトリです。必要になったときだけ、繰り返し実行するコードをscripts、長い説明や仕様をreferences、テンプレートや素材をassetsへ分けます。最初から各フォルダを空で作るより、SKILL.mdだけで試し、文章では再現しにくい処理や長すぎる資料が見つかった時点で切り出します。

SKILL.mdの先頭にはYAMLフロントマターでnameとdescriptionを置き、その後に実行手順を書きます。nameは呼び出し時に識別できる短い名前にします。descriptionは紹介文ではなく、どの依頼で使い、どの依頼では使わないかを判断できる文にします。CodexはSkillを選ぶ前に、まずnameとdescriptionなどのメタデータを参照するため、曖昧なdescriptionは誤起動と見逃しの両方につながります。

暗黙呼び出しでは、ユーザーの依頼とdescriptionの一致が選択の入口になります。『開発を支援する』のような広い表現では、調査、実装、レビュー、リリースのどこでも候補になり、他のSkillとも競合します。『Next.js公開ページのSEO監査と修正を行う。バックエンドAPI変更には使わない』のように、対象、仕事、除外範囲を先頭から書きます。

明示呼び出しにも対応できます。Codex CLIやIDE拡張ではSkillを直接指定できるため、再現テストでは明示呼び出しと自然文による暗黙呼び出しを分けて試します。明示したのに期待した作業をしない場合はinstructions、暗黙で選ばれない場合はdescription、関係ない依頼で選ばれる場合は境界を見直します。

本文は背景説明から始めず、作業者が実行できる順序で書きます。最初に必要な入力と不足時の扱いを定め、次に調査する場所、判断基準、変更対象、検証コマンド、最終報告を並べます。各工程は命令形にし、『適切に確認する』ではなく『変更ファイルを列挙し、禁止対象が含まれないことを確認する』のように観測可能な結果へ変えます。

例外時の停止条件も手順です。外部へ公開する、データを削除する、権限を広げるなど、通常手順から外れる操作は、どの情報を示して確認を求めるかまで書きます。一方、リポジトリ固有のコマンドや禁止事項がAGENTS.mdにあるなら全文を複製せず、その規約を読んで従う工程を置きます。正本を増やすと、Skillだけ更新されない状態が生まれます。

出力形式は作業の目的に合わせます。レビューSkillなら重大度、根拠、対象行、修正案、検証方法が必要です。記事作成Skillなら検索意図、タイトル、本文、一次情報、内部リンク、公開メタデータが成果物になります。見た目のテンプレートだけでなく、完了条件に必要な証拠を定義します。

Skillsは段階的に情報を読み込む設計です。最初にメタデータを見て、選択後にSKILL.md全体を読み、参照資料やスクリプトは必要な場面で使います。この仕組みを活かすには、SKILL.mdへすべての事例や仕様を貼らず、作業順と参照条件を残します。

referencesへ分ける基準は、毎回必要ではない長文かどうかです。複数フレームワークの設定例、製品ごとのAPI仕様、詳細な評価ルーブリックは、使う条件をSKILL.mdに書いて別ファイルへ置きます。scriptsへ分けるのは、同じ入力から同じ判定を返したい処理です。フォーマット検査、メタデータ検証、在庫集計などは文章で再現させるよりスクリプトで固定できます。

スクリプトを追加するときは、入力、出力、終了コード、変更する範囲を明記します。Skillがあるからといって、スクリプトへ広い削除権限や外部公開権限を持たせる必要はありません。実行前に対象を確認し、失敗時に途中状態を説明できる設計にします。

Skillのテストは、文章を読んで終わりではありません。使うべき依頼、使うか迷う境界の依頼、使うべきでない依頼を用意し、選択結果を確認します。次に、実際の小さな対象で最後まで実行し、必要な入力を聞けたか、対象外へ変更を広げなかったか、検証結果を残したかを見ます。

一度成功しても、手順が一般化できたとは限りません。入力の不足、既存変更、テスト失敗、外部API停止など、現実に起きる分岐を一つずつ追加します。失敗例からdescriptionと停止条件を修正し、Skillの変更もコードと同じように差分レビューします。