Agent Skillsの作り方｜5分で始める7つの実践設計ルール

結論: Agent Skillsは、よく使うプロンプトを保存するだけの機能ではありません。「いつ使うか」「どの順で進めるか」「どこで止めるか」を、AIエージェントが再利用できる仕事の単位にする仕組みです。最初の1本なら、nameとdescriptionを含むSKILL.mdだけで始められます。

この記事の要点:

• 最小構成は1フォルダと1つのSKILL.md。外部連携やスクリプトは後から足せます
• 自然文で呼び出せるかは、本文よりdescriptionの具体性に左右されます
• 作った後は、明示呼び出し・自然文・近接する非対象の3パターンで確認します

こんな人向け: AIエージェントへ同じ説明を何度もしている方、社内の定型業務を再現可能にしたい方、Claude CodeやCodexで仕事の手順を共有したい方。

読み終えると: 最小のスキルを1本作り、必要なフォルダを追加し、発火しない原因まで自分で切り分けられます。

Agent Skillsで何ができるのか

Agent Skillsは、指示、参考資料、スクリプト、テンプレートなどを1つのフォルダへまとめ、AIエージェントが必要なときに読み込む形式です。中心になるのはSKILL.mdで、Agent Skillsの仕様ではnameとdescriptionが必須項目として定義されています。

たとえば「公開前の記事をファクトチェックする」という仕事なら、次の内容を1つのスキルにできます。

• どんな依頼で起動するか
• 記事から何を抽出するか
• どの順番で一次情報と照合するか
• 未確認情報をどう表示するか
• どの形式で結果を返すか
• 公開や外部送信の前にどこで止まるか

一度この手順を定義すると、毎回長い指示を貼り直さなくても、同じ入口から同じ品質基準で作業を始められます。

プロンプト集との違い

プロンプト集は、人が適切な文面を探して会話へ貼り付けます。スキルは、AI側がdescriptionを見て「この仕事にはこの手順が必要だ」と判断し、本文を読みます。

文面の雛形だけでなく、入力、作業順、出力、確認が必要な条件まで持てる点も違います。単発の質問を上手にするならプロンプト、繰り返す仕事の進め方を安定させるならスキルが向いています。

AGENTS.mdやCLAUDE.mdとの違い

AGENTS.mdやCLAUDE.mdは、その作業場所で常に守るルールに向いています。命名規則、禁止操作、参照すべき正本など、どの仕事にも効く内容を置きます。

一方、スキルは特定の仕事でだけ読みます。月次レポートの作り方をすべての会話へ常駐させる必要はありません。全体ルールはAGENTS.md、仕事別の手順はSKILL.mdと分けると、更新場所が分かりやすくなります。

MCPとの違い

MCPは外部のデータや機能へ接続する仕組みです。スキルは、その道具をどの順で使い、何を確認し、どの状態まで進めるかを定義します。

外部接続がない仕事なら、スキルだけで完結します。MCPをつないでも手順が曖昧なら、出力は安定しません。両方を使う場合も、接続と手順を分けて考えるのが基本です。

最初にスキル化する仕事の選び方

最初から大きな自動化を選ぶと、入力も例外も増え、どこで失敗したか分からなくなります。まずは次の4条件に合う仕事を1つ選びます。

同じ説明を繰り返している

週に何度も「最初にこの資料を読んで、次にこの形式でまとめて」と説明している仕事は候補です。説明が安定しているほど、手順へ切り出しやすくなります。

入力と成果物が言える

「いい感じに営業を手伝う」では範囲が広すぎます。「案件メールを入力し、顧客へ送る前の紹介文を出力する」のように、入口と出口を1文で言える仕事を選びます。

正解を確認できる

出力を見ても良し悪しが分からない仕事は、改善もできません。必須項目、形式、計算結果、参照元など、完了を確認できる条件がある仕事から始めます。

失敗しても外部へ影響しない

最初の1本は、下書き作成やローカル集計のように、失敗しても公開・送信・削除が起きない仕事が安全です。外部反映が必要な場合は、下書きと公開を別ステップに分けます。

5分で最小のSKILL.mdを作る

ここでは「記事の数字と出典を確認する」スキルを例にします。必要なのは、フォルダを作り、SKILL.mdを置くことだけです。

