ガイド更新日
Codexのスキルで、いつもの手順を呼び出す
この記事で分かること
Codex 集中講座の第10回。特定の作業で繰り返す手順をスキルにまとめます。SKILL.md、名前、説明文の下書きを作り、AGENTS.mdとの役割の違いを整理します。

目次 読みたいところから
画像を用意するときだけ、長い手順を貼り直している。毎回必要な約束とは違い、その作業のときだけ開ける手順書があると助かります。
スキルは、そうした手順をまとめる仕組みです。SKILL.mdに作業の順番を書き、使う場面が伝わる名前と説明文を付けます。
必要になったときだけ開かれる
仕組みは単純です。公式ドキュメントによれば、Codex は最初、各スキルの名前と説明文と置き場所だけを受け取っています。本文は読んでいません。
作業の内容から「これは使えそうだ」と判断したときに、置き場所を頼りに SKILL.md を読みに行きます。読んだあとは、その中に書かれたファイルを見たり、スクリプトを実行したりします。
つまり、手順書が何ページあっても、使わない回には1行も読まれないということです。AGENTS.md との一番の違いはここにあります。
使うスキルを指定する
Codex CLI と IDE 拡張機能では、/skills または $ から使うスキルを指定できます。下は公式の変更履歴に掲載された CLI の例で、入力欄に $ を入れると、名前と説明文の候補が並んでいます。候補のスキルと画面内のモデル名は掲載例のものです。

