スキルで、その作業のときだけ開く手順書を用意する

前回の終わりに書いた問題から始めます。AGENTS.md は常に読まれるので、常に関係することしか書けません。

ところが、作業には「そのときだけは全部必要だが、ふだんは邪魔」という手順があります。画像を生成する手順、リリースの段取り、特定の形式のデータを取り込む方法。これらを AGENTS.md に書くと、関係ない依頼のときも毎回読まれることになります。

スキルは、この種類の知識のための置き場所です。

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

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

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

つまり、手順書が何ページあっても、使わない回には1行も読まれないということです。AGENTS.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 で、組織の端末に共通で配るためのものです。

置き場所の選び方は 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項目必要なら、そのまま書いてください。

次の回

AGENTS.md とスキルは、どちらも Codex に「知識」を渡す仕組みでした。

ただ、知識だけでは届かない場所があります。まだ存在しないデータ、外部のサービスの中にある情報。第11回で扱う MCP は、そこへ手を伸ばすための仕組みです。

参照した公式情報

• OpenAI「Build skills」「Customization」「Save workflows as skills」（developers.openai.com/codex、2026年9月時点）
• 引用した説明文は BenriWorks のブログリポジトリで実際に使っているスキルのもの