CodexのSKILL.mdの書き方｜明示呼び出しだけに制限する設定方法

Codexで同じ作業を繰り返すたびに、長い指示を一から書き直していないでしょうか。記事作成、コードレビュー、資料チェックなど、手順が決まった仕事はスキルにまとめると再利用できます。一方で、専門的なスキルが関係のない依頼でも自動的に選ばれるのは避けたい場合があります。

結論から言うと、作業手順は SKILL.md に書き、明示呼び出しだけに制限する設定は agents/openai.yaml に分けて書きます。description に「明示時のみ」と記載するだけではなく、allow_implicit_invocation: false を設定することが重要です。

この記事では、2026年7月22日時点のOpenAI公式資料とAgent Skills仕様を基に、リポジトリ固有スキルの最小構成、説明文の考え方、明示呼び出し限定の設定、動作確認まで順番に解説します。

スキルは専用フォルダとSKILL.mdで作る

リポジトリ全体で使うスキルは、プロジェクトルートの .agents/skills 以下へ、スキルごとのフォルダを作って配置します。例えば、Imidef Blogの記事を作る markdown-blog-writer なら、基本の構造は次のとおりです。

.agents/
└── skills/
    └── markdown-blog-writer/
        ├── SKILL.md
        └── agents/
            └── openai.yaml

OpenAI公式資料によると、Codexは現在の作業ディレクトリからリポジトリルートまでの .agents/skills を探索します。個人が複数のリポジトリで使うスキルはユーザー用の配置場所も選べますが、特定プロジェクトのフォルダ構成や検証方法に依存するスキルは、リポジトリ内へ置く方が共有しやすくなります。

スキル名は親フォルダ名と一致させます。Agent Skills仕様では、小文字の英字、数字、ハイフンを使い、先頭と末尾のハイフンや連続するハイフンを避ける形式が定められています。

SKILL.mdはメタデータと実行手順に分ける

SKILL.md は、先頭のYAMLフロントマターと、その後のMarkdown本文で構成します。必須のメタデータは name と description です。

---
name: markdown-blog-writer
description: Create paired Japanese and English Markdown articles for Imidef Blog. Use only when the user explicitly invokes $markdown-blog-writer for an article-generation task.
---

# Markdown Blog Writer

指定されたテーマを公式資料で調査する。
日本語記事、英語記事、共通OGP画像を作成する。
保存後にMarkdownとプロジェクトを検証する。

name は呼び出しに使う識別子です。description には「何をするか」だけでなく、「どのような依頼で使うか」「どのような場合は使わないか」まで簡潔に書きます。単に「ブログを手伝う」とするより、成果物、対象プロジェクト、明示呼び出し条件まで含める方が、誤った選択を減らせます。

本文には、入力、処理の順序、出力先、停止条件、禁止事項、検証方法を命令形で記載します。長い参考資料や決定的に実行したい処理は、必要に応じて references や scripts へ分けられます。

descriptionはスキルを見つけるために使われる

Codexは、すべてのスキルの長い手順を最初から読み込むわけではありません。最初に name、description、ファイルの場所など限られた情報を確認し、依頼に合うスキルを選んだときに、完全な SKILL.md を読み込みます。この仕組みはprogressive disclosureと呼ばれます。

そのため、暗黙呼び出しが許可されているスキルでは description が選択精度に大きく影響します。対象を広く書きすぎると無関係な依頼で選ばれやすくなり、狭すぎると必要な場面で見つかりません。具体的な成果物と利用条件を冒頭へ置き、曖昧な表現を減らすことが基本です。

ただし、description に「明示的に呼び出された場合だけ使う」と書くことと、システム上の暗黙呼び出しを無効にすることは別です。説明文は適切な判断を助けますが、呼び出し方を制御する正式な設定は次の openai.yaml に置きます。

明示呼び出しだけにするにはopenai.yamlを追加する

スキルフォルダ内へ agents/openai.yaml を作り、policy.allow_implicit_invocation を false にします。設定しない場合の既定値は true です。

interface:
  display_name: "Markdown Blog Writer"
  short_description: "Imidef Blog向けの日英記事とOGP画像を作成"
  default_prompt: "Use $markdown-blog-writer to create an article for the specified topic."

policy:
  allow_implicit_invocation: false

この設定では、依頼内容が description と一致していても、Codexがスキルを暗黙に起動しなくなります。一方、ユーザーが $markdown-blog-writer と指定した明示呼び出しは引き続き利用できます。

interface はデスクトップアプリなどに表示する名前、短い説明、呼び出し時の初期プロンプトを設定する任意項目です。明示呼び出し限定に必要な中心部分は policy です。description にも対象範囲を書いておくと、スキル一覧で目的を理解しやすくなり、明示呼び出し後の誤用も防ぎやすくなります。

スキルを明示的に呼び出す方法

Codex CLIやIDEでは、入力欄で $ に続けてスキル名を指定できます。スキル一覧から選びたい場合は /skills も利用できます。

$markdown-blog-writer SKILL.mdの書き方と明示呼び出しの設定方法

デスクトップアプリではSkillsから対象スキルを探して選択できます。選択後は、スキル名だけで終わらせず、今回のテーマや成果物など、その実行に必要な入力を続けて書きます。

明示呼び出しは、実行コストが大きい処理、ファイルを複数作る処理、外部調査や画像生成を伴う処理、限られた用途だけで使いたい処理に適しています。頻繁な定型作業を自然な依頼から自動選択してほしい場合は暗黙呼び出しも便利ですが、誤起動時の影響と比較して決めてください。

設定後は明示と暗黙の両方を試す

保存後は、まずスキルが一覧へ表示されるか確認します。Codexはスキルの変更を自動検出しますが、追加や更新が表示されない場合は再起動します。

次に、新しいチャットで明示呼び出しを行い、SKILL.md の手順が読み込まれることを確認します。その後、スキル名を書かずに似た依頼を送り、allow_implicit_invocation: false の状態で自動起動しないことも確かめます。

うまく動かない場合は、次の順番で切り分けます。

• フォルダ名と name が一致しているか
• YAMLフロントマターが --- で正しく閉じているか
• description が空ではなく、対象と条件を具体的に示しているか
• agents/openai.yaml の位置とインデントが正しいか
• allow_implicit_invocation が文字列ではなく真偽値の false になっているか
• 再起動後の新しいチャットでも同じ結果になるか

明示呼び出しには成功するのに通常の依頼では起動しないなら、今回の設定どおりです。反対に通常の依頼でも起動する場合は、同名スキルが別の探索場所にないかも確認してください。

まとめ

Codexのスキルは、.agents/skills/<skill-name>/SKILL.md に必須メタデータと再利用したい手順を書くことで作成できます。description はスキルの発見と選択に重要ですが、暗黙呼び出しを確実に止めるには agents/openai.yaml で allow_implicit_invocation: false を設定します。

まずは小さな手順を1つのスキルへまとめ、$skill-name での明示呼び出しと、スキル名なしの依頼をそれぞれ試してください。意図したときだけ動くことまで確認できれば、安全に自動化の範囲を広げられます。

便利なスキルほど、何を実行するかだけでなく「いつ実行しないか」を設計することが、長く安心して使うための近道です。