Codex Skills を使い始めると、最初は何でも skill にしたくなります。レビュー、記事作成、デプロイ、調査、リリースノート作成。ですが、ここを雑に広げるとすぐ壊れます。description が曖昧で誤発火する、SKILL.md が肥大化して誰も直せない、scripts が増えて保守コストだけ上がる。plugin にすべきものまで skill に押し込むと、配布境界も崩れます。この記事は、Codex skill を「便利メモ」ではなく再利用できるワークフロー部品として設計したい人向けです。
2026年4月時点の OpenAI 公式 docs では、skill は instructions、resources、optional scripts を束ねる仕組みで、Codex はまず metadata だけを見て必要時に SKILL.md 本体を読む progressive disclosure で扱います。つまり skill の本体は長文そのものではなく、いつ呼ばれるかを決める metadata と、呼ばれた後に迷わない手順です。plugin と何が違うのかから整理したい場合は Codex Plugins と Skills の違い を先に読むと、外部接続と再利用ワークフローの境界がつかみやすいです。Codex 全体の運用像を先に掴みたいなら Codex Automations 実践ガイド、並列作業との境界を見たいなら Codex 複数エージェント運用ガイド、常時読み込む指示の置き場を整理したいなら CLAUDE.md の書き方 設計パターン集 も合わせて読むとつながります。そもそも「何を固定し、何を変動部分として残すか」という上位の制御設計から入りたい場合は Harness Engineering 入門 がハブになります。
先に結論: skill は「知識」ではなく「再現したい仕事の型」に寄せる
私が skill を作る基準はかなり単純です。
- 同じ種類の依頼が繰り返し来る
- 毎回同じ順番で確認したい
- 出力形式をある程度固定したい
- AGENTS.md に常駐させるには重い
逆に、skill にしないものも明確です。
- プロジェクト全体で常に守るルール
- その場限りの一回性タスク
- 人間の判断が毎回大きく変わる抽象作業
- 外部スクリプトを足すほどでもない軽いメモ
ここを曖昧にすると、AGENTS.md、skill、automation、subagent が全部同じことを言い始めます。私は次の役割分担で切るのが一番安定しました。
| 置き場 | 役割 |
|---|---|
AGENTS.md | 常に必要な前提、禁止事項、コマンド、レビュー条件 |
| skill | 特定タスクでだけ使う再利用ワークフロー |
| automation | スケジュール付きで回す定期仕事 |
| subagent | main 会話から切り出す独立コンテキスト |
たとえば「OpenAI 関連の仕様確認では Docs MCP を最優先する」は skill化しやすいです。一方、「この repo では pnpm run build を通す」は AGENTS.md に置くべきです。前者は特定タスク向け、後者は常時ルールだからです。この切り分けの考え方は、より上位の設計論として Harness Engineering 入門 ともつながります。
まず description を設計する。本文より先です
OpenAI の docs では、Codex は skill の name、description、path などの metadata を先に見て、必要なときだけ SKILL.md を読みます。つまり自動起動の精度は本文ではなく、かなりの部分が description で決まります。
悪い description:
ブログ作業を助ける skill開発を効率化する万能 skillレビューや実装や調査に使える
これでは守備範囲が広すぎます。誤発火しやすいし、使う側も何を期待すればよいか分かりません。
私なら、description には最低限この3つを入れます。
- いつ使うか
- 何を返すか
- いつ使わないか
たとえばこうです。
---
name: blog-seo-refresh
description: 既存ブログ記事のtitle・description・内部リンクを見直すときに使う。新規記事執筆や実装変更には使わない。
---この1行が曖昧だと、本文でどれだけ丁寧に手順を書いても運用はぶれます。逆に description が締まっている skill は、instruction-only でも十分に機能します。
instruction-only で始め、scripts は「毎回同じ入出力が必要になってから」足す
OpenAI の docs でも、skill 作成は built-in creator を使うか、まず instruction-only で始める流れが基本です。ここはその通りで、最初から scripts を足すべきではありません。
私の基準では、scripts を追加するのは次のどちらかに当てはまるときだけです。
- 手作業だと毎回ぶれる
- 外部ツールや定型変換を確実に実行したい
たとえば、Markdown frontmatter を一括検査する、llms.txt 系の更新を走らせる、特定 API から定型データを引く。こういう処理は scripts に寄せる価値があります。
逆に、記事レビュー、設計レビュー、競合整理のような判断の中心が文章と基準にある仕事は instruction-only のままの方が保守しやすいです。scripts を入れると、skill ではなく小さなソフトウェアになります。そこまで行くなら、保守責任まで含めて本当に必要かを考えるべきです。
SKILL.md を太らせる前に references/ と assets/ に逃がす
公式 docs では、skill ディレクトリには references/、assets/、scripts/、agents/openai.yaml を置けます。ここで重要なのは、説明と資料を分けることです。
SKILL.md: 実行手順と判断基準references/: 長い仕様書、API 定義、運用ルールassets/: テンプレート、雛形、素材scripts/: 決まった処理
悪い skill は、全部を SKILL.md に埋め込みます。すると trigger 判定に必要ない長文まで毎回読み込まれ、修正もしづらくなります。
私なら SKILL.md は次の4ブロックで収めます。
- 何の仕事か
- 実行手順
- 出力形式
- やってはいけないこと
それ以上の背景説明や仕様サンプルは references/ に退避させます。これは CLAUDE.md を短く保つのと同じで、instruction の核と参照資料を混ぜない方が運用しやすいからです。
暗黙起動を許すかは、便利さではなく事故率で決める
Codex の docs では、skill は explicit invocation と implicit invocation の両方で使えます。また agents/openai.yaml の allow_implicit_invocation: false で暗黙起動を止められます。
ここはかなり大事です。私は次の基準で決めます。
implicit でよい skill
- タスク名と守備範囲がはっきりしている
- 誤発火しても大きな害がない
- 説明を毎回書くより自動起動の利便性が勝つ
例:
- OpenAI docs を読む
- コードレビュー観点を追加する
- ブログの frontmatter を点検する
explicit のみにする skill
- 実行コストが高い
- 強い書き込みや外部アクセスを伴う
- 誤発火すると混乱する
- 出力がかなり特殊
例:
- デプロイ
- 請求データ整理
- 大量ファイルの一括更新
- 画像生成や外部 API 呼び出し
便利だから全部 implicit に寄せるのは雑です。skill は「自動で使われる instruction」なので、誤発火した瞬間に運用負債になります。
repo skill と plugin 配布は、再利用範囲で切る
OpenAI の docs では、skill は repo、user、admin、system など複数スコープで置けます。また再利用配布したい場合は plugin に束ねる前提が整理されています。
私は次のように切ります。
repo 配下に置くもの
- その repository 固有の運用手順
- チーム共通でレビューしたい workflow
- コマンドやディレクトリ構造への依存が強いもの
user 配下に置くもの
- どの repo でも使う個人用 skill
- 自分だけの調査補助
- まだチーム共有するほど固まっていない試作
plugin にするもの
- 複数 repo で再利用したい
- app 連携や MCP 依存も一緒に配りたい
- チーム外にも配布したい
この順番を逆にすると失敗します。最初から plugin 化すると、まだ揺れている skill を配布単位で固定してしまうからです。まず repo で育てて、再利用が見えたら plugin に切り出す方が現実的です。
私ならこう書く: 最初の skill の型
例えば、記事作成前の重複チェックと内部リンク候補出しを再利用したいなら、私はこんな骨格から始めます。
---
name: blog-topic-check
description: 新規ブログ記事のテーマ選定時に使う。既存記事との検索意図重複、内部リンク候補、keyword-plan上の役割を確認する。本文執筆や画像作成には使わない。
---
# Goal
新規記事テーマが既存記事と競合しないことを確認し、内部リンク先を提案する。
# Steps
1. `data/seo/keyword-plan.md` を確認する
2. `src/content/blog/` の既存記事を検索意図ベースで棚卸しする
3. 重複候補と差分を整理する
4. 内部リンク候補を 2〜4 本出す
# Output
- 採用テーマ
- 重複候補
- 差別化ポイント
- 内部リンク候補
# Do Not
- 新規記事を勝手に作らない
- build や deploy を走らせないこの程度でも十分です。大事なのは豪華さではなく、呼んだときに毎回同じ粒度で返るかです。
skill 設計で一番効くのは「何をしないか」を書くこと
skill を増やしていくと、だんだん instruction が前向きなことばかりになります。しかし運用では、やることよりやらないことの方が効きます。
私は skill ごとに少なくとも次のどれかを書きます。
- 編集禁止の範囲
- 実行禁止のコマンド
- 対象外のタスク
- 出力の上限
たとえば reviewer skill なら「修正しない」、リサーチ skill なら「推測で断定しない」、SEO skill なら「本文を全面改稿しない」といった具合です。これがあるだけで、skill 同士の責務衝突がかなり減ります。
まとめ
Codex Skills の設計で重要なのは、機能を盛ることではありません。どの仕事を再利用単位として固定するかを決めることです。
私なら次の順で進めます。
- まず
AGENTS.mdに置くべき常時ルールを除く - 同じ依頼が3回以上来た仕事だけ skill 候補にする
- instruction-only で始める
descriptionを先に磨く- 長文は
references/に逃がす - 安定してから scripts と plugin 化を考える
この順番なら、skill は「便利そうだが誰も使わない飾り」ではなく、実際に再利用されるワークフローになります。
次に読む順番としては、skill を含む全体制御の考え方を俯瞰したいなら Harness Engineering 入門、background 運用へ広げたいなら Codex Automations 実践ガイド、並列タスクの安全な分割まで見たいなら Codex 複数エージェント運用ガイド に進むと、そのまま運用設計までつながります。