最初から自動化を広げず、1つの仕事を最小構成で作って3種類の入力を試します。

1. フォルダを作る

リポジトリで共有する場合は、たとえば次のように置きます。

.agents/skills/article-fact-check/
└── SKILL.md

スキル名は小文字・数字・ハイフンで表し、フォルダ名とnameを一致させます。名前だけで仕事が推測できるarticle-fact-checkのような表現が扱いやすいです。

2. nameとdescriptionを書く

---
name: article-fact-check
description: ブログ記事の数字・固有名詞・外部主張を出典と照合し、未確認箇所を一覧化する。記事の公開前レビュー、ファクトチェック、出典確認を依頼されたときに使う。
---

descriptionは紹介文ではなく、スキルを選ぶための判断材料です。「何をするか」に加え、「どんな依頼で使うか」まで書きます。

悪い例はブログを助けるです。記事の執筆、校正、SEO、入稿のどれを指すか分かりません。良い例は、対象が「公開前の記事」、作業が「数字・固有名詞・外部主張の照合」、出力が「未確認箇所の一覧」と分かります。

3. 入力・手順・出力・停止条件を書く

frontmatterの下へ、作業手順を置きます。

# 記事ファクトチェック

## 入力
- ユーザーが指定した記事ファイルまたは本文

## 手順
1. 対象記事を最後まで読む
2. 数字、日付、製品名、第三者の主張を抽出する
3. 各主張を一次情報と照合する
4. 確認済み／主張段階／未確認に分類する
5. 修正が必要な箇所を行番号つきで返す

## 停止条件
- 対象記事が特定できない場合は確認する
- 外部公開や本文の上書きは、明示依頼がなければ行わない

長い背景説明より、モデルが次に何をするかを動詞で書くのがポイントです。「十分に確認する」ではなく、「主張を抽出する」「一次情報と照合する」「3段階に分類する」まで分解します。

フォルダを4つの役割に分ける

最小のスキルが動いた後、必要に応じてreferences/、scripts/、assets/を足します。最初から空のフォルダを作る必要はありません。

SKILL.mdへすべて詰め込まず、判断、資料、処理、素材の役割で分けます。

SKILL.mdは判断と進行に絞る

SKILL.mdには、いつ使うか、何を読むか、どの順で動くか、どこで止まるかを置きます。モデルが仕事を進めるための目次兼手順書です。

仕様では500行未満が推奨されていますが、499行を目標にする意味はありません。短くても判断材料が足りなければ動かず、長くても分岐が明確なら必要な場合があります。行数ではなく「発動時に毎回読む必要があるか」で判断します。

referencesは必要なときだけ読む資料

制度全文、長い文体ガイド、記事型ごとのテンプレート、製品別の設定表はreferences/へ分けます。本文には「料金比較の場合はreferences/pricing.mdを読む」のように、読む条件を書きます。

article-fact-check/
├── SKILL.md
└── references/
    ├── source-priority.md
    └── claim-labels.md

参照先はスキルルートからの相対パスにします。個人のMacにしか存在しない絶対パスを書くと、別の環境で壊れます。

scriptsは同じ入力から同じ結果を出す処理

集計、並べ替え、ファイル変換、スキーマ検証のような決定的処理はscripts/に向いています。モデルへ毎回計算させるより、コードで結果を確定し、その意味をモデルが説明する方が再現しやすくなります。

スクリプトには入力、依存関係、終了コード、失敗時のメッセージを持たせます。実行できなかったときに、無理に推測値を作らない停止条件も必要です。

assetsは成果物へ使う素材

文書テンプレート、画像、定型JSONなど、最終成果物へコピー・変換して使うものはassets/に置きます。モデルが理解するための説明資料はreferences/、出力へ使う素材はassets/と分けます。

必要な情報だけ読む3段階の設計

Agent Skillsは、すべてのファイルを常時読み込む前提ではありません。仕様では、情報を段階的に開くProgressive Disclosureが示されています。

最初は発見に必要な情報だけを見せ、仕事が始まってから必要な資料や処理を選びます。

第1段階: nameとdescription

起動時は、スキルを発見するためのメタデータが使われます。ここで対象とトリガーが分からなければ、本文が良くても選ばれません。

第2段階: SKILL.md本文

