Anthropic公式ガイド全33ページを凝縮 ― Claude Skills設計パターン5選とデバッグ実践¶

対象読者

Claude Skillsの基本概念を理解済みで、実際のSkill設計・運用で手が止まっている開発者・パワーユーザー

この記事のポイント¶

Anthropic公式ガイドが提示する5つの設計パターンを、判断基準とともに整理
Skillが「発動しない」「発動しすぎる」「指示通り動かない」の3大トラブルに対する公式推奨のデバッグ手法を紹介
Skill有無でのトークン消費・やりとり回数の定量比較フレームワークを解説

公式ガイドが公開された背景¶

Anthropicは2026年1月29日、「The Complete Guide to Building Skills for Claude」と題した全33ページのPDFガイドを公開した¹。Skillsの基本構造から設計パターン、テスト方法論、配布戦略までを体系的にまとめた資料で、これまで公式ドキュメントやブログ記事に分散していた情報が一本化されている。

ただし33ページを通読するのは相応の時間がかかる。本記事では、実装判断に直結する「設計パターン」「デバッグ手法」「テスト方法論」の3テーマに絞って要点を抽出した。基本概念（Progressive DisclosureやSKILL.mdの構造など）は既知の前提で進める。未読であれば先にClaude Skills完全解説を参照されたい。

設計の出発点：Problem-first か Tool-first か¶

公式ガイドは、Skill設計のアプローチを2つに大別している¹。

Problem-first（課題起点） は、ユーザーが「プロジェクトのワークスペースを作りたい」のように成果物を求める場面を想定する。Skillが適切なMCP呼び出しを順序立てて実行し、ユーザーはツールの存在を意識しない。

Tool-first（ツール起点） は、ユーザーがすでにMCPサーバーを接続済みで、「このツールをうまく使いたい」という状況を想定する。Skillはベストプラクティスやワークフロー知識を提供し、ツールの活用精度を底上げする。

公式ガイドではホームセンターに例えている。修理したいキャビネットを持ち込んで店員に相談するのがProblem-first、電動ドリルを手に取って「これで何ができるか」を聞くのがTool-firstという位置づけだ。どちらのアプローチかによって、Skillの記述粒度やステップの抽象度が変わるため、設計の最初に決める必要がある。

5つの設計パターン¶

公式ガイドのChapter 5では、実際のSkill実装で繰り返し現れるパターンが5つ提示されている¹。以下、それぞれの適用場面と設計上のポイントを整理する。

パターン1：Sequential Workflow Orchestration¶

本質は順序依存。ステップAの出力がステップBの入力になる処理に使う。

顧客オンボーディングの例では、アカウント作成 → 支払い設定 → サブスクリプション作成 → ウェルカムメール送信の4ステップを順に実行する。各ステップ間にはデータの依存関係（Step 1で得たcustomer_idをStep 3で使う等）がある。

設計上の要点は、ステップ間の依存関係を明示すること、各ステージでのバリデーションを入れること、そして失敗時のロールバック手順を記述しておくことの3つ。特にロールバックの記述は見落としやすい。

パターン2：Multi-MCP Coordination¶

本質はMCP横断。1つのワークフローが複数の外部サービスをまたぐときに使う。

公式ガイドが示す「デザインハンドオフ」の例がわかりやすい。

Phase 1: Figma MCP からデザインアセットをエクスポート
Phase 2: Drive MCP にアップロード
Phase 3: Linear MCP に開発タスクを作成しアセットリンクを添付
Phase 4: Slack MCP にハンドオフサマリーを投稿

設計上の要点は、フェーズ間を明確に分離すること、MCP間でデータを渡す方法を定義すること、そして次フェーズに進む前にバリデーションを挟むこと。あるフェーズのMCP障害が後続に波及しないよう、集中的なエラーハンドリングも必要になる。

本質は改善ループ。一発で品質を出すのではなく、検証→修正を繰り返して品質を上げる。

典型的な流れは以下の通り。

データ取得 → 初稿生成
バリデーションスクリプトで品質チェック
問題箇所を修正 → 再バリデーション
品質閾値を満たすまで繰り返す

設計上の要点は、品質基準を明示的に定義すること、バリデーションをスクリプト（scripts/check_report.py等）で実装すること、そして終了条件を明記すること。終了条件がないと無限ループに陥る。公式ガイドの「決定論的処理はスクリプト化」の原則がここで特に重要になる。

