CodexのSkillsを使って、プロンプト運用を効率化する
こんにちは、たっきーです。
Nextat でも Codex などのAIエージェントを本格的に業務へ取り入れていこう、という動きが進んでいます。
実際に Codex を使っていると、こんな場面ありませんか？
- 実装レビューの指示で毎回ほぼ同じことを書いている
- 設計レビューの観点をコピペして投げている
- テストケースを書いてほしい時に、正常系・異常系・境界値の説明をしている
毎回同じプロンプトを書くの、正直もったいないですよね。
こうした “繰り返し発生する指示” は、実は Skills を使うと自動化できます。
Skillsって何？
以下が Codex のSkillsについての公式ドキュメントです。
https://github.com/openai/codex/blob/main/docs/skills.md
Skills をひとことで言うと...
「特定のタスクを実行するための、専門知識を持たせる仕組み」です。
簡単に特徴を挙げると...
~/.codex/skills/<skill-name>/SKILL.md にファイルを作成するだけで、自動で読み込まれる- 常時読み込まれるのはメタデータのみ
- 本文は Codex が必要なときだけ参照される
などがあります。
この後、さらに詳しく見ていきましょう。
Skillsの書き方
Skill ファイルのディレクトリ構造は以下のとおりです。
~/.codex/skills/<skill-name>/SKILL.md
ファイルの中身は以下の形式にします。
---
name: skill-name
description: スキルの説明（いつ・何のために使うか）
---
# 本文
name / description までは「Codexに読んでもらうメタ情報」を、
本文は「ふだんプロンプトで書いていた内容」をそのまま書くイメージです。
Skills の特徴
メタデータだけ常時読み込み、本文は Codex が“必要なときに自動で選択”する
今回の記事で一番伝えたい重要ポイントです。
Codex が起動時に保持するのは、markdownファイルのうち
namedescription
これらの メタデータのみ です。
そして本文は、メタデータからCodex 自身がタスク内容を判断し、「このスキルが必要だな」と思ったときだけに参照します。
だから Skills は...
- コンテキストを圧迫しない
- ユーザーによる明示的な呼び出しが不要
という性質を持ちます。
カスタムコマンドとの違い
ここは誤解されがちな部分ですが、非常に重要です。
カスタムコマンドでも “共通化” はできます。
/prompts:review/prompts:summary/prompts:lint-doc
など、共通で使うタスクを、markdownファイルで定義し、手動で呼び出す方法です。
これは 「毎回同じタスクを人間が選んで実行する」 という仕組みです。
ちなみに、前回の記事ではカスタムコマンドについて解説しています。
https://nextat.co.jp/staff/archives/393
カスタムコマンドは同じ「共通化」でも、Skills とは役割が異なります。
| 機能 | どう使われる？ | 誰が選択する？ |
| カスタムコマンド | 明示的に /prompts:xxx と呼び出す |
人間が選ぶ |
| Skills | Codex がタスクを見て自動的に参照する | LLM が選ぶ |
つまり Skills は、固有の「判断基準」や「観点」を Codex に“常備させる”機構なのに対し、
カスタムコマンドは、「やりたい処理」を明示的に呼び出す仕組みです。
どちらも便利ですが、目的が違います。
- 処理をパッケージ化したい → Skills
- 特定作業をのみを実行したい → カスタムコマンド
という使い分けになるかと思います。
- 設計レビューの観点をそろえたい
- コードレビューコメントの観点・フォーマットを統一したい
- テストケース（正常系/異常系/境界値）の洗い出しを楽にしたい
- バグ報告フォーマットを統一したい
Skillsの使用例
実際にそのまま使える Skill の例をいくつか載せます。例1: 設計レビュー用 Skill
~/.codex/skills/design-review/SKILL.md
---
name: design-review
description: 仕様書・設計書をレビューするときの共通観点を Codex に持たせるスキル
---
# 本文
## Purpose
仕様書や設計書をレビューし、不足・曖昧さ・リスクを体系的に洗い出す。
## Instructions
以下の観点でレビューコメントを出すこと
- 要件の完全性（抜けているユースケースはないか）
- データ構造・API仕様の整合性
- エッジケースの扱い
- パフォーマンス・セキュリティの懸念
- 依存関係の妥当性
- コメントは箇条書きで、日本語で簡潔に書くこと。
- 不足している点は「未記載」「曖昧」と明示すること。
## Examples
Input:
このAPI設計書をレビューしてください: ...
Output:
- 認証エラー時のレスポンス形式が未記載です。
- ページング用のクエリパラメータの上限値が不明です。
- タイムアウト時の挙動が定義されていません。
以後、「この設計をレビューして」と投げるだけで、毎回同じ観点でレビューしてくれるようになります。例2: コードレビュー用 Skill
「Issue / Suggestion 形式でコメントしてほしい」などのルールも、Skill にしておくと分かりやすいです。~/.codex/skills/code-review/SKILL.md
---
name: code-review
description: コードレビューの観点とコメント形式を統一するスキル
---
# 本文
## Purpose
コードの可読性・保守性・設計品質をレビューする。
## Instructions
- 指摘は必ず「Issue」「Suggestion」に分けて書くこと。
- バグ探しよりも、以下の観点を優先すること
- 責務分離（単一責務になっているか）
- 命名（目的が伝わる名前か）
- 複雑度（ネストや分岐が過剰でないか）
- 重複コード（DRY違反がないか）
- コメントは日本語で簡潔に書き、感情的な表現は避けること。
## Examples
Input:
このクラスのコードレビューをお願いします: ...
Output:
Issue: updateUser メソッドが 300 行あり、複数の責務を持っています。
Suggestion: バリデーション、永続化、イベント発行の処理をそれぞれ別メソッド／クラスに分割してください。
簡単に、質の高いセルフレビューが出来るようになります。まとめ
Skills は、
「毎回プロンプトで説明していたことを、Codex が自動で判断してくれる状態にする仕組み」
と言えます。
- コンテキストを圧迫せず
- 呼び出し忘れもなく
- 固有の観点や基準を適用してくれて
- レビューやテスト設計の品質もブレなくなる
つまり、Skills を作っておくことで、Codex がどんどん “強い相棒” に育っていきます。
もちろん、カスタムコマンドも便利ですが、
判断基準そのものを任せたい場面では Skills が効果的 です。
「同じ説明を毎回書いてる気がする…」
と思った瞬間が、Skill を作るベストタイミングです！
まずは 1 個だけでも作ってみて、Codex がどう変わるか体験してみてください。