左の名前だけで選びにくいときは、右の説明文を読みます。この例なら、plan は複雑な作業の計画、skill-creator はスキルの作成や更新をする候補だと分かります。表示されているのは選択前の一覧です。使うものを指定したあとは、会話や作業ログで SKILL.md を読んだことと、その手順に沿って進んだことを確かめます。
作り方はフォルダ1つと SKILL.md 1つ
スキルはフォルダです。中に SKILL.md を置きます。
.agents/skills/
release-blog/
SKILL.md
check-links.mjs
SKILL.md の先頭には、名前と説明文を書きます。
---
name: release-blog
description: ブログの記事をステージングから本番へ公開する手順。「リリース」「公開して」で使用する。記事の執筆そのものには使わない。
---
# ブログのリリース手順
1. 作業ブランチで npm run validate:content && npm run check:links を通す
2. ...
区切り線ではさまれた部分が設定で、その下が手順の本文です。本文の書き方に決まりはありません。人間が読んで手順どおりに動ける文章なら、そのまま通用します。
名前と説明文が、呼ばれるかどうかを決める
公式ドキュメントによれば、指定しなくても呼ばれるかどうかは説明文との一致で決まります。そのため、範囲と境界がはっきりした簡潔な説明文を書き、主な使いどころと呼び出しの言葉を先頭に置くよう勧めています。本文をどれだけ丁寧に書いても、呼ばれなければ効きません。
説明文に書くべきなのは、どういうときに使い、どういうときに使わないかです。上の例で「記事の執筆そのものには使わない」と書き足しているのは、そのためです。使わない場面を書いておくと、関係ない依頼で誤って呼ばれることが減ります。
BenriWorks で使っているスキルの説明文も、同じ形になっています。
description: Gemini APIで記事・アプリのアイキャッチ用フォトリアル写真を生成し、
public/images配下に配置する。「アイキャッチを生成」「写真を生成」「gen-image」で使用。
要 GEMINI_API_KEY 環境変数と generativelanguage.googleapis.com へのネットワーク許可。
何をするか、どういう言葉で呼ばれるか、何が前提として必要か。この3つが1文ずつ入っています。
置き場所は4種類ある
公式ドキュメントによれば、Codex はリポジトリ、個人、管理者、システムの4か所からスキルを読みます。
リポジトリのスキルは、作業フォルダからリポジトリの根まで遡りながら .agents/skills を探します。チームで共有するものはここに置きます。
個人のスキルは $HOME/.agents/skills です。自分だけの手順、たとえば普段使っている資料の整理のしかたなどは、ここに置けば全部のリポジトリで効きます。
管理者のスキルは /etc/codex/skills で、端末に共通の手順を配るためのものです。システムのスキルは、OpenAI が Codex に同梱するものです。
置き場所の選び方は AGENTS.md と同じ考え方です。チームの作業ならリポジトリ、自分の好みなら個人。リポジトリに置いたものは、他の人が読んで直せます。
スキルに向く作業、向かない作業
向くのは、手順が決まっていて、間違えると面倒で、たまにしかやらない作業です。
3つの条件がそろっていることが大事です。手順が決まっていなければ書けません。間違えても困らないなら書く価値がありません。毎回やる作業なら手が覚えるので、書いても読まれません。
BenriWorks のブログでは、3つのスキルを置いています。日本語の技術文書の文章規範、認知の切り替えを設計する書き方、そしてアイキャッチ画像の生成です。3つとも、記事を書くときにしか使わず、手順が決まっていて、外れると書き直しになります。
向かないのは、判断が要る作業です。「どの設計にするか決める」はスキルにできません。手順として書けるのは、決めたあとの実行部分だけです。
文章より、実行できる形にする
スキルはフォルダなので、SKILL.md の横にスクリプトやテンプレートを置けます。
手順の中で「このスクリプトを実行する」と書いておけば、Codex はそれを実行します。手順を文章で説明するより、この形のほうが結果は安定します。文章は解釈の幅がありますが、スクリプトにはありません。
BenriWorks の画像生成のスキルも、本文に手順を書きつつ、実際の処理はスクリプトを呼ぶ形にしています。
node .agents/skills/gen-image/generate.mjs --prompt "..." --out path
こうしておくと、生成のたびに設定が揺れることがなくなります。揺れてほしくないところをコードにし、揺れてよいところを文章にする。この切り分けが、スキルを書くときの実際的な設計になります。
育て方は AGENTS.md と同じ
作るきっかけも、前回と同じでよいはずです。
同じ手順を3回説明したとき。そして、手順を間違えて事故が起きたとき。どちらも、必要が証明されたあとです。
違うのは、書ける量です。AGENTS.md は短く保つ必要がありますが、スキルは長くて構いません。使う回にしか読まれないからです。手順が20項目あっても、それが本当に20項目必要なら、そのまま書いてください。
手順書にする作業を選ぶ
繰り返している作業を1つ選び、使う場面と手順を短く書き出します。本文のSKILL.mdの例に合わせて、名前、説明文、実施する順番を下書きにしてください。
説明文だけを読んで、いつ使い、何をするかがわかる状態を目指します。
次の回
規約や手順には、最新のログやチケットの状態までは書いておけません。情報がある場所につなぐ方法を用意します。「CodexをMCPで外部サービスにつなぐ」へ進めます。
参照した公式情報
- OpenAI Build skills(外部)(呼び出し方、書式、探索する場所、説明文の書き方。2026年11月時点)
- OpenAI Customization(外部)(必要になったときに手順を読む仕組み。2026年11月時点)
- OpenAI 変更履歴「Agent skills in Codex」(外部)(2025年12月19日の項目に掲載された CLI 選択画面を引用。2026年10月22日確認。撮影日は不明)
- 引用した説明文は BenriWorks のブログリポジトリで実際に使っているスキルのもの
よくある質問
- スキルと AGENTS.md はどう使い分けますか
- 常に効いてほしい規約は AGENTS.md、特定の作業のときだけ要る手順はスキルです。判断の基準は、その内容が作業の10回に1回しか関係しないかどうかです。毎回関係するなら AGENTS.md、たまにしか関係しないならスキルに向きます。
- スキルはどうやって呼び出しますか
- Codex CLI と IDE 拡張機能では、`/skills` または `$` から使うスキルを指定できます。明示的に指定しなくても、依頼がスキルの説明文に合うと Codex が選んで本文を読みに行きます。いつ使うべきかを説明文に書いておくと、選ぶ手がかりになります。
- スクリプトも一緒に置けますか
- 置けます。スキルはフォルダなので、`SKILL.md` の横にスクリプトやテンプレートを入れられます。手順の中で「このスクリプトを実行する」と書いておけば、Codex がそれを実行します。手順を文章で説明するより、実行できる形にしたほうが結果は安定します。
