- はじめに
- 基礎概念
- 計画と設計
- テストと反復開発
- 配布と共有
- パターンとトラブルシューティング
- 参考資料と関連情報
スキルとは、特定のタスクやワークフローの処理方法を簡潔なフォルダ形式でまとめた指示セットです。 Claudeをあなたのニーズに合わせてカスタマイズする最も強力な方法の一つです。 毎回会話のたびに好みやプロセス、専門分野の知識を説明し直す代わりに、スキルを使えば一度教えるだけで何度でもその恩恵を受けられます。 繰り返し発生するワークフローがある場合、スキルは特に有効です。具体的には、仕様書からのフロントエンドデザイン生成、一貫した手法によるリサーチ、チームのスタイルガイドに沿った文書作成、複数段階にわたるプロセスの調整などが挙げられます。また、コード実行機能や文書作成機能といったClaudeの標準機能ともシームレスに連携します。MCP（Multi-Capability Platform）との連携を構築する場合、スキルはさらに強力なレイヤーを追加し、単なるツールアクセスを信頼性の高い最適化されたワークフローへと進化させます。 このガイドでは、効果的なスキルを構築するために知っておくべきすべての内容を網羅しています。計画立案と構造設計からテスト方法、公開手順まで、幅広いトピックを解説しています。自分用、チーム用、あるいはコミュニティ向けのスキルを構築する場合でも、実践的なパターンや実際の使用例を豊富に掲載していますので、ぜひ参考にしてください。
- スキル構造における技術的要件とベストプラクティス
- スタンドアローンスキルとMCP強化ワークフローの設計パターン
- 様々なユースケースで効果が実証されたパターン事例
- スキルのテスト方法、改善プロセス、および展開方法
- Claudeに特定のワークフローを一貫して実行させたい開発者
- Claudeに特定のワークフローを実行させたいパワーユーザー
- 組織全体でClaudeの動作を標準化したいチーム
スタンドアローン型スキルを構築する場合：「基本機能」「プランニングと設計」、そしてカテゴリ1-2に焦点を当ててください。 MCP連携機能を強化する場合：「スキル＋MCP」セクションとカテゴリ3が該当します。どちらのアプローチも技術的要件は共通していますが、ご自身のユースケースに最適な内容を選択できます。
最後まで読み進めることで、1回のセッションで機能的なスキルを構築できるようになります。スキルクリエイターを使用して最初の動作可能なスキルを構築・テストするには、約15～30分程度を見込んでください。 それでは、さっそく始めましょう。
スキルとは、以下の内容を含むフォルダです：
- SKILL.md（必須）：YAMLフロントマター付きMarkdown形式の説明文書
- scripts/（オプション）：実行可能なコード（Python、Bashなど）
- references/（オプション）：必要に応じて読み込まれるドキュメント
- assets/（オプション）：出力時に使用されるテンプレート、フォント、アイコン
本システムではスキル管理に3段階の階層構造を採用しています：
- 第1階層（YAMLフロントマター）：常にClaudeのシステムプロンプトに読み込まれます。各スキルをいつ使用すべきかを判断するのに十分な情報を提供しつつ、すべての情報をコンテキストに読み込むことは避けます。
- 第2階層（SKILL.md本文）：Claudeが現在のタスクに当該スキルが関連していると判断した場合に読み込まれます。ここには完全な使用手順と詳細なガイダンスが含まれます。
- 第3階層（リンクファイル）：スキルディレクトリ内にバンドルされた追加ファイルで、Claudeは必要に応じてこれらを参照・探索できます。
この漸進的開示方式により、トークン使用量を最小限に抑えつつ、専門的な知識を効果的に活用することが可能です。
Claudeは複数のスキルを同時に読み込むことができます。 あなたのスキルは、他のスキルと協調して動作するように設計されている必要があり、唯一の機能として振る舞うべきではありません。
スキルは Claude.ai、Claude Code、API 間で完全に同じように動作します。一度スキルを作成すれば、環境がスキルに必要な依存関係をサポートしている限り、修正なしですべてのプラットフォームで使用できます。
💡 MCPを使用せずにスタンドアロンのスキルを構築中ですか？その場合は「計画と設計」セクションに直接進んでください。後からいつでもこのセクションに戻ることができます。
すでに動作するMCPサーバーをお持ちの場合、すでに難しい部分はクリアしています。スキルはその上に構築する知識層であり、あなたが既に熟知しているワークフローやベストプラクティスを取り込み、Claudeが一貫して適用できるようにするものです。
MCPはプロ仕様のキッチンを提供します：ツール、食材、設備へのアクセスです。 スキルはレシピを提供します：価値あるものを作り出すための段階的な手順書です。
これらを組み合わせることで、ユーザーは複雑な作業を、各ステップを自力で解明することなく完了できるようになります。 その連携方法：
| MCP（接続性） | スキル（知識） |
|---|---|
| Claudeを貴社サービスに接続します（Notion、Asana、Linearなど） | Claudeに貴社サービスの効果的な活用方法を教えます |
| リアルタイムデータへのアクセスとツールの呼び出しを可能にします | ワークフローとベストプラクティスを記録します |
| Claudeにできること | Claudeの適切な活用方法 |
- MCPに接続しても、ユーザーは次に何をすべきかわからない
- 「統合機能でXを行う方法は？」といったサポート問い合わせが頻発
- 各会話が毎回ゼロからのスタートになる
- ユーザーのプロンプト方法が異なるため、結果に一貫性が見られない
- 実際の問題はワークフローのガイダンス不足であるにもかかわらず、ユーザーはコネクタの不具合のせいにする
- 必要な時に自動的に起動する事前構築済みワークフローが利用可能
- 一貫性のある信頼性の高いツール活用が可能
- すべてのインタラクションにベストプラクティスが組み込まれる
- 統合機能の学習曲線が緩やかになる
コードを書き始める前に、あなたのスキルが実現すべき具体的なユースケースを2～3個特定してください。 効果的なユースケース定義のポイント：
Use Case: Project Sprint Planning
Trigger: User says "help me plan this sprint" or "create
sprint tasks"
Steps:
1. Fetch current project status from Linear (via MCP)
2. Analyze team velocity and capacity
3. Suggest task prioritization
4. Create tasks in Linear with proper labels and estimates
Result: Fully planned sprint with tasks created- ユーザーは具体的に何を達成したいのか？
- それを実現するために必要な多段階のワークフローは何か？
- どのツールが必要か（組み込み機能かMCPか）？
- どのような専門知識やベストプラクティスを組み込むべきか？
Anthropic社では、主に以下の3つの典型的な活用ケースを確認しています：
用途：文書、プレゼンテーション、アプリケーション、デザイン、コードなど、一貫性のある高品質なアウトプットを生成する際に使用
実例：frontend-designスキル（docx、pptx、xlsx、ppt用スキルも参照可能）
「デザイン性に優れ、実際に運用可能なフロントエンドインターフェースを作成します。Webコンポーネントやページ、アーティファクト、ポスター、アプリケーションの開発時にご活用ください」
- 組み込みのスタイルガイドとブランド基準の適用
- 一貫した出力を実現するためのテンプレート構造
- 最終出力前の品質チェックリスト
- 外部ツール不要 - Claudeの内蔵機能のみで完結
用途：複数の段階からなるプロセスで、一貫した方法論による効率化が図れる場合、 特に複数のMCPサーバーを跨ぐ連携作業に適しています。
「新しいスキルを作成するためのインタラクティブガイド。ユーザーを使用事例の定義、 フロントマターの生成、手順書の作成、検証といった各工程に段階的に案内します。」
- 検証ゲートを備えた段階的ワークフロー
- 一般的な構造向けのテンプレート機能
- 組み込み型のレビュー機能と改善提案
- 反復的な改良ループ
用途：MCPサーバーが提供するツールへのアクセスを支援するためのワークフローガイダンス。
実例：sentry-code-reviewスキル（Sentry社製）
「GitHubプルリクエストで検出されたバグを、Sentryのエラー監視データを用いて 自動的に分析・修正します。SentryのMCPサーバー経由でデータを取得します。」
- 複数のMCPコールを順次実行する連携機能
- ドメイン専門知識の組み込み
- ユーザーが別途指定する必要のあるコンテキスト情報の提供
- MCP利用時に発生しがちなエラーへの対処機能
これらは理想的な目標値であり、厳密な閾値ではなく大まかなベンチマークです。厳密さを追求しつつも、ある程度の感覚的な評価要素が含まれることをご了承ください。現在、より信頼性の高い測定ガイドラインとツールの開発を積極的に進めています。
- 関連クエリの90%でスキルが適切に起動する – 測定方法：スキルが起動すべき10～20件のテストクエリを実行します。自動起動するケースと、明示的な呼び出しが必要なケースの回数を記録してください。
- Xツールの呼び出し回数でワークフローを完了できる
- 測定方法：スキル有効時と無効時で同じタスクを実行し、ツールの呼び出し回数と消費トークン数を比較します。
- ワークフローあたりのAPI呼び出し失敗件数が0件 – 測定方法：テスト実行時にMCPサーバーのログを監視します。リトライ回数とエラーコードを追跡してください。
- ユーザーが次の手順をClaudeに促す必要がない – 評価方法：テスト実施時に、ユーザーの誘導や説明が必要になる頻度を記録します。ベータ版ユーザーからのフィードバックも収集してください。
- ユーザーの修正なしでワークフローが完了できる – 評価方法：同じリクエストを3～5回繰り返し実行します。出力結果を比較し、構造的な一貫性と品質を確認してください。
- セッション間で一貫した結果が得られる – 評価方法：新規ユーザーが最小限のガイダンスで、初回の試行でタスクを完了できるかどうかを検証してください。
your-skill-name/
├── SKILL.md # Required - main skill file
├── scripts/ # Optional - executable code
│ ├── process_data.py # Example
│ └── validate.sh # Example
├── references/ # Optional - documentation
│ ├── api-guide.md # Example
│ └── examples/ # Example
└── assets/ # Optional - templates, etc.
└── report-template.md # Exa- 正確に「SKILL.md」（大文字小文字を厳密に区別）
- バリエーションは認めない（例：SKILL.MD、skill.mdなど）
- ケバブケースを使用する：
notion-project-setup✅ - スペースは使用しない：
Notion Project Setup❌ - アンダースコアは使用しない：
notion_project_setup❌ - 大文字は使用しない：
NotionProjectSetup❌
- スキルフォルダ内にREADME.mdを含めない
- すべてのドキュメントはSKILL.mdまたはreferences/ディレクトリに配置すること
- 注：GitHub経由で配布する場合でも、人間のユーザーが参照できるようにリポジトリレベルのREADMEファイルを用意することが望ましい ― 配布と共有のセクションを参照のこと。
YAMLフロントマターは、Claudeがあなたのスキルを読み込むかどうかを判断する重要な要素です。この設定を正確に行う必要があります。
-
name: your-skill-name
description: What it does. Use when user asks to [specific
phrases].
---これで準備は完了です。
name（必須）：
- ケバブケース形式のみ使用可
- スペースや大文字は使用不可
- フォルダ名と一致させる必要があります
description（必須）：
- 以下の両方を必ず含めてください： – スキルの機能内容 – 使用タイミング（トリガー条件）
- 1024文字以内
- XMLタグ（）は使用不可
- ユーザーが言いそうな具体的なタスク例を記載してください
- 関連するファイル形式があれば明記してください
license（任意）：
- スキルをオープンソースとして公開する場合に指定してください
- 一般的なライセンス例：MITライセンス、Apache License 2.0
compatibility（任意）
- 1～500文字以内
- 環境要件を示す情報：想定される製品、必要なシステム環境、必要なパッケージ、ネットワークアクセス要件などを記載します
metadata（任意）：
- 任意のキーと値のペアを設定可能
- 推奨項目：作成者、バージョン、mcp-server
- 具体例：
metadata:
author: ProjectHub
version: 1.0.0 mcp-server: projecthub- XMLの角括弧記号（< >）
- 名称に「claude」または「anthropic」を含むスキル（予約語扱い）
理由：フロントマターはClaudeのシステムプロンプトに表示されるため、 悪意のあるコンテンツが指示を挿入するリスクがあります。
Anthropic社のエンジニアリングブログによると、「このメタデータは...各スキルをいつ使用すべきかをClaudeが判断できる最小限の情報を提供しつつ、すべての情報をコンテキストに読み込む必要がないようにしています。」これが漸進的開示の第一段階です。
[What it does] + [When to use it] + [Key capabilities]# Good - specific and actionable
description: Analyzes Figma design files and generates
developer handoff documentation. Use when user uploads .fig
files, asks for "design specs", "component documentation", or
"design-to-code handoff".
# Good - includes trigger phrases
description: Manages Linear project workflows including sprint
planning, task creation, and status tracking. Use when user
mentions "sprint", "Linear tasks", "project planning", or asks
to "create tickets".
# Good - clear value proposition
description: End-to-end customer onboarding workflow for
PayFlow. Handles account creation, payment setup, and
subscription management. Use when user says "onboard new
customer", "set up subscription", or "create PayFlow account".# Too vague
description: Helps with projects.
# Missing triggers
description: Creates sophisticated multi-page documentation
systems.
# Too technical, no user triggers
description: Implements the Project entity model with
hierarchical relationships. フロントマターの後に、Markdown形式で実際の手順を記述してください。
このテンプレートをご自身のスキルに合わせてカスタマイズしてください。角括弧で囲まれた部分は それぞれ具体的な内容に置き換えてください。
---
name: your-skill
description: [...]
---
# Your Skill Name
# Instructions
# Step 1: [First Major Step]
Clear explanation of what happens.
Example:
\`\`\`bash
python scripts/fetch_data.py --project-id PROJECT_ID
Expected output: [describe what success looks like]（必要に応じて追加の手順を記載してください）
ユーザーの指示：「新規マーケティングキャンペーンを設定してください」
実施手順：
- MCP経由で既存キャンペーンを取得
- 提供されたパラメータを使用して新規キャンペーンを作成
結果：確認用リンク付きのキャンペーンが作成される
（必要に応じて追加の具体例を記載してください）
エラー：【一般的なエラーメッセージ】 原因：【発生原因】 解決策：【対処方法】
（必要に応じて追加のエラーケースを記載してください）
✅ Good：
Run `python scripts/validate.py --input {filename}` to check
data format.
If validation fails, common issues include:
- Missing required fields (add them to the CSV)
- Invalid date formats (use YYYY-MM-DD)❌ Bad:
Validate the data before proceeding.# Common Issues
### MCP Connection Failed
If you see "Connection refused":
1. Verify MCP server is running: Check Settings > Extensions
2. Confirm API key is valid
3. Try reconnecting: Settings > Extensions > [Your Service] >
ReconnectBefore writing queries, consult `references/api-patterns.md`
for:
- Rate limiting guidance
- Pagination patterns
- Error codes and handlingSKILL.mdファイルは基本的な指示に特化してください。
詳細なドキュメントはreferences/ディレクトリに移動し、そこからリンクを貼るようにしてください。
（3段階システムの仕組みについては、コア設計原則 を参照してください）
スキルのテストは、お客様のニーズに応じて様々なレベルの厳密さで実施可能です：
- Claude.aiでの手動テスト - 直接クエリを実行して動作を確認。迅速な反復作業が可能で、事前設定も不要です。
- Claude Codeでのスクリプトテスト - 変更に伴う繰り返し検証のためのテストケースを自動化します。
- スキルAPIを介したプログラムテスト - 定義されたテストセットに対して体系的に実行される評価スイートを構築します。
品質要件とスキルの可視性に合わせて、適切なアプローチを選択してください。小規模チーム内で内部利用されるスキルと、数千の企業ユーザーに展開されるスキルでは、必要なテスト内容が異なります。
プロのアドバイス：タスクを拡大する前に、まずは単一タスクを繰り返し処理しましょう
私たちの経験では、最も効果的なスキル作成者は、Claudeが成功するまで単一の困難なタスクを繰り返し試行し、その成功手法を抽出してスキルとして実装します。 このアプローチはClaudeの文脈学習機能を活用し、広範囲にわたるテストよりも迅速に有効なシグナルを得ることができます。 基本的な動作基盤が確立できたら、カバー範囲を広げるために複数のテストケースに展開してください。
初期の経験に基づくと、効果的な技能試験では通常、以下の3つの分野が網羅されます：
目的：スキルが適切なタイミングで正しく起動することを確認します。
- ✅ 明確なタスク要求時に正しく起動する
- ✅ 言い換えられた要求時にも正しく起動する
- ❌ 関連性のないトピックでは起動しない
Should trigger:
- "Help me set up a new ProjectHub workspace"
- "I need to create a project in ProjectHub"
- "Initialize a ProjectHub project for Q4 planning"
Should NOT trigger:
- "What's the weather in San Francisco?"
- "Help me write Python code"
- "Create a spreadsheet" (unless ProjectHub skill handles
sheets)目標：スキルが正確な出力を生成することを検証する。
テストケース：
- 有効な出力が生成されること
- API呼び出しが成功すること
- エラー処理が正常に機能すること
- エッジケースが適切に処理されること
Test: Create project with 5 tasks
Given: Project name "Q4 Planning", 5 task descriptions
When: Skill executes workflow
Then:
- Project created in ProjectHub
- 5 tasks created with correct properties
- All tasks linked to project
- No API errors目的：本手法がベースラインと比較して明確な成果向上をもたらすことを実証する
「成功基準の定義」で設定した指標を使用します。比較結果のイメージは以下の通りです。 ベースラインとの比較：
Without skill:
- User provides instructions each time
- 15 back-and-forth messages
- 3 failed API calls requiring retry
- 12,000 tokens consumed
With skill:
- Automatic workflow execution
- 2 clarifying questions only
- 0 failed API calls
- 6,000 tokens consumedスキル作成機能は、Claude.aiのプラグインディレクトリから利用可能です（またはClaude Code向けにダウンロード可能）。この機能を活用すれば、スキルの構築と改良を効率的に進めることができます。MCPサーバー環境があり、主要なワークフロー上位2～3パターンを把握している場合、1回のセッション（通常15～30分程度）で機能的なスキルを構築・テストすることが可能です。
- 自然言語による説明からスキルを生成
- フロントマター付きの適切な形式のSKILL.mdファイルを作成
- トリガーフレーズと構造の提案
- 一般的な問題点（曖昧な説明、トリガー不足、構造上の問題など）を指摘
- 過剰なトリガー発動やトリガー不足のリスクを特定
- スキルの目的記述に基づいてテストケースを提案
- スキルを実際に使用し、エッジケースや不具合に遭遇した場合、その事例をスキル作成機能にフィードバック
- 例：「このチャットで特定した問題点と解決策を活用して、[具体的なエッジケース]に対するスキルの処理方法を改善してください」