【ハンズオン】Agent Skillsの作り方・ベストプラクティス・配布方法

要約

Agent Skillsの作成方法には、skill-creatorスキルを使う方法と手動で作成する方法がある。SKILL.mdファイルは必須であり、nameとdescriptionのフロントマターが正しく設定されていることが重要である。マルチファイル構成では、scripts/、reference.md、templates/などを活用してトークン効率を最適化できる。チームへの配布は、Zip、Git、プラグインバンドルの3つの方法がある。

対象読者: Agent Skillsの基本概念を理解し、自分でスキルを作成したいエンジニア

検証環境: Claude Code 2.0.76 / Claude.ai Pro以上（2025年12月時点）

この記事を読むことで得られるメリット

この記事を読むことで以下のことが分かる:

Agent Skillsの基本構造とSKILL.mdの書き方
skill-creatorスキルを使った効率的な作成方法
マルチファイル構成でトークン効率を最適化する方法
命名規則やファイルサイズなどのベストプラクティス
MCPツールとの連携方法（参照形式）
チームや組織への配布・展開方法

この記事を読むのにかかる時間

約18分

環境

MacOS Apple M4 Max Sequoia 15.1
Claude Code 2.0.76
Claude Pro / Max / Team / Enterpriseプランのいずれか

Agent Skillsの基本構造

フォルダ構成

Agent Skillsは、フォルダとファイルで構成される。最小構成は以下の通りである。

my-skill/
└── SKILL.md    # 必須

より実践的な構成では、追加のファイルを含めることができる。

pdf-processing/
├── SKILL.md              # メイン指示（必須）
├── FORMS.md              # フォーム入力ガイド（オプション）
├── reference.md          # APIリファレンス（オプション）
├── examples.md           # 使用例（オプション）
├── scripts/              # スクリプト（オプション）
│   ├── analyze_form.py
│   ├── fill_form.py
│   └── validate.py
├── templates/            # テンプレート（オプション）
└── assets/               # フォント、画像、設定ファイル（オプション）

SKILL.mdのフロントマター要件

SKILL.mdには、フロントマターが必須である。以下の2つのフィールドを必ず含める必要がある。

---
name: pdf-processing
description: PDFファイルからテキストや表を抽出し、フォームに記入し、文書を結合します。PDFの処理、フォーム入力の自動化が必要な場合に使用。
---

nameフィールドの要件:

最大64文字
小文字、数字、ハイフンのみを使用
XMLタグを含めることはできない
予約語（「anthropic」「claude」）を含めることはできない

descriptionフィールドの要件:

空にすることはできない
最大1024文字
XMLタグを含めることはできない
何ができるかといつ使うかの両方を含める

descriptionの質がスキル呼び出しの精度を左右する。Claudeはこの説明を読んで、ユーザーのリクエストとマッチングを行う。

良い例と悪い例:

説明	評価	理由
「コンテンツマーケティングのヘルパー」	悪い	範囲が広すぎる
「メタディスクリプションの追加」	悪い	範囲が狭すぎる
「ブログ記事のSEO最適化を行う。タイトル、メタディスクリプション、内部リンクを改善する場合に使用」	良い	具体的で使用タイミングが明確

maasaablog.com

Agent Skillsとは？仕組みと基本概念をわかりやすく解説

Agent Skillsの作成方法

方法1: skill-creatorスキルを使う（推奨）

Anthropicは、スキルを作成するためのスキル「skill-creator」を提供している。これが最も簡単な方法である。

手順:

Claude.aiの設定→機能→スキルから「skill-creator」を有効にする
チャットで「○○のワークフロー用Skillを作りたい」と伝える
関連資料（テンプレート、ブランドガイドラインなど）をアップロード
Claudeが対話的にスキルを構築

skill-creatorは、構造化されたスキルの作成をガイドする。説明文の改善点を提案し、指示書の適切なフォーマット設定をサポートする。特に最初の数個のスキル作成に役立つ。

方法2: 手動で作成する

skill-creatorを使わず、手動でスキルを作成することも可能である。

手順:

スキル用のフォルダを作成
SKILL.mdファイルを作成
フロントマター（name、description）を記述
本文に手順や指示を記述
必要に応じて追加ファイルを作成

最小構成の例（Hello World）

最もシンプルなスキルの例を示す。

hello-world/
└── SKILL.md