スキルが選ばれたときに、作業手順を読みます。共通の確認順、出力形式、停止条件など、その仕事で毎回必要な内容を置きます。

第3段階: references・scripts・assets

分岐に応じて必要なものだけ読み、実行し、使います。国内向けと海外向けの規約が別なら、両方を本文へ貼るのではなく、対象地域を判断して該当資料だけ読みます。

この分離によって、スキルを追加しやすくなるだけでなく、失敗箇所も追いやすくなります。発火しないなら第1段階、手順を間違えるなら第2段階、資料選択や計算が違うなら第3段階を見直せます。

失敗を減らす7つの設計ルール

1. descriptionを発火テストとして書く

descriptionには対象作業、入力、主な出力、利用場面を入れます。発火させたい言い回しだけでなく、発火させたくない近接依頼も考えます。

たとえば「経歴書を評価する」と「経歴書を顧客提出用に整える」は、同じPDFを使っても仕事が違います。説明文で評価と編集の境界を分けます。

2. 1スキル1ジョブにする

「採用全部」「マーケ全部」のような大きい単位は、入力も完了条件も増えます。面談記録、候補者評価、通知文の作成は分けた方が、どこで失敗したかを追えます。

ただし、1ステップごとに細切れにする必要もありません。1つの入力から、確認可能な1つの成果物まで完了できる単位を基本にします。

3. 本文と長い資料を分ける

SKILL.mdには判断と進行を残し、詳細な規約や例はreferences/へ移します。参照ファイルが増えたら、本文に「どの条件でどれを読むか」を必ず書きます。リンクだけを並べると、結局すべて読む動きになりがちです。

4. 決定的な処理はscriptsへ移す

計算、変換、検証はコードへ寄せます。ただし、何でもスクリプトにするのではなく、「同じ入力なら同じ出力であるべき処理」を対象にします。文章の要約や論点整理はモデル、合計値や形式検証はスクリプト、という分け方が実用的です。

5. 外部反映の直前で止める

「成果物を作る」と「公開・送信・削除する」は別の権限です。下書きまでは自動、公開は承認後という状態を手順に書きます。

確認を最初にまとめて取るより、実際の内容が見えた直前で止める方が、承認する側も判断できます。メール、SNS、CMS、顧客データの更新では特に重要です。

6. 相対パスと代替経路を書く

参照先はスキルルートから相対指定します。外部サービスや特定ツールが必要なら、利用できない場合の動きも書きます。

たとえば「CMS一覧を取得する。連携がなければ未確認と明記する」とすれば、接続できない環境で存在しないデータを作る事故を防げます。

7. 成功例より境界例を試す

スキル名をそのまま呼ぶテストだけでは、自動発火の品質は分かりません。次の3種類を試します。

1. 明示呼び出し: $article-fact-check この原稿を確認して
2. 暗黙呼び出し: 公開前に数字と出典だけ見て
3. 近接する非対象: この記事の言い回しを自然に直して

1と2では発火し、3では文章レビューなど別の処理へ回るのが期待動作です。明示呼び出しだけ成功するならdescription、発火後の作業が違うなら本文を見直します。

Claude CodeとCodexで共有する方法

Agent Skillsの基本形式は共通化できます。ただし、同じSKILL.mdを読めることと、同じ権限・ツールで実行できることは別です。

正本を1か所に置く

Codexはリポジトリ階層の.agents/skillsを探索します。リポジトリ全体で使うなら、ルート直下へ置くと共有しやすくなります。

Claude Code側で.claude/skillsが必要な構成では、同じファイルをコピーするより、正本へのシンボリックリンクを検討できます。ただし、利用中のバージョンとOSでリンク先を認識するかは実機で確認します。

.agents/skills/        ← 正本
.claude/skills         ← 正本へのリンク、またはホスト用配置

既に多数のスキルを運用している場合の考え方は、Claude Codeのスキルを業務へ広げた記録も参考になります。

共通部分とホスト固有部分を分ける

allowed-toolsはAgent Skills仕様上Experimentalです。一方の環境で動く指定が、別のホストでも同じ意味になるとは限りません。本文ではツール名だけでなく、目的と代替経路を書きます。

Claude CodeとCodexの役割分担や外部接続まで含めた例は、2つのAIコーディングエージェントを併用する設計で詳しく整理しています。

