CodexのAgent Skillsの作り方 — SKILL.md 1枚から始めて「一度成功した手順」を資産にする

Agent Skillsとは — 再利用できる仕事の手順書

Agent Skills とは、Codexが特定の仕事をするときに使う再利用可能なワークフローです。手順そのものだけでなく、必要に応じてスクリプトや参照資料もパッケージに含められます。

なぜCodexのスキルが .codex ではなく .agents というフォルダに置かれるのか、という設計の背景についてはCodexのSkillsはなぜ.agents配下にあるのかで解説しています。本記事は、その置き場所を前提に「では実際にどう作るか」に絞ります。

フォルダ構成 — 必須はSKILL.md 1枚だけ

スキルの実体は1つのフォルダです。中に SKILL.md というファイルを置けば、それがスキルになります。SKILL.md 以外はすべて任意なので、まずは1枚から始めて構いません。

my-skill/
├── SKILL.md          ← 必須：手順とメタデータ（name・description）
├── scripts/          ← 任意：実行できるコード
├── references/       ← 任意：参照用の資料
├── assets/           ← 任意：テンプレート・素材
└── agents/
    └── openai.yaml   ← 任意：見た目の設定と依存関係

scripts references assets agents は決められた名前です。自分で好きな名前を付けるのではなく、この名前のフォルダに入れます。いちばん下の agents/openai.yaml は表示設定や依存関係を指定する上級者向けのファイルで、通常は用意しなくても動きます。

SKILL.mdの書き方 — nameとdescription、その下に手順

SKILL.md は、いちばん上に name（スキルの名前）と description（どんなときに使うか）を書き、その下に手順を書くだけです。

---
name: 請求書作成
description: マネーフォワードで請求書の下書きを作るとき。「請求書作って」「インボイス発行して」などの依頼で使う。
---

# 請求書を作る手順

1. references/請求ルール.md で締め日と消費税の扱いを確認する
2. scripts/集計.py を実行して、稼働時間シートから請求金額を出す
3. assets/請求書雛形.xlsx に 2 の金額を転記する
4. 金額と宛名を読み上げ、送信前に必ず確認を取る

「毎月、稼働時間のシートを見て請求書を作る」という仕事をスキルにすると、フォルダ全体は次のようになります。

請求書作成/
├── SKILL.md              ← 請求書を作る手順。「請求書作って」で使うと書いておく
├── scripts/
│   └── 集計.py           ← 稼働時間シートから請求金額を計算する
├── references/
│   └── 請求ルール.md     ← 締め日・振込期限・消費税の扱いなど、毎回参照するルール
└── assets/
    └── 請求書雛形.xlsx   ← 実際に書き込むテンプレート

どこに何を置くかは、次の基準で分けます。

• SKILL.md — やることの手順そのものと、どんな依頼のときに使うか
• scripts/ — 毎回まったく同じ計算や変換など、コードに任せたほうが速くて正確な処理
• references/ — 判断のもとになるルールや資料。ここに置いておけば、毎回同じ説明を書かずに済む
• assets/ — 書き込む土台になるテンプレートや素材

迷ったら、まず手順を SKILL.md に書くだけで十分です。「同じ説明を何度も書いている」と気づいたら references/ へ、「同じ手作業を毎回繰り返している」と気づいたら scripts/ へ切り出す。この順番で育てていくのがおすすめです。

段階的開示 — 何十個入れても邪魔にならない理由と、その限界

Codexは、最初はすべてのスキルの名前と説明文だけを読み、「これを使う」と決めた1つだけ SKILL.md の全文を読み込みます。この仕組みを段階的開示といい、スキルを何十個入れても本来の作業を邪魔しないのはこのためです。

ただし、この最初に読む一覧は毎回コンテキストに読み込まれ、上限があります。上限はコンテキストウィンドウの2%（分からない場合は8,000文字）です。スキルが多すぎると説明文が短縮され、さらに増えると一覧から省かれて警告が出ます。

作り方の核心 — いきなり作り込まず、1回やり切ってから

ここが本記事でいちばんお伝えしたいところです。いきなりスキルを作り込もうとするのは間違いです。

まだ一度も成功していない手順を先に文章化しても、実際に動かすと抜けや思い違いが出てきます。机上で書いたスキルは、たいてい作り直しになります。

順番は逆です。まずCodexと対話しながら、その仕事を1回いっしょにやり切る。うまくいったら、そのやり方をそのままスキルにしてもらいます。頼み方はこれだけです。

今やった手順をスキル化して

これがいちばん確実です。実際に動いた手順がそのまま元になるので、「書いてみたけれど、やってみたら足りなかった」が起きません。うまくいった1回を、次からは何度でも再現できる形に変えるだけです。

できたスキルはCodexが自動で見つけます。反映されないときはCodexを再起動してください。

使われ方 — 自分で指定する / Codexが自分で選ぶ

使われ方は2通りあります。

• 自分から指定する — ChatGPTでは アットマーク、Codexでは ドル記号 に続けてスキル名を書きます（Codexは /skills で一覧も見られます）
• Codexが自分で選ぶ — 「今月の請求書を作っておいて」と普通に頼むだけで、description に合うスキルがあれば自動で使われます

普段の運用では後者が中心になるため、スキル名を覚えておく必要はありません。だからこそ description が効いてくる、という話につながります。

置き場所 — 自分専用・プロジェクト共通・フォルダ用の3か所

スキルは .agents/skills というフォルダの中に、スキル1つ＝1フォルダで置きます。どこに置くかで「誰が使えるか」が変わります。

~/.agents/skills/              ← 自分専用：どのプロジェクトでも使える
└── 議事録作成/

my-project/
├── .agents/skills/            ← プロジェクト共通：この案件に関わる全員が使える
│   └── 請求書作成/
│
└── 営業/
    └── .agents/skills/        ← このフォルダ用：営業の作業だけで使える
        └── 提案書作成/

Codexは、起動したフォルダから上へたどりながら .agents/skills を探し、見つかったスキルを全部集めて1つの一覧にします。

スキルのベストプラクティス4点

有用なスキルを作る4ステップ

ここまでの内容を、実際の進め方として4ステップにまとめます。例として「問い合わせメールへの返信下書きを作る」という仕事を、最後まで通して見ていきます。

組織で使うなら — 「属人化した手順」を出す装置として使う

スキルの本当の効果は、AIが速くなることではありません。担当者の頭の中にしかなかった手順が、読める形でファイルに出てくることです。これまでマニュアル化が進まなかった業務でも、「1回やり切ってスキル化して」を繰り返すだけで手順書が溜まっていきます。

だからこそ、組織で始めるときはプロジェクト側の .agents/skills に置いて共有するところまでを設計に入れてください。自分専用の場所にだけ置いていると、せっかく言語化した手順が個人の中に閉じてしまい、属人化の解消につながりません。

当社のCodex研修・導入伴走支援では、貴社の実業務を1つ選んで、その場で一緒にやり切り、そのままスキル化するところまでをワークとして行っています。持ち帰って作るのではなく、研修の中で最初の1本ができている状態を目指しています。