SKILL.md:

---
name: greeting-generator
description: 挨拶メッセージを生成する。「おはよう」「こんにちは」などの挨拶を作成する場合に使用。
---

# 挨拶メッセージ生成

## 概要

このスキルは、状況に応じた挨拶メッセージを生成する。

## 手順

1. 時間帯を確認する（朝・昼・夜）
2. フォーマルかカジュアルかを判断する
3. 適切な挨拶メッセージを生成する

## 例

- 朝・カジュアル: 「おはよう！今日も一日頑張ろう」
- 昼・フォーマル: 「お疲れ様です。本日もよろしくお願いいたします」

SKILL.mdの書き方

必須要素（name, description）

前述の通り、nameとdescriptionはフロントマターで必須である。ここでは、本文の構成について解説する。

推奨セクション構成

SKILL.mdの本文には、以下のセクションを含めることを推奨する。

# スキル名

## 概要
[このスキルが何をするかの簡潔な説明]

## 手順
1. [ステップ1]
2. [ステップ2]
3. [ステップ3]

## 制約事項
- [このスキルでできないこと]
- [注意点]

## 例
[具体的な使用例]

明確な階層構造を意識する。概要、前提条件、実行手順、例、エラー処理、制限事項という流れが理想的である。複雑なワークフローは、明確な入力と出力を持つ個別のフェーズに分割する。

命名規則（動名詞形推奨）

スキル名には動名詞形（動詞 + -ing）を使用することが推奨される。これはスキルが提供するアクティビティを明確に説明するためである。

良い命名例（動名詞形）:

processing-pdfs
analyzing-spreadsheets
managing-databases
testing-code
writing-documentation
generating-commit-messages

悪い命名例:

pdf → 何をするか不明
my-skill → 説明的でない
helper → 抽象的すぎる

マルチファイルスキル構成

フォルダ構造の設計

SKILL.mdが大きくなりすぎた場合（目安は500行以上）、内容を別々のファイルに分割することを推奨する。

seo-optimizer/
├── SKILL.md                    # メイン指示（500行以下に抑える）
├── reference.md                # 補足情報と参照情報
├── title-optimization.md       # タイトル最適化の詳細
├── meta-optimization.md        # メタディスクリプション最適化
├── content-optimization.md     # 本文最適化
└── scripts/
    └── analyze_keywords.py     # キーワード分析スクリプト

SKILL.md内でこれらのファイルを参照することで、Claudeはスキル実行時にそのリソースにアクセスする必要があるかどうかを判断できる。

## 詳細手順

タイトル最適化の詳細は `title-optimization.md` を参照されたい。
メタディスクリプションについては `meta-optimization.md` に記載している。

この「メニュー」アプローチにより、Claudeはユーザーのタスクに関連するファイルのみを読み取り、その会話では他のファイルはそのまま残す。

スクリプトによるトークン節約

スクリプトを活用すると、以下のメリットがある。

トークンを節約: コンテキストにコードを含める必要がない
時間を節約: コード生成は不要
決定論的な処理: LLMの生成に頼らない確実な処理

Claudeがスクリプトを実行すると、スクリプトのコード自体はコンテキストウィンドウに読み込まれない。スクリプトの出力のみ（「検証に成功しました」や特定のエラーメッセージなど）がトークンを消費する。

例: バリデーションスクリプト

my-skill/
├── SKILL.md
└── scripts/
    └── validate_form.py

SKILL.mdで以下のように参照する。

## 検証手順

フォーム入力後、`scripts/validate_form.py` を実行して入力値を検証する。
エラーがあればメッセージを表示し、修正を促す。

これにより、スクリプトはClaudeが同等のコードをその場で生成するよりもはるかに効率的になる。

ベストプラクティス

500行以下に抑える

SKILL.mdの本文は、最適なパフォーマンスのために500行以下に保つことを推奨する。この制限に近づいたときは、コンテンツを別のファイルに分割する。

メニューアプローチの活用

スキルが複数の異なるプロセスやオプションをカバーする場合、SKILL.mdで利用可能な機能を記述し、それぞれを相対パスで参照して個別のファイルを参照する。

## 利用可能な機能

このスキルは以下の機能を提供する:

1. **タイトル最適化** → `title-optimization.md`
2. **メタ最適化** → `meta-optimization.md`
3. **内部リンク分析** → `internal-linking.md`

