はじめに
「毎回同じ説明をClaudeに書いている気がする」
「PDF処理やExcel整形の手順を、毎回プロンプトに貼るのは大変」
「社内ノウハウを、Claudeにうまく再利用させたい」
そんなときに役立つのが Claude Agent Skills です。
Agent Skillsは、Claudeに専門知識入りの作業フォルダを持たせるような仕組みです。
単なる長いプロンプトではありません。
SKILL.md、追加資料、テンプレート、スクリプトなどをひとまとまりにして、Claudeが必要なときだけ読み込んで使えるようにします。
1. Claude Agent Skillsとは？
Claude Agent Skillsは、Claudeの機能を拡張するためのモジュール型の仕組みです。
各Skillには、次のようなものをまとめられます。
- Claudeに読ませる指示
- Skillを識別するメタデータ
- 作業手順
- ベストプラクティス
- 参照資料
- テンプレート
- 実行可能なスクリプト
ユーザーの依頼に対して、Claudeは「この依頼にはどのSkillが関係しそうか」を判断し、必要なSkillを自動的に使います。
初心者向けに一言でいうと、Agent Skillsは次のようなものです。
Claudeに、業務別・用途別の「専門知識入り作業フォルダ」を持たせる仕組み
たとえば、PDF処理用Skillを用意しておけば、毎回「PDFを読むときはこのライブラリを使って、表はこう抽出して、フォーム入力はこうして……」と説明する必要が減ります。
Claudeが依頼内容を見て、必要に応じてそのSkillを開いて使ってくれるわけです。
2. 全体アーキテクチャ
Claude Agent Skillsの全体像は、次の流れで考えるとわかりやすいです。
- ユーザーが依頼する
- Claudeが依頼内容を理解する
- Skillのメタデータを見て、関連するSkillを判断する
- 仮想マシン上のSkillディレクトリにアクセスする
- 必要なファイルだけを読む
- 必要ならスクリプトを実行する
- 要約・抽出・変換・成果物生成などの結果を返す
ポイントは、Skillがファイルシステムベースであることです。
Skillは、仮想マシン上のディレクトリとして存在します。
Claudeは必要に応じて、そのディレクトリ内のファイルを読みます。場合によっては、bash経由でスクリプトを実行します。
たとえば、PDF処理用のSkillなら、次のような構成になります。
pdf-skill/
├── SKILL.md
├── FORMS.md
├── REFERENCE.md
└── scripts/
└── fill_form.py
それぞれの役割は、ざっくり次の通りです。
-
SKILL.md- Skillの中心です。
- メタデータ、基本手順、使い方を書きます。
-
FORMS.md- フォーム入力など、特定作業の詳細手順を書きます。
-
REFERENCE.md- 詳細な仕様、APIリファレンス、補足資料を書きます。
-
scripts/fill_form.py- Claudeが必要に応じてbash経由で実行する補助スクリプトです。
このように、Agent Skillsは「プロンプトだけで頑張る仕組み」ではありません。
指示、資料、コードをひとつのパッケージとして持てるのが強みです。
3. なぜプロンプトだけではなくSkillが必要なのか
普通のプロンプトでも、Claudeに詳しい手順を伝えることはできます。
たとえば、次のような長いプロンプトを書けば、PDF処理の手順を教えることはできます。
あなたはPDF処理の専門家です。
PDFからテキストを抽出するときは...
表を抽出するときは...
フォーム入力をするときは...
エラーが出た場合は...
ただし、この方法には弱点があります。
- 毎回同じ説明を書く必要がある
- 長くなるとプロンプトが読みづらい
- 使わない情報まで毎回コンテキストに入る
- チームや複数会話で再利用しにくい
- スクリプトやテンプレートを自然に同梱しにくい
Agent Skillsは、この問題を解決するための仕組みです。
よく使う知識や手順をSkillとしてまとめておけば、Claudeは必要なときだけそれを開いて使えます。
4. 3段階の読み込みモデル
Agent Skillsの一番おもしろいところは、全部を最初から読まないことです。
Skillは、必要な情報を段階的に読み込みます。
公式ドキュメントでは、この仕組みが「段階的な情報開示」として説明されています。
初心者向けには、次の3段階で理解するとわかりやすいです。
レベル1：メタデータ
レベル1は、常に読み込まれるメタデータです。
SKILL.mdの先頭には、YAML front matterと呼ばれる情報を書きます。
---
name: pdf-processing
description: PDFファイルからテキストや表を抽出し、要約・フォーム入力・文書結合を行うときに使う
---
Claudeは、このnameとdescriptionを見て、次のことを知ります。
- どんなSkillが存在するのか
- そのSkillは何をするのか
- どんな依頼のときに使うべきなのか
ここで大事なのは、descriptionです。
Claudeは、この説明を頼りに「この依頼にはこのSkillが合いそうだ」と判断します。
悪い例は、次のような説明です。
---
name: pdf-processing
description: PDFのSkillです
---
これだと、何ができるのか、いつ使うべきなのかが曖昧です。
良い例は、次のような説明です。
---
name: pdf-processing
description: PDFファイルからテキストや表を抽出し、要約、フォーム入力、文書結合を行うときに使う
---
これなら、Claudeが判断しやすくなります。
レベル2：指示
レベル2は、Skillがトリガーされたときに読み込まれる指示です。
たとえば、ユーザーが次のように依頼したとします。
このPDFからテキストを抽出して、要約してください。
このときClaudeは、PDF処理Skillのdescriptionを見て、「この依頼にはPDF処理Skillが必要そうだ」と判断します。
そこで、SKILL.mdの本文を読み込みます。
SKILL.mdの本文には、次のような情報を書きます。
- 作業手順
- ベストプラクティス
- 注意点
- 具体例
- 出力形式
- エラー時の対応
例としては、次のような構成です。
# PDF Processing
## Instructions
1. PDFからテキストを抽出する
2. 表がある場合は表として構造化する
3. 重要な見出しを抽出する
4. 最後に要約を作る
## Output Format
- 概要
- 抽出した重要ポイント
- 表データ
- 注意点
ここで初めて、Skillの詳しい手順がコンテキストに入ります。
つまり、すべてのSkillの詳細を最初から読むのではなく、関連したSkillだけを読むということです。
レベル3：リソースとコード
レベル3は、必要に応じて読み込まれる追加資料やコードです。
たとえば、SKILL.mdの中に次のような記述があったとします。
フォーム入力が必要な場合は、FORMS.mdを参照してください。
入力値の検証には scripts/validate_form.py を使ってください。
この場合、Claudeは必要になったときだけFORMS.mdを読み、必要に応じてスクリプトを実行します。
ここがとても重要です。
スクリプトを使う場合、Claudeはスクリプトのコード全文を毎回コンテキストに入れるわけではありません。
bash経由で実行し、その出力だけを利用します。
つまり、次のようなメリットがあります。
- 大きな参照資料をSkillに含められる
- 使わないファイルはトークンを消費しにくい
- コード処理は実行結果だけを利用できる
- 手順と実行ロジックを分離できる
5. Agent Skillsが効率的な理由
Agent Skillsが効率的なのは、必要な情報だけを段階的に開くからです。
普通の長いプロンプトでは、使うかどうかわからない情報も最初から全部入ってしまいます。
一方、Agent Skillsでは次のように動きます。
Agent Skillsでは、次のように段階的に情報を読みます。
- レベル1：
name/description- 起動時に常に読みます。
- Claudeは「どんなSkillがあるか」「いつ使うか」を知ります。
- レベル2：
SKILL.md本文- Skillが関連したときだけ読みます。
- 手順やベストプラクティスがコンテキストに入ります。
- レベル3：追加資料・コード
- 必要になったときだけ読みます。
- スクリプトは必要に応じて実行します。
この仕組みによって、Claudeは「どんなSkillがあるか」は知っているけれど、「全部の中身」を常に抱え込む必要はありません。
たとえるなら、本棚の目録だけを先に見ておいて、必要になった本だけを開くようなイメージです。
6. Agent Skillsが使える場所
Agent Skillsは、主に次の環境で使えます。
- Claude API
- 使えるSkill：事前構築Skill / カスタムSkill
- 特徴：
containerパラメータとskill_idを使います。
- Claude Code
- 使えるSkill：カスタムSkill
- 特徴：
SKILL.mdを含むディレクトリとして作ります。
- Claude.ai
- 使えるSkill：事前構築Skill / カスタムSkill
- 特徴：設定からzipファイルとしてアップロードします。
Claude APIでSkillsを使う場合は、コード実行コンテナと関連するskill_idを指定します。
また、公式ドキュメントでは、APIで使う場合に次のベータヘッダーが必要と説明されています。
code-execution-2025-08-25
skills-2025-10-02
files-api-2025-04-14
Claude Codeでは、カスタムSkillをSKILL.mdを含むディレクトリとして作れます。
APIアップロードが不要なので、開発者が手元でSkillを作って試すにはわかりやすい形です。
Claude.aiでは、設定からzipファイルとしてカスタムSkillをアップロードできます。
7. 最低限のSkill構造
すべてのSkillには、YAML front matterを含むSKILL.mdが必要です。
最低限の形は次の通りです。
---
name: your-skill-name
description: このSkillが何をし、いつ使うかを簡潔に説明する
---
# Your Skill Name
## Instructions
Claudeが従うべき手順を、明確にステップ形式で書く。
## Examples
このSkillを使う具体例を書く。
特に重要なのは、次の2つです。
-
name- 小文字、数字、ハイフンを使います。
- 短く、わかりやすい名前にします。
-
description- 何をするSkillかを書きます。
- いつ使うべきかも具体的に書きます。
初心者が最初に作るなら、SKILL.mdだけで完結するシンプルなSkillがおすすめです。
8. まず作るなら「ブログ整形Skill」がおすすめ
最初から複雑なスクリプト付きSkillを作る必要はありません。
まずは、SKILL.mdだけで動くSkillから始めると理解しやすいです。
たとえば、次のような「ブログ整形Skill」です。
---
name: blog-formatting
description: 日本語の技術ブログ記事を、初心者向けに読みやすく、見出し・要約・表・箇条書きを使って整形するときに使う
---
# Blog Formatting
## Instructions
あなたは日本語の技術ブログ編集者です。
入力された文章を、初心者にも読みやすいブログ記事に整形してください。
次のルールに従ってください。
1. 冒頭に読者の悩みに寄り添う導入文を書く
2. H2、H3見出しを使って構成を整理する
3. 専門用語はなるべく噛み砕いて説明する
4. 必要に応じて表を使う
5. 最後にまとめを書く
## Examples
入力:
FastAPIはPythonのWebフレームワークです。
出力:
# FastAPIとは？
FastAPIは、PythonでWeb APIを作るためのフレームワークです。
このようなSkillなら、コード実行なしで安全に試せます。
慣れてきたら、テンプレートファイル、参考資料、スクリプトを少しずつ追加すればOKです。
9. プロンプトとSkillの違い
Agent Skillsを理解するときは、プロンプトとの違いを押さえるとスッキリします。
プロンプトとAgent Skillの違いは、次のように考えるとわかりやすいです。
- 主な用途
- プロンプト：その場の指示に向いています。
- Agent Skill：再利用する専門知識に向いています。
- 保存場所
- プロンプト：会話の中に書きます。
- Agent Skill：ファイルシステム上のSkillディレクトリに置きます。
- 読み込み方
- プロンプト：基本的に入力した分が最初から入ります。
- Agent Skill：必要に応じて段階的に入ります。
- 再利用性
- プロンプト：低めです。
- Agent Skill：高いです。
- 追加資料
- プロンプト：長くなると扱いにくいです。
- Agent Skill：別ファイルとして持てます。
- スクリプト
- プロンプト：通常は含めにくいです。
- Agent Skill：同梱して実行できます。
ざっくり言うと、次の判断でOKです。
- 1回限りの指示ならプロンプト
- 何度も使う知識ならSkill
- 実行コードやテンプレートも含めたいならSkill
10. Agent Skillsに向いている用途
Agent Skillsは、繰り返し使う専門知識や作業手順と相性がよいです。
Agent Skillsは、たとえば次のような用途に向いています。
- ドキュメント処理
- PDF、Word、Excel、PowerPointの作成・変換・整理
- 社内ノウハウ共有
- 社内標準のレビュー観点、報告書フォーマット
- 定型ワークフロー
- 毎月のレポート作成、チェックリスト処理
- 専門知識の再利用
- 法務、経理、IT運用、開発標準などの手順化
- 複数Skillの組み合わせ
- Excel分析 → PowerPoint生成 → Word報告書作成
ITエンジニア向けなら、次のようなSkillも面白そうです。
- 障害報告書作成Skill
- ログ分析Skill
- API仕様レビューSkill
- コードレビュー観点Skill
- TerraformレビューSkill
- セキュリティチェックSkill
- 社内運用手順書作成Skill
- Excel台帳整形Skill
- 議事録からタスク化するSkill
- KDP電子書籍の章構成作成Skill
こう考えると、Agent Skillsは単なるClaudeの便利機能ではなく、業務ノウハウをAIに渡すためのパッケージ形式とも言えます。
11. セキュリティ上の注意点
Agent Skillsは強力ですが、注意も必要です。
なぜなら、Skillには指示だけでなく、実行可能なコードや参照ファイルを含められるからです。
悪意のあるSkillがあると、Claudeに不適切なツール呼び出しやコード実行を指示する可能性があります。
そのため、Skillは「ただのメモ」ではなく、ミニソフトウェアとして扱うべきです。
注意点は次の通りです。
- 信頼できるソースのSkillだけ使う
-
SKILL.mdだけでなく同梱スクリプトも監査する - 外部URLに依存するSkillは特に注意する
- 機密データに触れるSkillは慎重に扱う
- 本番環境では、ソフトウェアを導入する感覚でレビューする
特に、外部URLから情報を取得するSkillには注意が必要です。
外部コンテンツに悪意のある指示が混ざっている可能性があるためです。
また、顧客情報や社内機密にアクセスするSkillは、情報漏えいリスクも考える必要があります。
12. ZDR対象外である点にも注意
公式ドキュメントでは、Agent SkillsはZero Data Retention、つまりZDRの対象外と説明されています。
つまり、データはこの機能の標準保持ポリシーに従って保持されます。
企業利用や機密情報を扱う場合は、この点も確認が必要です。
特に、次のようなデータを扱う場合は、事前に利用条件や運用ルールを確認した方が安全です。
- 顧客情報
- 社内の機密文書
- 契約書
- 財務情報
- 医療・法務関連情報
- 個人情報
- 本番システムに近い情報
13. Skill設計のコツ
最後に、初心者向けにSkill設計のコツをまとめます。
コツ1：descriptionに「いつ使うか」を必ず書く
Claudeはdescriptionを見て、どのSkillを使うか判断します。
そのため、単に「PDF処理」ではなく、次のように書くのがおすすめです。
description: PDFファイルからテキストや表を抽出し、要約、フォーム入力、文書結合を行うときに使う
コツ2：SKILL.mdは短く実用的にする
SKILL.mdは、Skillがトリガーされたときにコンテキストに入ります。
そのため、何でもかんでも詰め込むより、実用的な手順に絞った方が扱いやすいです。
おすすめ構成は次の通りです。
# Skill Name
## Purpose
このSkillの目的
## When to use
使うべき場面
## Instructions
手順
## Output format
出力形式
## Examples
具体例
コツ3：詳細資料は別ファイルに分ける
長い仕様書、テンプレート、サンプル集などは、SKILL.mdに全部入れずに別ファイルへ分けるのがおすすめです。
my-skill/
├── SKILL.md
├── REFERENCE.md
├── TEMPLATES.md
└── examples/
└── sample-output.md
これにより、Claudeは必要なときだけ追加ファイルを読みます。
14. まとめ
Claude Agent Skillsは、Claudeに専門知識や作業手順を再利用可能な形で持たせる仕組みです。
初心者は、まず次のように理解するとよいです。
- Agent Skillsは「専門知識入りの作業フォルダ」
-
SKILL.mdが中心ファイル -
nameとdescriptionは常に読み込まれる -
SKILL.md本文は関連時だけ読み込まれる - 追加資料やスクリプトは必要時だけ使われる
- プロンプトより再利用しやすい
- コードを含められるため、セキュリティ確認が重要
特に重要なのは、Agent Skillsが全部入りプロンプトではないという点です。
Skillは、必要な情報を必要なタイミングで開く「知識パック」です。
1回限りの作業ならプロンプトで十分です。
しかし、何度も使う業務ノウハウ、社内標準、ドキュメント処理、定型ワークフロー、専門手順をClaudeに覚えさせたいなら、Agent Skillsは非常に強力な選択肢になります。
参考リンク
- Claude Agent Skills 公式ドキュメント
https://platform.claude.com/docs/ja/agents-and-tools/agent-skills/overview - Claude API Docs
https://platform.claude.com/docs/