本文へ移動
BenriWorks LabBenriWorks トップ

ガイド更新日

Codexのスキルで、いつもの手順を呼び出す

この記事で分かること

Codex 集中講座の第10回。特定の作業で繰り返す手順をスキルにまとめます。SKILL.md、名前、説明文の下書きを作り、AGENTS.mdとの役割の違いを整理します。

書類のファイルが並んだ棚の前で、1冊を開いてこちらを向いている女性
目次 読みたいところから

画像を用意するときだけ、長い手順を貼り直している。毎回必要な約束とは違い、その作業のときだけ開ける手順書があると助かります。

スキルは、そうした手順をまとめる仕組みです。SKILL.mdに作業の順番を書き、使う場面が伝わる名前と説明文を付けます。

必要になったときだけ開かれる

仕組みは単純です。公式ドキュメントによれば、Codex は最初、各スキルの名前と説明文と置き場所だけを受け取っています。本文は読んでいません。

作業の内容から「これは使えそうだ」と判断したときに、置き場所を頼りに SKILL.md を読みに行きます。読んだあとは、その中に書かれたファイルを見たり、スクリプトを実行したりします。

つまり、手順書が何ページあっても、使わない回には1行も読まれないということです。AGENTS.md との一番の違いはここにあります。

スキルの読み込みの仕組みを示した図。最初は名前と説明文と場所だけが渡され、作業に関係すると判断されたときにSKILL.mdの本文と同梱ファイルが読み込まれる二段階が矢印で示されている
最初に渡るのは名前と説明文だけ。本文は必要になってから

使うスキルを指定する

Codex CLI と IDE 拡張機能では、/skills または $ から使うスキルを指定できます。下は公式の変更履歴に掲載された CLI の例で、入力欄に $ を入れると、名前と説明文の候補が並んでいます。候補のスキルと画面内のモデル名は掲載例のものです。

Codex CLIの入力欄にドル記号が入り、linear、plan、skill-creator、skill-installerの名前と説明文が候補に表示されている
公式変更履歴の CLI 画面例。入力欄の $ と、その下に並ぶスキル名と説明文を見る。2026年10月22日確認出典:OpenAI 変更履歴「Agent skills in Codex」(外部サイト)画像を拡大(別タブ)

左の名前だけで選びにくいときは、右の説明文を読みます。この例なら、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 のブログリポジトリで実際に使っているスキルのもの

READ NEXT

次はこれを読む

Codex 集中講座の次の回へ

CodexをMCPで外部サービスにつなぐ

Codex 集中講座の第11回。チケットやログなど、その時点の情報を取得するMCPを扱います。接続方式、認証、必要な権限を整理し、取りたい情報から接続を考えます。

続きを読む →
複数のサービスの画面を並べたディスプレイの前で、こちらを向いている男性

よくある質問

スキルと AGENTS.md はどう使い分けますか
常に効いてほしい規約は AGENTS.md、特定の作業のときだけ要る手順はスキルです。判断の基準は、その内容が作業の10回に1回しか関係しないかどうかです。毎回関係するなら AGENTS.md、たまにしか関係しないならスキルに向きます。
スキルはどうやって呼び出しますか
Codex CLI と IDE 拡張機能では、`/skills` または `$` から使うスキルを指定できます。明示的に指定しなくても、依頼がスキルの説明文に合うと Codex が選んで本文を読みに行きます。いつ使うべきかを説明文に書いておくと、選ぶ手がかりになります。
スクリプトも一緒に置けますか
置けます。スキルはフォルダなので、`SKILL.md` の横にスクリプトやテンプレートを入れられます。手順の中で「このスクリプトを実行する」と書いておけば、Codex がそれを実行します。手順を文章で説明するより、実行できる形にしたほうが結果は安定します。