はじめに
SkillはClaudeエコシステムの実用的な拡張メカニズム。「Claudeにどう仕事してほしいか」をフォルダーに固化する仕組み。毎回の会話で好みやフローを説明し直す必要がなく、一度教えるだけでOK。
このガイドはAnthropic公式の完全チュートリアル。基礎概念から設計、テスト、デプロイ、5つの実践パターン、トラブルシューティングまで33ページで網羅。
第一章：基礎概念
Skillとは？
1つのSkill = 1つのフォルダー。中身は：
SKILL.md（必須）：YAML frontmatter付きのMarkdown指示ファイル
scripts/（任意）：実行コード（Python、Bash等）
references/（任意）：必要時に読み込む参考ドキュメント
assets/（任意）：テンプレート、フォント、アイコン等の出力リソース
核心設計原則
段階的開示：3層構造で情報を管理。frontmatterは常に読み込まれ、本文は関連時のみ読み込まれ、関連ファイルは必要時のみアクセス。トークン消費を最小化。
構成可能性：複数のSkillを同時に読み込み可能。他のSkillと共存できるよう設計すべき。
移植性：Claude.ai、Claude Code、APIで一貫して動作。一度書けば全プラットフォームで実行可能。
MCP開発者向け：Skills + コネクター
MCPは「プロ用キッチン」（道具と材料）、Skillは「レシピ」（手順）。MCPは「何ができるか」、Skillは「どうやるか」を定義。組み合わせで初めて価値を発揮。
第二章：計画と設計
ユースケースから出発
コードを書く前に、2〜3の具体的なユースケースを特定。良いユースケース定義には：トリガー条件、ステップ、期待結果を含める。
3つのユースケース分類
分類1：ドキュメント・アセット作成：一貫した高品質な出力を作成。スタイルガイドやブランド基準を埋め込み。例：frontend-design Skill。
分類2：ワークフロー自動化：統一された方法論でマルチステップフローを処理。検証ステップ付きの段階的ワークフロー。例：skill-creator Skill。
分類3：MCP強化：MCPサーバーのツールアクセスにワークフロー指導を追加。複数のMCP呼び出しを順序よく調整。例：sentry-code-review Skill。
YAML Frontmatter：最も重要な部分
FrontmatterがClaudeがSkillを読み込むかどうかを決定。nameはkebab-case必須。descriptionは「何をするか」と「いつ使うか」を含める。1024文字以内、XMLタグ禁止。
良いdescriptionの構造：[何をするか] + [いつ使うか] + [コア機能]。ユーザーが発言しそうな具体的なフレーズを含める。
第三章：テストと反復
推奨テスト方法
1. トリガーテスト：Skillが正しいタイミングで読み込まれるか検証。「トリガーすべき発言」と「トリガーすべきでない発言」をテスト。
2. 機能テスト：Skillが正しい結果を生成するか検証。入力→実行→検証のフローで確認。
3. パフォーマンス比較：Skill使用時と非使用時を比較。ユーザー操作、往復会話、API呼び出し失敗、トークン消費を測定。
skill-creatorの使用
Anthropic提供の補助ツール。自然言語記述からSkill生成。frontmatter生成、トリガーフレーズ提案、一般的問題の検出まで対応。「skill-creator skillを使って[ユースケース]のskillを構築して」とClaudeに依頼するだけ。
フィードバックに基づく反復
トリガー不足→descriptionに詳細とキーワードを追加。トリガー過多→ネガティブトリガー条件を追加。実行問題→指示を改善しエラー処理を追加。
第四章：配布と共有
現在の配布方法
個人インストール：Skillフォルダーをダウンロード→Claude.aiのSettings > Capabilities > Skillsからアップロード。
組織レベルSkill：管理者がワークスペース範囲でデプロイ可能。自動更新、集中管理。
APIでSkillsを使用
/v1/skillsエンドポイントでSkill管理。Messages APIのcontainer.skillsパラメータで追加。Claude Consoleでバージョン管理。
推奨プラクティス
GitHubで公開し、明確なREADME（人向け）、使用例、スクリーンショットを含める。MCPドキュメントにリンクを追加し、組み合わせの価値を説明。
第五章：パターンとトラブルシューティング
5つの設計パターン
パターン1：順次ワークフロー編成：特定の順序で実行すべきマルチステップフロー。明確なステップ順序、ステップ間の依存関係、各ステップの検証を定義。
パターン2：マルチMCP調整：複数サービスにまたがるワークフロー。フェーズの明確な分割、MCP間のデータ受け渡し、次フェーズ進入前の検証。
パターン3：反復的洗練：反復で品質向上。明確な品質基準、検証スクリプト、終了タイミングを定義。
パターン4：コンテキスト認識ツール選択：同じ目標でもコンテキストにより異なるツールを使用。明確な決定基準、代替案、選択プロセスの透明性。
パターン5：ドメイン専門知識埋め込み：ツールアクセスを超えた専門知識を追加。ドメイン知識のロジック埋め込み、行動前のコンプライアンス、包括的ドキュメント。
トラブルシューティング
アップロード失敗：SKILL.mdの命名確認（大文字小文字区別）、YAML形式確認。
トリガーしない：descriptionが具体性に欠ける場合、トリガーフレーズを追加。Claudeに「[skill名] skillはいつ使いますか？」と質問してデバッグ。
トリガー過多：ネガティブトリガー追加、より具体的に記述、スコープを限定。
指示が無視される：指示を簡潔に、重要事項をトップに配置、スクリプトで決定的に検証。
第六章：リソースと参照
公式ドキュメント
Anthropic提供：Best Practices Guide、Skills Documentation、API Reference、MCP Documentation。
ツール
skill-creator：Claude.aiとClaude Codeに組み込み。記述からSkill生成、改善提案。「skill-creatorを使ってskillを構築して」と依頼。
サポート
技術的質問：Claude Developers Discord。バグ報告：GitHub Issues（skill名、エラーメッセージ、再現手順を添付）。
よくある質問
Q: Skillとプロンプトテンプレートの違いは？
A: プロンプトテンプレートは使い捨て。Skillは永続的な知識パッケージ。Claudeがいつ使うか、どう使うかを自動認識。複数ファイル構造をサポート。
Q: SKILL.mdの最適な長さは？
A: コア指示は5,000語以内。詳細はreferences/に配置。
Q: 複数のSkillを同時有効化できる？
A: 技術的に制限はないが、20〜50個以上でレスポンス遅延や品質低下の可能性。機能別にグループ化し選択的に有効化を推奨。
Q: Skillはクロスプラットフォームで使える？
A: はい。Claude.ai、Claude Code、APIで利用可能。環境依存がある場合はcompatibilityフィールドで要件を明記。
原文リンク：https://resources.anthropic.com/hubfs/The-Complete-Guide-to-Building-Skill-for-Claude.pdf?hsLang=en