必要な機能のファイルを参照して実行する。

モデル別のテスト考慮

スキルはモデルへの追加として機能するため、効果は基礎となるモデルに依存する。使用予定のすべてのモデルでスキルをテストすることを推奨する。

モデル	特徴	テスト時の考慮点
Claude Haiku	高速、経済的	スキルは十分なガイダンスを提供しているか？
Claude Sonnet	バランス型	スキルは明確で効率的か？
Claude Opus	強力な推論	スキルは過度な説明を避けているか？

Opusで完璧に機能するものは、Haikuではより詳細が必要な場合がある。複数のモデルでスキルを使用する予定がある場合は、すべてのモデルでうまく機能する指示を目指す。

その他のベストプラクティス

よく行うタスクに対して作成する: 「このタスクを少なくとも5回実行したか？あと10回以上実行する予定があるか？」と自問する
必須項目を明記する: フォーマット基準、検証チェック、品質基準を指示書に含める
具体的な例を含める: 正しい使用方法を示す例を記載する
制限事項を明記する: スキルで実行できない操作を明記し、誤用を防ぐ

MCPツールとの連携

MCPツール参照形式（ServerName:tool_name）

スキルがMCP（Model Context Protocol）ツールを使用する場合、「ツールが見つかりません」エラーを避けるために完全修飾ツール名を使用する。

形式: ServerName:tool_name

例:

## データ取得手順

1. `BigQuery:bigquery_schema` ツールを使用してテーブルスキーマを取得する
2. `GitHub:create_issue` ツールを使用して問題を作成する
3. `Slack:send_message` ツールを使用してメッセージを送信する

サーバープレフィックスがないと、特に複数のMCPサーバーが利用可能な場合、Claudeはツールの場所を特定できない可能性がある。

maasaablog.com

Agent Skillsとは？仕組みと基本概念をわかりやすく解説

実践例：週報自動作成スキル

MCPツールと連携するスキルの実践例を示す。

---
name: generating-weekly-reports
description: 週報を自動作成し、Slackに投稿する。「週報を作って」などのリクエストで使用。
---

# 週報自動作成

## 概要

このスキルは、カレンダー、Slack、タスク管理ツールからデータを収集し、週報を自動生成する。

## 手順

1. `google-calendar:get_events` で今週の会議を取得する
2. `slack:get_messages` で自分の投稿を取得する
3. `notion:get_tasks` で完了タスクを取得する
4. 以下のフォーマットで週報を作成する:
   - 今週の成果
   - 進行中の作業
   - 来週の予定
5. `slack:send_message` で #weekly-report チャンネルに投稿する

## 制約事項

- 各サービスへのMCP接続が事前に設定されている必要がある
- 投稿先チャンネルへの書き込み権限が必要

maasaablog.com

怒涛の24ユースケース紹介｜今話題のAgent Skillsを一挙に実践紹介

配布方法

個人向け配布

個人やチームメンバーとスキルを共有するには、以下の方法がある。

Zip配布

スキルフォルダをZipファイルにまとめて共有する。最も簡単で非公式なコラボレーション向けである。

手順:

スキルフォルダをZip圧縮
チームメイトに送付
受け取り側がClaude.ai設定→スキル→「スキルをアップロード」からZipをアップロード

注意: ZIPにはスキルフォルダがルート（サブフォルダではない）として含まれている必要がある。

Git配布

完全なコミット履歴とブランチ管理を使用して、コードと一緒にスキルをバージョン管理する。

my-project/
├── .claude/
│   └── skills/
│       └── my-skill/
│           └── SKILL.md
├── src/
└── README.md

Claude Codeでは、プロジェクトのルートに skills/ ディレクトリを作成し、SKILL.mdファイルを含むスキルフォルダを追加する。プロジェクトをクローンすると、スキルも一緒に取得できる。

プラグインバンドル

スキルをClaude Codeプラグインにパッケージ化して配布する。プラグインの skills/ ディレクトリにスキルをバンドルすることで、プラグインのインストール時にClaudeが自動的に検出して使用する。

my-plugin/
├── skills/
│   └── my-skill/
│       └── SKILL.md
└── plugin.json

Team/Enterprise向け展開

Claude TeamおよびEnterpriseプランでは、管理者が組織全体にSkillsを一括展開できる。

