Codexを使うたびに、同じ手順やルールを入力していないでしょうか。
「キーワードを分析してSEO記事を書く」「修正後は決まったテストを行う」「調査結果を指定形式でまとめる」。こうした繰り返しの指示は、Skillsにまとめておくと次回から使い回せます。
とはいえ、最初はSKILL.mdに何を書き、どこへ置けばよいのか迷うものです。ここでは最小構成から始めて、保存場所、作成手順、呼び出し方まで順番に見ていきます。コピーして試せるサンプルも用意しました。
Codex Skillsとは
Codex Skillsは、繰り返し使う作業手順や専門知識を、ひとまとまりのワークフローとして保存する仕組みです。毎回長いプロンプトを書き直す代わりに、用途に合ったSkillを呼び出します。
1つのスキルは、基本的に専用フォルダとSKILL.mdで構成します。必要に応じて、参考資料、スクリプト、画像やテンプレートなどの素材も同じフォルダへ追加できます。
my-skill/
├── SKILL.md
├── agents/
│ └── openai.yaml
├── references/
├── scripts/
└── assets/
最初に必要なのはSKILL.mdだけ。ほかのフォルダは、必要になった段階で足せば十分です。
OpenAIの公式マニュアルでは、SkillsはChatGPTデスクトップアプリ、Codex CLI、IDE拡張機能で利用できると説明されています。また、最初からすべての指示を読み込むのではなく、まず名前と説明を確認し、必要と判断したときだけSKILL.md全体を読み込む仕組みです。
この読み込み方は「progressive disclosure」と呼ばれます。Skillが増えても、関係のない長い指示まで最初から抱え込まないための仕組みです。詳しい仕様はOpenAIのBuild skillsで確認できます。
Skillsに向いている作業
では、どんな作業をSkillにすると便利なのか。目安は「同じ説明を何度も入力しているか」です。
- SEO記事の企画、構成、執筆、校正
- コードレビューの確認項目
- テストやビルドの実行手順
- 市場調査の情報源と出力形式
- 社内文書の書式や表現ルール
- 特定サービスを操作するときの確認手順
一度きりの指示なら、通常のプロンプトで十分でしょう。反対に、プロジェクト全体で常に守る規約はAGENTS.md、記事作成やレビューなど必要なときだけ動かす手順はSkills。このように役割を分けると、指示が散らかりません。詳しい使い分けはCLAUDE.mdとSkillsの実践ガイドも参考にしてください。
Codex Skillsの保存場所
保存場所は、「そのSkillをどこまで共有したいか」で決まります。
| 用途 | 保存場所 | 適用範囲 |
|---|---|---|
| プロジェクト専用 | .agents/skills/ |
対象プロジェクト |
| 個人共通 | $HOME/.agents/skills/ |
自分が扱う複数プロジェクト |
| 管理者・システム用 | 管理者またはシステムの所定場所 | 共有環境 |
プロジェクト固有のルールを含むなら、リポジトリ内の.agents/skills/が分かりやすい置き場所です。Gitで管理できるため、チーム内でも同じSkillを共有できます。
たとえば、Weblaboの記事作成スキルは次のように配置できます。
project-root/
└── .agents/
└── skills/
└── weblabo-article-writer/
├── SKILL.md
├── agents/
│ └── openai.yaml
└── references/
└── editorial-policy.md
Codexは現在の作業フォルダからリポジトリのルートへ向かい、.agents/skillsを探します。ここで注意したいのがSkill名の重複です。同じnameが複数あっても内容は自動統合されないので、別の名前を付けておきましょう。
Codex Skillsの作り方
1. 繰り返したい作業を1つ決める
最初から何でもできるSkillを狙うと、いつ呼び出すのか、何を出力するのかがぼやけます。まずは「SEO記事を書く」「Pull Requestをレビューする」など、1つの仕事に絞るのがコツです。
書き始める前に、次の3点だけ決めておきます。
- どのような依頼で使うか
- どの順番で処理するか
- 最終的に何を出力するか
記事作成Skillを例にすると、入力はキーワード、処理は検索意図の分析から校正まで、出力はMarkdown原稿。この程度まで輪郭が見えていれば、SKILL.mdを書き始められます。
2. skill-creatorを呼び出す
ゼロからフォルダ構成を考えるのが面倒なら、skill-creatorに任せる手があります。プロンプトは、たとえば次のように書きます。
$skill-creatorを使って、SEO記事を作成するスキルを作ってください。
プロジェクト内の .agents/skills に保存してください。
用途、発動条件、保存場所まで伝えるのがポイント。必要なフォルダとSKILL.mdの形が決まりやすくなります。
もちろん手作業でも作れます。ただ、初回はskill-creatorを使ったほうが、必須項目の抜けに気づきやすいはずです。
3. SKILL.mdを書く
SKILL.mdの先頭にはYAML frontmatterを置きます。必須なのはnameとdescriptionの2項目。
---
name: seo-article-writer
description: 指定されたキーワードから日本語SEO記事を企画、構成、執筆、校正する。新規記事、リライト、タイトル作成、検索意図分析を依頼されたときに使う。
---
# SEO Article Writer
## ワークフロー
1. 主キーワードと想定読者を確認する。
2. 検索意図を定義する。
3. タイトルと見出し構成を作る。
4. 結論を先に示して本文を書く。
5. 事実、リンク、表記を確認する。
## 出力形式
- Markdownで出力する。
- H2から見出しを始める。
- 最後に公開前の確認事項を付ける。
nameには、小文字の英数字とハイフンを使った短い名前が適しています。
descriptionは、単なる紹介文ではありません。CodexがSkillを自動選択するときの判断材料です。「何をするか」だけでなく、「どんな依頼を受けたときに使うか」まで書くと、呼び出しの精度が上がります。
4. 詳細資料をreferencesへ分ける
記事の編集方針や社内ルールを、すべてSKILL.mdへ詰め込む必要はありません。長くなるほど、Skillを使うたびに読み込む情報も増えてしまいます。
詳細はreferences/へ分け、SKILL.mdには読み込む条件を書きます。
seo-article-writer/
├── SKILL.md
└── references/
├── editorial-policy.md
└── seo-checklist.md
記事を執筆する前に `references/editorial-policy.md` を読む。
公開前に `references/seo-checklist.md` で確認する。
毎回同じコードを使う処理はscripts/へ。成果物にコピーするテンプレートや画像はassets/へ分けます。空のフォルダを先回りして作るより、必要になったものだけ足すほうが見通しもよくなります。
5. 必要に応じてopenai.yamlを追加する
agents/openai.yamlは任意のファイルです。ChatGPTデスクトップアプリに表示する名前や説明、最初のプロンプト、暗黙呼び出しの可否、ツール依存関係などを指定したいときに追加します。
interface:
display_name: "SEO Article Writer"
short_description: "Plan and write practical SEO articles"
default_prompt: "Use $seo-article-writer to draft an SEO article."
policy:
allow_implicit_invocation: true
allow_implicit_invocationをfalseにすると、依頼内容が一致してもCodexが自動では呼び出さず、$seo-article-writerのような明示的な指定が必要になります。
作成したSkillを使う方法
作成したSkillの呼び出し方は2つ。名前を指定する「明示呼び出し」と、Codexに選ばせる「暗黙呼び出し」です。
スキル名を指定して呼び出す
確実に使いたい場面では、プロンプト内でSkill名を指定します。
$seo-article-writerを使って、「Codex Skills 作り方」の記事を書いてください。
Codex CLIやIDE拡張機能では、/skillsからスキルを選ぶ方法や、$を入力して候補を表示する方法もあります。
Codexに自動選択させる
一方、依頼内容がdescriptionと合っていれば、CodexがSkillを自動選択することもあります。
たとえばdescriptionに「SEO記事の新規作成、リライト、タイトル作成で使う」と書かれていれば、次の依頼で候補になります。
「WordPress バックアップ 方法」を主キーワードにして記事を書いてください。
ここでも効いてくるのがdescriptionです。対象作業と発動条件を簡潔に書いておくと、自動選択の精度を上げやすくなります。
Skillsが反映されないときの確認点
保存場所を確認する
Skillが見つからないときは、まず保存場所から確認します。プロジェクト用なら、作業フォルダまたはその上位の.agents/skills/です。Skill名のフォルダ直下にSKILL.mdがあるかも見ておきましょう。
.agents/skills/skill-name/SKILL.md
frontmatterを確認する
ファイル先頭の---、name、description、閉じる---が欠けていないか確認します。
---
name: skill-name
description: このスキルが行うことと、使用する場面を書く。
---
YAMLの記号やインデントが崩れている場合も、正しく認識されない原因になります。
descriptionを具体的にする
「作業を効率化する」だけでは、どの依頼で使えばよいのか判断できません。抽象的な説明は、次のように具体化します。
# 曖昧
description: 記事作成を支援する。
# 具体的
description: 指定キーワードから日本語SEO記事を構成、執筆、校正する。新規記事、リライト、タイトル作成を依頼されたときに使う。
再起動して確認する
Codexはスキルの変更を自動検出します。ただし、更新が表示されない場合はCodexを再起動するよう公式マニュアルで案内されています。
スキルが表示されても期待どおり動かない場合は、実際の依頼文で試し、手順、入力条件、出力形式を具体化してください。
SkillとPluginの違い
Skillは、再利用するワークフローそのもの。プロジェクト内や個人環境で使うだけなら、Skill単体から始められます。
対してPluginは、複数のSkills、コネクター、MCP設定、表示用素材などをまとめて配布する仕組みです。
| 比較項目 | Skill | Plugin |
|---|---|---|
| 主な目的 | 作業手順の再利用 | 機能一式の配布・導入 |
| 最小構成 | SKILL.md |
プラグインマニフェストなど |
| 向いている範囲 | 個人・プロジェクト | チームや利用者への配布 |
| 外部ツール連携 | 依存関係を設定可能 | Skillsやコネクターとまとめて配布可能 |
迷ったら、まずはSkillでワークフローを整える。複数人が簡単に導入できる形で配りたくなった段階で、Plugin化を検討すれば十分です。
よくある質問
SkillsとAGENTS.mdはどう使い分けますか？
AGENTS.mdは、そのプロジェクトで常に守ってほしい規約や確認手順に向いています。Skillsは、記事作成、調査、レビューなど、特定の依頼で呼び出す一連のワークフローに向いています。
SKILL.mdだけでも使えますか？
はい。専用フォルダ内に、nameとdescriptionを含むSKILL.mdがあれば最小構成になります。agents/openai.yaml、references/、scripts/、assets/は必要に応じて追加します。
スキルを更新するたびに再起動が必要ですか？
通常は変更が自動検出されます。更新がSkills一覧や候補へ反映されない場合は、Codexを再起動してください。
チームで共有できますか？
プロジェクトの.agents/skills/へ配置し、リポジトリで管理すれば共有できます。複数のスキルや外部連携をインストール可能な形で配布したい場合は、Plugin化が適しています。
まとめ
Codex Skillsを難しく考える必要はありません。何度も入力している指示、判断基準、作業手順を、次回も使える形で置いておく仕組みです。
まずは繰り返しが多い作業を1つ選び、.agents/skills/スキル名/SKILL.mdへまとめてみてください。descriptionには用途と発動条件を具体的に書き、実際の依頼で試しながら少しずつ直していく。この進め方なら、最初から完璧な設計を目指さずに済みます。
初めて作成する場合は、次のようにskill-creatorへ依頼すると始めやすくなります。
$skill-creatorを使って、〇〇を行うスキルを作ってください。
プロジェクト内の .agents/skills に保存してください。
Codexへ毎回同じ説明を繰り返しているなら、もう題材は決まっています。その指示を、最初のSkillにしてみてください。Codexをこれから使い始める場合は、AIコーディングツールの初心者向けガイドもあわせて確認できます。
コメント