Codex カスタムプロンプトの使い方とSkills移行

カスタムプロンプトとは — ~/.codex/prompts に置く再利用可能な指示

カスタムプロンプトは、繰り返し使う指示を Markdown ファイルにまとめ、Codex のスラッシュコマンドとして呼び出せるようにする機能だ。ファイルは利用者ごとのホーム配下、具体的には ~/.codex/prompts ディレクトリに直接置く。サブディレクトリではなくこの場所に置いたものが、スラッシュメニューに候補として並ぶ(出典: https://developers.openai.com/codex/custom-prompts )。

呼び出し方はシンプルで、/prompts:名前 と入力する。たとえば draftpr.md というファイルを置けば /prompts:draftpr で実行できる。Codex CLI と Codex の IDE 拡張の両方から同じように使える点も実務上は便利だ。重要なのは、カスタムプロンプトが手元の Codex ホームに保存される個人的な仕掛けであり、リポジトリを通じてチームに共有されるものではないという性質だ。あくまで「自分の環境で、明示的に呼び出したときだけ効く」前提で考えると、用途の見当がつけやすい。

なお、Codex CLI にはこのカスタムプロンプトとは別に、/init や /status、/compact、/review といった組み込みのスラッシュコマンドが多数用意されている(出典: https://developers.openai.com/codex/cli/slash-commands )。カスタムプロンプトは、こうした標準コマンドに「自分専用のコマンド」を足していく拡張口だと捉えると位置づけがわかりやすい。

カスタムプロンプトの作り方 — Markdown と front matter

作成手順そのものは難しくない。テキストエディタで Markdown ファイルを 1 つ用意し、所定のディレクトリに保存するだけで、すぐスラッシュメニューに現れる。ここでは最小構成から、説明文や引数のヒントを付ける段階までを順に示す。front matter は省略してもよいが、書いておくとメニュー上で用途が一目で分かるようになり、複数のプロンプトを使い分けるときに役立つ。

Step 1: ~/.codex/prompts に Markdown ファイルを置く

まず ~/.codex/prompts ディレクトリを用意し、その直下に Markdown ファイルを作る。ファイル名がそのままコマンド名になるため、draftpr.md のように用途が分かる短い名前を付けるとよい。本文には Codex に実行してほしい指示を、普段プロンプトとして打っている文章のまま書けばよい。保存した時点でスラッシュメニューに反映される。

Step 2: front matter に description と argument-hint を書く

ファイル先頭の YAML front matter には、メニューに表示する説明を description として、期待する引数を argument-hint として書ける。argument-hint は KEY=<value> の形式で「何を渡せばよいか」を示すためのもので、後述するプレースホルダと組み合わせて使う。説明文があると、コマンド名の下に用途が表示されるため、時間が経って中身を忘れても選びやすくなる。

Step 3: スラッシュメニューから呼び出す

実行するときは Codex で / を押してスラッシュメニューを開き、prompts: に続けてファイル名を入力する。引数があるプロンプトなら、コマンドの後ろに値を空白区切りや KEY=value の形で添える。これで毎回同じ長い指示を打ち直すことなく、登録済みのテンプレートを呼び出して作業を始められる。

引数を渡す — 位置指定と名前付きのプレースホルダ

カスタムプロンプトの本領は、呼び出すたびに中身を少しずつ差し替えられる点にある。本文にプレースホルダを埋め込んでおくと、コマンド実行時に渡した値がそこへ展開される。展開の種類は公式ドキュメントで次のように整理されている(出典: https://developers.openai.com/codex/custom-prompts )。用途に応じて位置指定と名前付きを使い分けると、テンプレートの再利用性が高まる。

1. 位置指定プレースホルダ: $1 から $9 までが、コマンドの後ろに付けた空白区切りの引数を順番に受け取る。すべての引数をまとめて使いたいときは $ARGUMENTS を置く。
2. 名前付きプレースホルダ: $FILE や $TICKET_ID のような大文字の名前を本文に置き、呼び出し時に KEY=value の形で値を渡す。値に空白を含む場合は FOCUS="loading state" のように引用符で囲む。
3. リテラルのドル記号: 文中に $ をそのまま出したいときは $$ と書くと、ドル記号 1 つに展開される。

実際の呼び出しは、たとえば /prompts:draftpr FILES="path1 path2" PR_TITLE="My title" のように書く。FILES と PR_TITLE がそれぞれ対応する名前付きプレースホルダへ入り、本文のテンプレートが埋まった状態で Codex に渡る。レビュー対象のファイルや課題番号など、毎回変わる部分だけを引数にしておけば、本文の指示は固定したまま使い回せる。

非推奨化のお知らせ — カスタムプロンプトから Skills へ

ここが本記事で最も押さえておきたい変更点だ。OpenAI は公式ドキュメントでカスタムプロンプトを非推奨(deprecated)と明記し、再利用可能な指示には Skills を使うよう案内している(出典: https://developers.openai.com/codex/custom-prompts )。既存のカスタムプロンプトは引き続き動作し、~/.codex/prompts 配下のファイルをスラッシュメニューから呼び出せるが、新しく整える場合は Skills を起点に考えるのが公式の推奨に沿う。

理由は機能の性質の違いにある。カスタムプロンプトは「明示的に呼び出さないと効かない」「手元のホームにしか置けずリポジトリで共有されない」という制約がある。これに対して Skills は、リポジトリを通じてチームで共有でき、しかも利用者が明示的に呼び出さなくても、Codex 側がタスクの内容に応じて暗黙的に選んで適用できる(出典: https://developers.openai.com/codex/skills )。「共有したい」あるいは「自分で毎回指定しなくても効かせたい」というニーズは、カスタムプロンプトでは満たしにくく、Skills が引き受ける形になっている。

Skills は SKILL.md という Markdown ファイルを中心としたディレクトリで構成され、front matter に name と「いつ使うか」を表す description を書く。配置場所は、リポジトリ直下の .agents/skills、利用者ホームの $HOME/.agents/skills、システム共通の場所などを Codex が走査する仕組みだ(出典: https://developers.openai.com/codex/skills )。呼び出しは /skills コマンドや $ での指定でも、Codex による暗黙的な選択でも行える。最初は名前と説明だけを読み込み、選ばれたときに本文を展開する段階的な読み込みにより、無駄な文脈消費を抑える設計になっている。

カスタムプロンプトと Skills の使い分け

では、どちらを選べばよいのか。判断軸は「共有するか」「明示的に呼ぶか」の 2 点に集約できる。チームで同じ手順をそろえたい、リポジトリに含めて誰の環境でも効くようにしたい、あるいは自分で毎回指定しなくても状況に応じて適用してほしい——こうした要件があるなら Skills が適している。逆に、ごく個人的な定型操作で、自分が明示的に呼び出すときだけ効けば十分なら、既存のカスタムプロンプトでも当面は事足りる。

ただし、これから新しく整備するなら Skills へ寄せておくのが無難だ。非推奨という位置づけである以上、今後の機能追加や改善は Skills 側に集まると考えるのが自然で、長く使う仕掛けほど推奨側に置いておく価値が大きい。既存のカスタムプロンプトを抱えている場合は、まず利用頻度の高いものから、name と description、本文を持つ Skills の形へ書き直していくと移行を進めやすい。引数を多用していたプロンプトは、Skills の本文に「どんな入力を前提にどう動くか」を言葉で記述し直すと、暗黙的な呼び出しにもなじみやすくなる。

移行はいちどに全部を作り替える必要はない。まずは 1 つだけ Skills へ置き換えて、/skills から呼び出せること、そして説明文に沿って Codex が選んでくれることを確かめる。動作の手応えをつかんだうえで、よく使うものから順に移していけば、非推奨の影響を受けずに済む。

まとめ — 今ある定型指示を、共有できる形へ

カスタムプロンプトは、~/.codex/prompts に Markdown を置き、/prompts:名前 で呼び出すだけの手軽な拡張だ。front matter に説明と引数のヒントを書き、$1〜$9 や $ARGUMENTS、名前付きの $FILE などのプレースホルダを使えば、同じテンプレートを少しずつ変えて再利用できる。ここまでが、まず押さえておきたい基本になる。

そのうえで意識したいのが、OpenAI がカスタムプロンプトを非推奨とし、Skills を推奨しているという事実だ。リポジトリで共有でき、Codex が暗黙的にも選べる Skills は、チーム運用や「指定しなくても効かせたい」用途に向く。個人的で明示的に呼ぶだけの定型操作はカスタムプロンプトでも当面動くが、新規に整えるものや長く使うものは Skills へ寄せておくと安心だ。次に確認すべきは、手元でよく使っている指示を 1 つ Skills の形へ置き換え、/skills から呼び出して動作を確かめることだ。そこから順に移していけば、無理なく推奨側へ移行できる。