Claude Code・Codexのスキルの作り方｜SKILL.mdの書き方とSkill Creatorの使い方

Claude Code（Anthropic）とCodex（OpenAI）は、ターミナルから自然言語で指示を出し、コードを読み書きさせるコーディングエージェントです。どちらも「スキル（Agent Skills）」を渡すと、レビューやテスト、文書作成といった決まった作業を、毎回同じ品質でこなせるようになります。出回っているスキルを探して入れる方法は、Claude Code・Codexのおすすめスキル｜探し方・選び方・入れ方と定番スキル集で整理しています。本記事は、その先の「繰り返す作業を、自分のスキルとして作る」ところに踏み込みます。

作り方そのものは難しくありません。スキルの実体は、先頭にnameとdescriptionを書いたSKILL.mdという1枚のテキストだからです。実際には、どの作業をスキルにするかの選び方、狙った場面で自動的に発火させる書き方、そして作ったあとの育て方で差がつきます。固有名は公式ドキュメントで確認したものに絞っています。

01.結論：小さく手書きし、使いながら育てる

スキルづくりでつまずくのは、たいてい最初に大きく設計しすぎたときです。テキスト1枚から始めて、実際の作業で呼ばれるかを確かめながら直すほうが、結果的に早く形になります。以降、この結論を分解して、メリット→最小構成→descriptionの設計→作り方6ステップ→スキルを作るスキル→置き場所→チーム運用の順に説明します。

02.スキルを作ると何が良いのか｜4つのメリット

作り方の前に、スキルを自作すると何が良くなるのかを押さえておきます。出来合いのスキルを入れるだけでも便利ですが、自分の繰り返し作業をスキルにすると、次の4つの効果が積み上がります。

1つ目は、毎回の説明が要らなくなることです。「リリースノートを書くときは、この観点で差分を確認して、この順で書いて――」と毎回書いていた説明が、一度SKILL.mdに固定すれば不要になります。指示の出し方のうまさに左右されず、頼むだけで毎回同じ段取りが走るので、結果の品質が安定します。

2つ目は自動発火です。エージェントは、いま取り組んでいる作業の内容と各スキルの説明文（description）を照らし合わせ、関係しそうなときだけそのスキルを読み込みます。「あのスキルを使おう」と意識しなくても、関係する作業を頼むだけで適用されるため、プロンプトの定型文のように毎回貼り付ける必要がありません。仕組みと発火させる書き方は、後半で詳しく扱います。

3つ目は、使うほど育つことです。スキルはただのテキストなので、使って気づいた不足をすぐ直せます。「ここで発火してほしかった」「この手順が足りない」という気づきを反映するたびに、次回から確実に効きます。この積み重ねが、一度きりの効率化との違いです。

そして4つ目が、チームへの広げやすさです。リポジトリに置いてコミットすれば、変更履歴が残り、プルリクエストでレビューでき、チーム全員が同じ手順を共有できます。個人の効率化として始めたスキルが、そのまま組織の標準になっていきます。

スキルづくりの位置づけを、Anthropicは「Moving up the stack」という整理で説明しています（Equipping agents for the real world with Agent Skills）。Models（プロセッサ）の上にAgents（OS）が乗り、その上にSkills（アプリケーション）が乗る――つまりスキルの自作は、エージェントというOSの上で動く自社専用のアプリケーションを増やしていくことにあたります。プロセッサやOSは買ってくるものでも、業務に効くアプリケーションは自分たちで足していけます。

03.スキルの最小構成をおさらい（SKILL.md・name・description）

次に、スキルの最小構成を確認します。スキルは1つのフォルダで、中身は次のとおりです。本体はSKILL.mdという1枚のテキストで、これだけでもスキルとして成立します。

release-notes/            ── フォルダ名 = スキル名
├── SKILL.md              ── 本体（先頭に name / description、続けて手順）
├── reference.md          ── 任意：詳しい参照資料（必要なときだけ読まれる）
└── scripts/
    └── collect_diff.sh   ── 任意：補助スクリプト

SKILL.mdの先頭には、YAMLフロントマターと呼ばれる短い設定を書きます。最低限必要なのはname（スキルの名前。フォルダ名と一致させる）とdescription（何をするか・どんなときに使うか）の2つだけです。その下に、ふだん指示で伝えている手順をそのまま書きます。

---
name: release-notes
description: リリースノートを書くときに使う。直前のタグからの差分を
  ユーザー向けの変更点に整理し、決まった見出し構成で日本語の
  リリースノートを作成する。「リリースノート」「変更点をまとめて」
  と頼まれたときに発火する。
---

# リリースノートの作り方

