先週、あなたはバイブコーディングで一勝した。やりたいことを言葉で説明し、エージェントが組み上げ、動いて、出荷した。ところが月曜、また同じものが必要になる。同じリリース儀式、同じオンボーディング手順。それなのにあなたは、あの長い段落をまた一からタイプし直している。またしても、だ。
そのギャップを埋めるのが Codex の agent skills です。スキルとは、タスクが合致したときだけエージェントが読み込む再利用可能なプレイブックのこと。つまり、一度苦労して突き止めたやり方が、それ以降はひと言のトリガーへと変わります。OpenAI は Codex 向けに agent skills を出荷しました。これは、Codex が特定のタスクを確実に完了できるよう手助けする、再利用可能な指示の束であり、任意でスクリプトやリソースも合わせて束ねられます。本ガイドでは、agent skills とは何か、そしてフォルダ構成とフロントマターを含む最初の一つの書き方を、コードを書く人もそうでない人も対象に解説します。
agent skill とは実際のところ何か
スキルとは、ひとつのフォルダです。その中に、プレーンな Markdown で書かれた SKILL.md というファイルが一つ入っている。最小構成はこれだけです。
release/
SKILL.md
そしてファイルの中身はこうです。
---
name: release
description: Use when cutting a new release. Bumps the version,
updates the changelog, runs the test suite, drafts release
notes, and tags the commit. Trigger on "ship a release" or
"cut version".
---
# Release playbook
1. Bump the version in package.json (patch unless told otherwise).
2. Move everything under "## Unreleased" in CHANGELOG.md into a
new dated version heading.
3. Run `npm test`. If anything fails, stop and report. Do not tag.
4. Draft release notes from the changelog entries, grouped by
Added / Fixed / Changed.
5. Create an annotated git tag matching the new version.
YAML フロントマターに必須なのは、ちょうど二つのフィールド name と description だけ。本文は、慎重な新入社員に渡す手順書をそのまま順番に書いたものにすぎません。JSON スキーマも、SDK も、ビルドステップもありません。技術者でない創業者でも、5分あれば書けます。
ひとつのワークフローにスキルが収まりきらなくなったら、任意のサブフォルダを足します。実行させたい補助コードは scripts/、参照させたい長めのドキュメントは references/、テンプレートは assets/、そして Codex 固有の設定は agents/openai.yaml へ。どれも、始めるにあたっては必須ではありません。
スキルはプロンプトと(そして AGENTS.md と)どう違うのか
プロンプトは使い捨ての指示です。あなたが打ち込み、エージェントが動き、その言葉は蒸発する。次に同じ結果が欲しくなったとき、あなたは記憶からプロンプトを再構築する。そして必ず少しだけ間違える。人間は、いつもそうだからです。
スキルとは、そのプロンプトを永続的かつ 自己選択的 にしたものです。違いを生むのは、あの description フィールドに尽きます。Codex はインストール済みの全スキルの名前と説明文を最初に読み込みます。あなたがゴールを言葉にすると、Codex はその要求を各説明文と照合し、適切なプレイブックを自ら読み込む。あなたが「リリースを出して」と言えば、Codex は release スキルの説明文にまさにそれが書いてあることに気づき、棚から引き出す。あなたはそのスキルの存在を覚えておく必要すらありません。
スキルは AGENTS.md ではありません。とはいえ、作り手はこの二つを絶え間なく混同します。AGENTS.md は常時オンのプロジェクト文脈、つまり Codex が すべての タスクで読むハウスルールです(「うちは pnpm を使う、npm は決して使わない。テストは __tests__ に置く。/legacy には触るな」)。スキルはオンデマンドで、タスクが合致したときだけ読み込まれます。
- AGENTS.md = エージェントが常に知っているルール。
- スキル = 仕事がそれを必要とするときに棚から引き出すプレイブック。
常に必要なルールを、めったに発火しないスキルに入れれば、エージェントはそれに従いません。逆に、ニッチなリリース儀式を AGENTS.md に入れれば、すべてのタスクが代償を払う文脈を膨らませてしまう。正しいものを、正しいレイヤーへ。
Codex はどうスキルを発火させるのか
スキルを発火させる方法は二つあり、面白いのは二つ目のほうです。
- 明示的な呼び出し。 名前で呼ぶ方法です。
/skillsコマンド、または$skill-nameの構文(例:$release)。どのプレイブックが欲しいか正確に分かっているときに便利です。 - 暗黙的な呼び出し。 ゴールを平易な言葉で説明すると、Codex が説明文から合致するスキルを自動選択します。覚えるべきコマンドはありません。やってほしいことを言えば、適切なプレイブックが自ら読み込まれます。
数十個のスキルをインストールしてもエージェントが遅くならない理由は、段階的開示(progressive disclosure) にあります。Codex は最初、各スキルの名前・説明文・ファイルパスだけを読み、本文は読みません。SKILL.md の全文を読み込むのは、そのスキルを使うと判断したときだけ。このフォーマットを生んだ Anthropic は、段階的開示(progressive disclosure) を、Agent Skills をスケーラブルにする中核の設計原則と呼んでいます。平たく言えば、棚に百個のプレイブックが並んでいても、一つが引き出されるまではほぼコストゼロ、ということです。
スキルは、そのプレイブックが誰のためのものか に対応するスコープに置かれます。
- リポジトリ単位 — プロジェクト内の
.agents/skills。チームのプレイブックを、リポジトリにコミットして、クローンする全員と共有します。 - 個人 —
$HOME/.agents/skills。あらゆるプロジェクトで使える、あなた自身のプレイブック。 - 管理者 / システム全体 —
/etc/codex/skills。管理者がマシン一台あるいはフリート全体に設定する、全社標準のプレイブック。 - 組み込み — Codex 自体に同梱されているスキル。スキルを足場として組み立て、インストールしてくれるヘルパーも含まれます。
Codex と Claude Code は同じ標準の上に乗っている
SKILL.md フォーマットは、特定ベンダーの発明ではなく、ツールを横断するオープンな標準です。Anthropic が Claude Code の Agent Skills でこれを生み出し、クロスプラットフォームの可搬性のためにオープンな形で公開しました。そして Codex も同じ標準の上に構築されています。フロントマター、段階的開示モデル、フォルダ構造はいずれも共有されているため、リリースプレイブックは OpenAI Codex と Claude Code の間でおおむね可搬です。あなたが学んでいるのは標準であって、特定ベンダーへの賭けではありません。そしてスキルはプログラマー専用のものでもなく、ドキュメントやスプレッドシート向けの組み込みスキルは、チャット画面から、ターミナル不要で動きます。
スキルライブラリの実例
盗む価値のあるプレイブックをいくつか。それぞれ、ツールが実際にやれることに根ざしています。
release/— 上で挙げた「バージョン更新 → テスト → タグ付け」の儀式。Codex はすでにリポジトリを読み、ファイルを編集し、テストを走らせ、コミットまでこなすので、このスキルはそのループをワンショットにするだけです。onboarding/— チームのツールをインストール・設定し、各メンバーのエージェントが同じ挙動をするようにします。「うちでのチケットの切り方」や環境セットアップの流儀を Codex に教えるスキルです。branch-review/— サブエージェントのチームを編成するプレイブック。一文が三人の専門家を扇状に展開します。"Review this branch against main. Have pr_explorer map code paths, reviewer find risks, and docs_researcher verify APIs."
この最後の例は、スキルが サブエージェント――Codex が並行して生成し、ひとつの答えに統合できる専門化されたエージェント――とどう組み合わさるかを示しています。つまずきやすい正直な注意点を一つ。Codex は、あなたが明示的に頼んだときだけサブエージェントを生成します。自分から勝手に発火することはありません。
技術者でない創業者のためのビジネス活用例
ここに挙げるどれも、コードを読む必要はありません。
- 一貫したカスタマー返信。 受信メッセージを分類し、自社のブランドボイスで返信文を起こし、人手が必要なものにフラグを立てる
support-triageスキル。すべて Markdown で書けます。 - 週次の投資家向けアップデート。 定型のセクションを引き出し、今週の三つの数字を尋ね、あなたのフォーマットでメールを起草する
investor-updateスキル。 - 新入社員のセットアップ。 初日が毎回まったく同じように進む
onboardingスキル。誰か一人の頭の中だけにある状態を、なくします。
パターンはこうです。同じ説明を二度するものは、すべてスキルの候補です。日本の現場でいえば、入社初日の開発環境セットアップ手順書や、毎月のレポート作成フローのように「結局いつも誰かが口頭で引き継いでいる」作業ほど、スキル化の効果が大きくなります。
安全性とレビューのチェックリスト
スキルは再現性を足しますが、判断力は足しません。信頼する前に、これを走らせてください。
- 「何を」だけでなく「いつ」を語る
descriptionを書く。 暗黙的な呼び出しは、ここに全面的に依存します。曖昧な説明文は、スキルが永遠に発火しないか、間違ったタスクで発火するかのどちらかを招きます。 - 何もかもを一つの巨大な SKILL.md に詰め込まない。 それは段階的開示を台無しにします。手に負えなくなったら、深い内容は参照ファイルに分割してください。
- スキルと AGENTS.md を、それぞれ正しいレイヤーに保つ。 常時オンのルールは AGENTS.md へ、オンデマンドのプレイブックはスキルへ。
- サブエージェントの自動生成を期待しない。 起きません。あなたが頼むのです。スレッド数と深さのデフォルト値にも注意を払ってください。
- 検証ステップをスキルに組み込む。 スキルの再現性は、レビューされていない AI 出力を受け入れてしまうリスクを取り除きはしません。テストコマンドと「失敗したら止まる」指示を、プレイブックに直接焼き込んでください。
- ベンダーロックインを前提にしない。 SKILL.md はオープンで可搬な標準です。一度書けば、ツールをまたいで動きます。
スキルは、バイブコーディングの 後に 来る成熟のステップです。バイブが最初のバージョンを連れてくる。スキルは、検証ゲートを焼き込んだうえで、それを信頼できるものにします。
プレイブックを残しておく
動いたスキルは、Command Center にバージョン付きの一式として保存しておきましょう。一度突き止めたワークフローが、チーム全体で何度でも再利用できる資産に変わります。
出典と参考リンク
- OpenAI Codex: Agent Skills
- OpenAI Codex ドキュメント
- Anthropic: Equipping agents for the real world with Agent Skills
- Anthropic: Claude Code ドキュメント
FAQ
Codex のスキルを書くのに、コードが書けないとダメですか?
いいえ。SKILL.md の必須部分はプレーンな Markdown――name、description、そして番号付きの手順だけです。スクリプトは任意。同僚に向けて分かりやすい手順書が書けるなら、スキルも書けます。
スキルと AGENTS.md は何が違うのですか?
AGENTS.md は Codex が全タスクで読む常時オンの文脈、つまりプロジェクトの常設ルールです。スキルは、タスクが説明文に合致したときだけ読み込まれます。常設ルールは AGENTS.md へ、特定の繰り返しワークフローはスキルへ入れます。
Codex 用に書いたスキルは Claude Code でも動きますか? おおむね、はい。SKILL.md は Anthropic が生み出し、クロスプラットフォームの可搬性のために公開したオープン標準で、Codex はその同じ標準の上に構築されています。フォーマット、フロントマター、段階的開示モデルは共有されているので、よく書かれたプレイブックは、ほとんど、あるいはまったく変更なしに両者を行き来します。
インストール済みなのに、Codex がスキルを使ってくれないのはなぜ?
ほぼ必ず description が原因です。Codex はあなたの要求を説明文と照合してスキルを暗黙的に選ぶため、曖昧なもの(「リリースを手伝う」)は精密なもの(「リリースを切るときに使う。バージョンを更新し、テストを走らせ、タグ付けする」)に負けます。何をするかだけでなく、いつ 発火させるかを明記してください。
Boostor の関連記事: Claude Code のスラッシュコマンドとスキルの設定 · AGENTS.md ベストプラクティス:短く保つ · Claude Code のサブエージェント:いつ・どう使うか