【要注意】発火しないときの診断表

期待どおりに動かないときは、モデルの性能だけを疑わず、発見、読込、実行、外部反映のどこで止まったかを分けます。

症状ごとに直す場所を分けると、SKILL.mdへ説明を足し続ける状態を避けられます。

発火しない

明示呼び出しでは動くのに自然文で動かない場合は、まずdescriptionを確認します。

❌ description: ブログを助ける ⭕ 対象、作業、出力、利用場面を具体的に書く

Codexではスキル数が多い場合、初期一覧のコンテキスト予算に合わせて説明が短縮・省略される可能性が公式ドキュメントに示されています。重要な対象語と行動語は前方へ置きます。

読みすぎて遅い

全制度、全テンプレート、全事例をSKILL.mdへ入れると、発動時に関係ない資料まで読みます。判断手順だけを残し、分岐ごとの説明をreferences/へ移します。

500行未満は上限の目安であり、長くする目標ではありません。毎回使わない説明が増えた時点で分離を考えます。

結果が毎回ぶれる

合計、並び順、JSON形式、ファイル名のように正解が決まる箇所をモデルへ任せていないか確認します。決定的にしたい部分をscripts/へ移し、モデルは入力の解釈と結果の説明を担当させます。

勝手に送る・公開する

「最後まで完了する」だけでは、下書きと外部反映の境界がありません。状態を「作成済み」「確認待ち」「公開済み」に分け、外部へ影響する直前に明示承認を必要とします。

Claude Codeでは動くがCodexでは動かない

最初にname、description、フォルダ名、相対参照を確認します。その後、利用可能なツール、ネットワーク、ファイル権限、MCP設定を比べます。ファイル形式が共通でも、実行環境の能力は自動では揃いません。

1週間で定着させるチェックリスト

スキルは、書いた時点で完成する設定ファイルではありません。実際の依頼で外れ方を確認し、仕事の境界を育てます。

今日: 1本だけ作る

• [ ] 同じ説明を繰り返している仕事を1つ選ぶ
• [ ] 入力と成果物を1文で書く
• [ ] nameとdescriptionを置く
• [ ] 手順を5ステップ前後に分ける
• [ ] 外部送信・公開・削除の停止条件を書く

明日: 3種類の入力を試す

• [ ] スキル名を明示して呼ぶ
• [ ] 自然な依頼文で呼ぶ
• [ ] 似ているが対象外の依頼をする
• [ ] 発火しないのか、発火後に間違えるのかを分ける

1週間後: 必要なものだけ追加する

• [ ] 繰り返し参照した資料をreferences/へ移す
• [ ] 同じ計算・変換をscripts/へ移す
• [ ] 成果物の素材をassets/へ移す
• [ ] 使われなかった説明や分岐を削る
• [ ] 別環境でも相対パスと権限を確認する

最初から大きな仕組みを作る必要はありません。まず1本を小さく動かし、3つの入力で外れ方を見る方が、直すべき場所を早く見つけられます。

まとめ

Agent Skillsを作るときは、長いプロンプトを書く前に、仕事の入口と出口を決めます。最小構成はSKILL.mdだけです。動いた後で、長い資料をreferences/、決定的な処理をscripts/、成果物の素材をassets/へ分けます。

重要なのは、スキル数を増やすことではありません。自然な依頼で正しい手順が選ばれ、確認可能な成果物が出て、外部反映の前で安全に止まることです。

最初の1本には、今日か今週また説明する予定の仕事を選んでください。5分で最小形を作り、明示・自然文・近接非対象の3テストを通すところまでが、実用的なスタートです。

参考・出典

• Specification - Agent Skills — Agent Skills（参照日: 2026-08-16）
• Build skills — OpenAI公式ドキュメント（参照日: 2026-08-16）
• Equipping agents for the real world with Agent Skills — Anthropic（参照日: 2026-08-16）
• anthropics/skills — Anthropic公式GitHubリポジトリ（参照日: 2026-08-16）
• skills/skill-creator/SKILL.md — Anthropic公式スキル作成ガイド（参照日: 2026-08-16）
• Claude Code assistant not aware of available skills #9716 — GitHub Issue、未検証の利用者報告（参照日: 2026-08-16）