1. 直前のリリースタグからの差分を確認する。
2. 内部的な修正と、ユーザーに関係する変更を分ける。
3. 「新機能 / 改善 / 修正」の見出しで、利用者目線の言葉に直す。
4. 末尾に既知の注意点があれば加える。

フロントマターに書ける項目は、nameとdescriptionのほかにもあります。Claude Codeで使える主な項目を挙げます（全項目の一覧は公式ドキュメントAgent Skillsを参照。Codexが読み取るのはこのうちnameとdescriptionです）。

スキルが何かという仕組み――SKILL.mdとYAML、段階的開示、MCPとの役割分担、階層モデルまで――は、Agent Skills｜専門知識をフォルダで配るエージェントの作り方と構成で整理しています。基礎から確認したい場合は、あわせてご覧ください。本記事は、この最小構成を前提に「効くスキルをどう書くか」へ進みます。

04.自動で発火する仕組みと、発火させるdescriptionの書き方

スキルは、入れただけでは効きません。数が増えるほど存在を忘れ、呼び出されないまま「入れっぱなし」になるスキルが出てきます。狙った場面で自動的に発火（関係する作業のときだけ中身が読み込まれること）してくれれば、作った本人が忘れていても、関係する作業のたびに勝手に効きます。そして、descriptionの書き方が発火の精度を左右します。

常に読むのはnameとdescriptionだけ（段階的開示）

スキルを大量に用意しても重くならないのは、「段階的開示」という設計があるためです。エージェントが起動時に常に読むのは、各スキルのnameとdescriptionだけ（1スキルあたりごくわずかな分量）。本文や参照資料は、その作業に関係すると判断されたときに初めて読み込まれます。公式の技術ブログ（Equipping agents for the real world with Agent Skills）でも、この段階的な読み込みが中心的な考え方として説明されています。

この流れでは②が発火の可否を決めます。照合の材料はdescriptionなので、ここが曖昧だと、関係する作業が来ても発火しません。逆に具体的に書けば、利用者が何も指定しなくても自動で呼ばれます。

発火するdescriptionの型：何を×いつ×具体語

発火するdescriptionには、共通の型があります。「何をするか」だけでなく「どんなときに使うか（発火条件）」と、その作業で実際に出てくる具体的な言葉を入れることです。エージェントは利用者の依頼文と照合するので、依頼に現れそうな単語が入っているほど当たりやすくなります。

範囲を絞ることも、発火の安定に効きます。1つのスキルに用途を詰め込むと、どの作業で呼ぶべきか判断しづらくなり、似たスキルどうしで発火が競合します。1スキル1目的を守り、用途が増えたらスキルを分けるのが原則です。

手動でも呼べる（スキル名を指定する）

この自動発火は、両ツールとも既定で有効です。Claude Codeは既定で利用者とClaudeの双方がスキルを呼び出せる設定になっており、Codexも依頼内容がdescriptionに合致するとスキルを自動選択します（allow_implicit_invocationの既定値はtrue）。そのうえで、確実に使いたい場面では手動でも呼べます。Claude Codeでは/スキル名で直接実行でき、Codexでは指示文の中で$スキル名と書いてスキルを指定できます（それぞれ公式ドキュメントAgent Skills・Codex skillsに記載）。新しく作ったスキルが自動では呼ばれないときも、まず手動で動かして手順を確かめ、そのうえでdescriptionを調整して自動発火に寄せていく、という進め方ができます。なお、Claude Codeはスキルのフォルダを監視しているので、既存スキルの編集は同じセッションの中でそのまま反映されます。

05.スキルの作り方｜最小構成から作る6ステップ

ここまでを踏まえ、実際にスキルを1つ作る手順を6ステップに整理します。最初から大きく作らず、よく繰り返す作業を1つ選んで小さく始めるのがコツです。

特にステップ6は見落としがちです。スキルは一度書いて終わりではなく、実際に使うと「ここで発火してほしいのに呼ばれない」「手順のこの部分が足りない」と必ず気づきます。使いながら直す前提で、小さく出して回すほうが、最初から作り込むより早く実用に届きます。

06.スキルを作るスキル｜Skill Creator・$skill-creator・Superpowers

スキルづくり自体を補助する「スキルを作るスキル」が、Claude CodeにもCodexにも公式・コミュニティの両方で用意されています。土台はあくまで手書きですが、雛形づくりやdescriptionの調整はこれらに任せると速くなります。まず選択肢を並べます。

Claude Code：公式のSkill Creator