パターン4：Context-aware Tool Selection¶

本質は条件分岐。同じ「保存」でも、入力の性質に応じて最適なツールが変わる場面に使う。

ファイル保存の例では、10MB超のファイルはクラウドストレージMCP、共同編集ドキュメントはNotion/Docs MCP、コードファイルはGitHub MCP、一時ファイルはローカルストレージ、というようにファイルの種類とサイズで振り分ける。

設計上の要点は、判断基準を決定木として明確に記述すること、フォールバック先を用意すること、そしてなぜその選択をしたかをユーザーに説明する指示を含めること。透明性の確保がこのパターンでは特に重視されている。

パターン5：Domain-specific Intelligence¶

本質は業務知識。ツールアクセスだけでは足りず、専門領域のルールや判断基準がないと正しく動けない処理に使う。

公式ガイドの金融コンプライアンスの例では、トランザクション処理の「前」にコンプライアンスチェック（制裁リスト確認、管轄許可の検証、リスクレベル評価）を実行し、結果を記録してから実際の処理に進む。処理後には監査証跡を生成する。

設計上の要点は、ドメイン知識をロジックとして組み込むこと、「アクション前のチェック」を徹底すること、そして監査・コンプライアンス用のドキュメント生成を最終ステップに含めること。ガバナンス要件のある業務に特に適合する。

パターン選択の判断基準¶

判断軸	推奨パターン
ステップの順序が固定されている	Pattern 1: Sequential
複数の外部サービスを横断する	Pattern 2: Multi-MCP
出力品質をスクリプトで検証できる	Pattern 3: Iterative Refinement
入力条件で使うツールが変わる	Pattern 4: Context-aware
業務ルール・法規制の知識が必要	Pattern 5: Domain-specific

実際のSkillでは複数パターンを組み合わせるケースも多い。たとえばMulti-MCP Coordination（Pattern 2）の各フェーズ内部でIterative Refinement（Pattern 3）を適用するといった構成は自然な組み合わせとなる。

3大トラブルのデバッグ手法¶

Skillを作って動かしてみると、大きく3つのカテゴリの問題に遭遇する。公式ガイドのトラブルシューティングセクションから、対処法を整理する¹。

トラブル1：Skillが発動しない（Under-triggering）¶

最も多い原因は description フィールドの記述不足。Claudeの自動発動判断はフロントマター全体に依存するが、その中でも特に description が中核を担っている。曖昧な説明ではマッチしない。

公式推奨のデバッグ手法： Claudeに直接聞く。

"When would you use the [skill name] skill?"

Claudeは description をそのまま引用して回答する。この回答を見れば、どのキーワードが不足しているか、トリガー条件がどう解釈されているかが即座にわかる。descriptionの改善 → 再質問のサイクルで精度を上げられる。

公式ガイドのチェックリストは以下の3点。

記述が漠然としていないか（「Helps with projects」では発動しない）
ユーザーが実際に使うフレーズが含まれているか
関連するファイル形式が記載されているか（該当する場合）

トラブル2：Skillが発動しすぎる（Over-triggering）¶

無関係なクエリでSkillがロードされる場合は、descriptionの範囲が広すぎる。

公式推奨の対策：Negative triggers（否定トリガー）の追加。

# 公式ガイドの例を日本語訳したもの（原文は英語）
description: CSVファイルの高度なデータ分析用。統計モデリング、
  回帰分析、クラスタリングに使用。単純なデータ探索には使用しない
  （そちらはdata-vizスキルを使うこと）。

使用しない（○○） のように否定条件を明記することで、類似タスクとの境界を明確にできる。さらに対象ドメインを限定する（「ドキュメントを処理」→「契約レビュー用のPDF法務ドキュメントを処理」）ことで、発動範囲を絞り込む。

トラブル3：発動するが指示通り動かない¶

Skillはロードされるのに、期待した手順で実行されない場合。公式ガイドは4つの原因を挙げている。

原因a：指示が冗長すぎる。 SKILL.md本文が長すぎると、重要な指示が埋もれる。核となる手順だけを本文に残し、詳細なリファレンスは references/ に分離する。目安として、本文は肥大化させないことが重要で、標準仕様・公式ガイドともに5,000前後を上限の目安としている²。

原因b：重要な指示が埋もれている。 ## Important や ## Critical のようなヘッダーで強調し、必要であれば重要ポイントを繰り返し記述する。