特徴:

管理者がプロビジョニングしたSkillsは全ユーザーにデフォルトで有効化される
個別にオフにすることも可能
組織内で承認・維持されるバージョンを集中リポジトリでホスト

API経由での展開:

Claude開発者プラットフォームでは、Skills API（/v1/skillsエンドポイント）経由でスキルをアップロードできる。

curl -X POST "https://api.anthropic.com/v1/skills" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: skills-2025-10-02" \
  -F "display_title=My Skill Name" \
  -F "files[]=@my-skill/SKILL.md;filename=my-skill/SKILL.md"

まとめ

本記事では、Agent Skillsの作成から配布までを実践的に解説した。

重要なポイントを振り返る:

基本構造: SKILL.mdは必須、nameとdescriptionのフロントマターを正しく設定する
作成方法: skill-creatorスキルを使う方法が最も簡単、手動作成も可能
マルチファイル構成: 500行を超えたら分割、スクリプトでトークン節約
命名規則: 動名詞形（processing-pdfs など）を推奨
ベストプラクティス: メニューアプローチ、モデル別テスト、よく行うタスクに作成
MCP連携: ServerName:tool_name 形式で完全修飾ツール名を使用
配布方法: Zip、Git、プラグインバンドル、API経由

次の記事では、Agent Skillsの具体的なユースケースを10個以上紹介し、実際の活用事例を解説する。

>

【ハンズオン】Agent Skillsの作り方・ベストプラクティス・配布方法

INDEX

要約

この記事を読むことで得られるメリット

この記事を読むのにかかる時間

環境

Agent Skillsの基本構造

フォルダ構成

SKILL.mdのフロントマター要件

Agent Skillsの作成方法

方法1: skill-creatorスキルを使う（推奨）

方法2: 手動で作成する

最小構成の例（Hello World）

SKILL.mdの書き方

必須要素（name, description）

推奨セクション構成

命名規則（動名詞形推奨）

マルチファイルスキル構成

フォルダ構造の設計

スクリプトによるトークン節約

ベストプラクティス

500行以下に抑える

メニューアプローチの活用

モデル別のテスト考慮

その他のベストプラクティス

MCPツールとの連携

MCPツール参照形式（ServerName:tool_name）

実践例：週報自動作成スキル

配布方法

個人向け配布

Zip配布

Git配布

プラグインバンドル

Team/Enterprise向け展開

まとめ

MORE READING

AUTHOR

masayan

INDEX

要約

この記事を読むことで得られるメリット

この記事を読むのにかかる時間

環境

Agent Skillsの基本構造

フォルダ構成

SKILL.mdのフロントマター要件

Agent Skillsの作成方法

方法1: skill-creatorスキルを使う（推奨）

方法2: 手動で作成する

最小構成の例（Hello World）

SKILL.mdの書き方

必須要素（name, description）

推奨セクション構成

命名規則（動名詞形推奨）

マルチファイルスキル構成

フォルダ構造の設計

スクリプトによるトークン節約

ベストプラクティス

500行以下に抑える

メニューアプローチの活用

モデル別のテスト考慮

その他のベストプラクティス

MCPツールとの連携

MCPツール参照形式（ServerName:tool_name）

実践例：週報自動作成スキル

配布方法

個人向け配布

Zip配布

Git配布

プラグインバンドル

Team/Enterprise向け展開

まとめ

SHARE

MORE READING

Agent Skillsとは？仕組みと基本概念をわかりやすく解説

怒涛の24ユースケース紹介｜今話題のAgent Skillsを一挙に実践紹介

Agent Skills vs MCP 完全ガイド：5つの決定的な違いと使い分け・共存

MCP・Claudeスキルが示す「参加のアーキテクチャ」とは？Tim O'Reilly解説

RELATED

Webエンジニアなら確実に押さえておきたい最強のAIサービス Vrew編

microCMSでMCPサーバーを使用してコンテンツの入稿をしてみた

AI時代のドキュメント作成：Claude Codeでビジネス、開発で必要なドキュメント作成を劇的に効率化

Claude DesktopからMCPサーバーを経由して外部APIからデータを取得するチュートリアル

CLAUDE.md ベストプラクティス完全ガイド｜60行以下で性能最大化

Claude Code クラッシュコース基礎編 - 実践で使える必須テクニック

AUTHOR

masayan