Anthropic公式のSkill Creatorは、雛形を出して終わりの道具ではありません。対話で意図を聞き取ってSKILL.mdの下書きを作り、テスト用のプロンプトを実行してスキルあり・なしの結果を比べ、「発火してほしい依頼・してほしくない依頼」を並べてdescriptionの当たり精度まで最適化するところまで面倒を見ます。スキルの効き目を分けるdescriptionの調整を、道具側で詰めてくれる存在です。本体はanthropics/skillsで公開されており、Claude Codeへは公式マーケットプレイス（claude-plugins-official）から/plugin install skill-creator@claude-plugins-officialでプラグインとして導入できます。

Codex：組み込みの$skill-creatorとRecord & Replay

Codex側は、スキル作成の補助が本体に組み込まれています（公式ドキュメントCodex skills）。$skill-creatorを呼ぶと、何をするスキルか・いつ発火すべきか・スクリプトを含めるかを対話で確認しながらスキルを生成できます。もうひとつがRecord & Replayで、実際の作業を録画すると、Codexが手順を検査して再利用可能なスキルに起こしてくれます。毎回やっているのに手順をうまく言語化できない作業こそ、実演から作るこの機能に向いています。出来上がったスキルの導入には$skill-installerも用意されています。

フレームワーク：Superpowersのスキル作成スキル

Superpowers（obra/superpowers）は、個別のスキルというより「計画から実装、レビューまでの開発の型」をまとめて配るスキル集で、新しいスキルの作成・既存スキルの編集・デプロイ前の動作確認を担うwriting-skillsという「スキルを書くためのスキル」を含みます。

07.Claude CodeとCodexの両方で使う｜置き場所の違いと横断配布

作ったスキルは、エージェントが決まったフォルダから読み込みます。ファイルの書式はClaude CodeとCodexで共通なので中身は流用できますが、読み込む場所は両者で異なります。まずClaude Codeの置き場所です（公式ドキュメントAgent Skillsを参照）。

Codex側は、リポジトリ単位の.agents/skillsや利用者単位の~/.agents/skillsを読み込みます（公式ドキュメントCodex skillsを参照。Codexのスキル対応は新しめの機能で、置き場所は今後変わる可能性があります）。書式が同じでも、片方に置けば両方に反映される公式の共有の仕組みがあるわけではないので、同じスキルを両ツールで使うときは、それぞれの読み込み先に届ける必要があります。

Claude Code                        Codex
─────────────────────              ─────────────────────
~/.claude/skills/                  ~/.agents/skills/        ← 利用者ごと
└── release-notes/                 └── release-notes/
    └── SKILL.md                       └── SKILL.md

.claude/skills/                    .agents/skills/          ← リポジトリ内
└── release-notes/                 └── release-notes/
    └── SKILL.md                       └── SKILL.md

※ フォルダの中身は共通。置き場所だけ両ツールの読み込み先に合わせる

なお、このSKILL.md形式はAgent Skillsというオープンな標準になっており、Claude CodeとCodexに限らず対応ツールが広がっています。ここで作ったスキルは、チームが将来別のエージェントに乗り換えても持ち運べる資産になります。

Claude CodeとCodexそのものの違いや使い分けは、Claude CodeとCodexの比較とワークフローで整理しています。あわせてご覧ください。

08.チームに広げて定着させる運用

自分用に作って育てたスキルは、リポジトリに置くだけでそのままチームの標準にできます。個人のスキルがチームに定着するまでの流れは、次の循環で回します。

スキルはコードと同じくレビューと棚卸しの対象にします。リポジトリで共有し、レビューで質を保ち、使われ方を見て足し引きします。この回し方ができていると、良い手順が自然に全員へ広がり、ブレていた作業の品質がそろっていきます。

どのスキルを入れて、どう探し、安全に運用するかという「入れる側」の整理は、Claude Code・Codexのおすすめスキル｜探し方・選び方・入れ方と定番スキル集にまとめています。自作と外部スキルの併用を考えるときは、あわせてご覧ください。

09.よくある質問（FAQ）

10.スキルづくりを自社の開発・運用に落とし込む

スキルづくりは、よく繰り返す作業を小さく手書きし、descriptionで狙いどおり呼び出させ、使いながら育てる、という3段で回せます。エディタひとつで今日から始められて、まず自分の繰り返し作業が楽になり、リポジトリに置けばそのままチームの標準になっていきます。この積み上げが、スキルを自作するいちばんの価値です。

とはいえ、どの作業をスキルにすべきか、発火条件をどう書き分けるか、Claude CodeとCodexをまたいでどう配り、どこまで自動実行を許すかは、チームの開発フローや扱うデータによって変わります。弊社では、AIをフル活用した開発・運用の体制づくりを、課題の洗い出しからスキルの設計・自作、チームへの定着までを伴走して支援しています。Claude CodeやCodexのスキルを自社にどう根づかせるかでお悩みの場合は、お気軽にお問い合わせください。