原因c：指示が曖昧。 「Make sure to validate things properly」ではなく、「CRITICAL: Before calling create_project, verify: Project name is non-empty / At least one team member assigned / Start date is not in the past」のように検証項目を列挙する。

原因d：モデルの"手抜き"傾向。 公式ガイドが認めている興味深い知見として、以下のような励まし文言が有効とされている。

- Take your time to do this thoroughly
- Quality is more important than speed
- Do not skip validation steps

ただし公式は、この種の文言はSKILL.md内ではなくユーザープロンプト側に入れた方が効果的と注記している¹。Skill本文はあくまで手順とルールに集中させ、動機づけはプロンプト層で行うという使い分けの指針だ。

テスト方法論：Skillの品質を定量評価する¶

公式ガイドはSkillのテストを3軸で整理している¹。定量的な目標値も提示されているが、これらは厳密な閾値ではなく「aspirational targets」（目安となる目標）と位置づけられている点に注意が必要。

軸1：Triggering tests（発動精度テスト）¶

10〜20個のテストクエリを用意し、Skillが自動発動するかを確認する。目標ヒット率は90%。同時に、無関係なクエリで発動しないことも検証する。

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"

軸2：Functional tests（機能テスト）¶

期待する出力が得られるか、APIコールが成功するか、エラーハンドリングが機能するかを検証する。同一リクエストを3〜5回実行し、出力の構造的一致度と品質を確認する。

軸3：Performance comparison（性能比較）¶

Skill有無での定量比較を行う。公式ガイドが示す比較例は以下の通り。

指標	Skillなし	Skillあり
やりとり回数	15往復	確認質問2回のみ
APIエラー	3回（リトライ要）	0回
トークン消費	12,000	6,000

この比較フレームワークは、Skillの導入効果をステークホルダーに説明する際にも活用できる。

テストの実施手段¶

公式ガイドは3段階の手段を提示している。

手動テスト（Claude.ai）： クエリを直接実行して挙動を観察。セットアップ不要で最速
スクリプトテスト（Claude Code）： テストケースを自動化し、変更ごとに再検証
プログラマティックテスト（Skills API）： 評価スイートを構築し、テストセットに対して体系的に実行

Skill用途が社内の小規模チームか、大規模エンタープライズかでテストの深度を使い分ける判断が推奨されている。

見落としやすい4つの運用ポイント¶

設計パターンとデバッグ以外にも、ガイド本文には実装前に押さえておきたい知見がある。

「1つの難しいタスクで先にイテレーションせよ」¶

公式のPro Tipとして、最初から幅広いテストケースに当てるのではなく、単一の困難なタスクでSkillが成功するまで磨き込むアプローチが推奨されている。成功パターンを確立してからSkillとして汎用化する方が、効率的にin-context learningを活用できるという考え方だ。

README.mdを入れてはいけない¶

Skillフォルダ内にREADME.mdを配置してはならない。ドキュメントはすべてSKILL.mdまたは references/ に格納する。ただしGitHubリポジトリとして配布する場合は、リポジトリのルートレベルにREADME（Skill外）を置くのは問題ない。

組織全体デプロイは2025年12月に出荷済み¶

管理者がSkillをワークスペース全体にデプロイする機能は、2025年12月18日時点で提供済みと公式ガイドに記載されている。「Coming Soon」と認識している場合は、すでに利用可能であることを確認されたい。

MCPとSkillsの関係：キッチンとレシピ¶

公式ガイドの比喩として、MCPは「プロフェッショナルキッチン」（ツール・食材・設備へのアクセス）、Skillsは「レシピ」（価値を生み出すためのステップバイステップの手順）と位置づけられている。MCPだけではユーザーは「次に何をすべきか」がわからず、サポートチケットが増え、毎回ゼロから会話が始まる。Skillsがあることで、ベストプラクティスがすべてのインタラクションに組み込まれ、学習曲線が下がるという構図だ。

まとめ¶

公式ガイド全33ページから抽出した実装判断の芯は4つ。

最初に決めるのは Problem-first か Tool-first か
実装は 5パターンのどれに近いかで考える
発動不良は "When would you use this skill?" で詰める
効果は Triggering / Functional / Performance の3軸で測る

本記事で扱わなかった配布戦略やAPIリファレンスなど、全体像は公式ガイド原典を参照されたい¹。