Claude Skills構築の完全ガイド

• Claude Skills は、反復される作業フローを一度定義して 継続的に再利用 できるよう設計されたワークフロー知識パッケージ
• Anthropic が直接作成した 33ページのPDFガイド で、スキル設計から 構造化、テスト、デプロイ まで全工程を段階的に扱う
• 単独のワークフロー自動化から MCP ベースのツール統合強化 まで、幅広い活用シナリオを含む
• 実際の運用環境で検証されたパターンと失敗事例をもとに作成されている
• 上位2〜3個のワークフローが整理されていれば、最初のスキルは 15〜30分以内 に構築・テスト可能

---

Introduction

• このガイドは、Claude Skills を 一回限りのプロンプトではなく、繰り返し使えるワークフロー資産 として扱うことを目的としている
• Skills は、特定の作業やプロセスを Claude に一度教え、その後のすべての対話で 一貫して再利用 できるように設計された構造として定義される
• ユーザーの好み、作業方式、ドメイン知識を毎回説明しなくてよくなるため、認知的・運用的コストを大幅に削減 できる

• Skills が特に効果的な場面

  • Skills は 反復可能で構造化された作業 で最も大きな効果を発揮する
    • 仕様に基づくフロントエンドデザインの生成
    • 一定の方法論に従うリサーチの実施
    • チームのスタイルガイドを反映した文書作成
    • 複数段階にまたがる複合プロセスのオーケストレーション
  • Claude の組み込み機能（コード実行、文書生成など）と自然に組み合わせられる

• MCP と Skills の役割分担

  • MCP 統合を使う場合、Skills は単なるツール接続を超えて ワークフローを安定化する追加レイヤー として説明される
  • MCP が「何ができるか」を提供するなら、Skills は「どう実行すべきか」を固定する役割を担う
  • これにより、生のツールアクセスを 信頼できる自動化体験 に変換できる

• ガイドの目的と範囲

  • この文書は Skills 構築に必要な全工程を網羅する
    • 事前計画と構造設計
    • 実際の作成方法
    • テストと反復改善
    • デプロイと共有
  • 個人用スキル、チーム内標準スキル、コミュニティ共有向けスキルまで あらゆる活用範囲 を対象とする
  • 理論説明よりも 実務で検証されたパターンと例 を中心に構成されている

• 想定読者

  • Claude に特定のワークフローを 常に同じ方法で実行してほしい開発者
  • 反復作業の自動化を望むパワーユーザー
  • 組織単位で Claude の使い方を標準化しようとするチーム
  • MCP コネクタにワークフロー知識を組み合わせたいビルダー

• ガイドの活用ルート

  • 単独の Skills 構築が目的なら:
    • Fundamentals
    • Planning and Design
    • Category 1–2 を中心に参照することを推奨
  • MCP 統合の強化が目的なら:
    • Skills + MCP セクション
    • Category 3 を中心に活用することを推奨
  • 両ルートは技術要件を共有しており、必要な部分だけを選択的に適用可能 である

• 期待される結果

  • このガイドに沿って進めれば、1回のセッションで実用的な Skill を1つ完成 できるよう設計されている
  • 上位2〜3個の明確なワークフローがある場合、最初の Skill は 約15〜30分以内に構築・テスト可能
  • Introduction では、以降のすべての章の前提となる中核的な視点、すなわち
    「Skills はプロンプトではなく、再利用可能な作業知識である」 という認識を明確にする

Chapter 1: 基本概念 (Fundamentals)

• Claude Skills を理解するための 概念的土台と設計哲学 を説明する
• Skills を単なるプロンプトの束ではなく、継続的に再利用される作業知識の単位 として定義し
• 以降の章で扱う設計・テスト・デプロイの議論の前提となる重要原則を整理する

• Skill とは何か

  • Skill は、Claude に特定の作業やワークフローの実行方法を 一度教えて繰り返し使える ようにする構造
  • ユーザーの好み、手順、ドメイン知識を毎回説明しなくてよいよう設計されている
  • 反復性の高い作業で最も大きな効果を発揮する
  • 例:
    • 仕様ベースのフロントエンドデザイン生成
    • 一貫した方法でのリサーチ実施
    • チームのスタイルガイドに従う文書作成
    • 多段階プロセスの自動実行

• Skill の基本構成要素

  • Skill は1つのフォルダ単位で構成される
  • 必須構成:
    • SKILL.md: YAML frontmatter と Markdown の指示を含む中核ファイル
  • 任意構成:
    • scripts/: Python、Bash などの実行コード
    • references/: 必要に応じて参照される文書やガイド
    • assets/: 出力物に使われるテンプレート、リソース
  • この構造は、シンプルさと拡張性を同時に満たすよう設計されている

• 中核設計原則 1: Progressive Disclosure

  • Skills は 3段階の情報ロード構造 に従う

  • 第1段階: YAML frontmatter

    • Claude のシステムプロンプトに常にロードされる
    • スキルをいつ使うべきか判断するための最小限の情報だけを含む
    • 不要なコンテキスト読み込みを防ぐ役割を果たす

  • 第2段階: SKILL.md 本文

    • Claude がそのスキルが関連すると判断したときにロードされる
    • 実際の作業手順と指示が含まれる

  • 第3段階: 関連ファイル

    • references、scripts、assets など
    • Claude が必要だと判断した場合にのみ探索する
    • トークン使用量を最小限に抑えながら専門性を維持する
  • この構造により、コンテキストコストと作業精度のバランス を実現する

• 中核設計原則 2: Composability

  • Claude は複数の Skills を同時にロードできる
  • したがって各 Skill は:
    • 単独実行を前提としてはいけず
    • 他の Skill と衝突しないように設計されるべきである
  • スキル同士が協調できる環境を基本前提とする

• 中核設計原則 3: Portability

  • Skills は Claude.ai、Claude Code、API 環境で同様に動作するよう設計されている
  • 一度作った Skill を プラットフォームごとの修正なしで再利用 できる
  • ただし、スクリプトやネットワークアクセスなどは実行環境の制約を受ける

• MCP と Skills の関係

  • MCP を使う場合、Skills は 知識レイヤー (knowledge layer) の役割を果たす
  • MCP はツールとデータアクセスを提供する
  • Skills はそのツールを どのように使うべきか を定義する

  • キッチンの比喩

    • MCP: キッチン、食材、調理器具
    • Skills: レシピ
    • 両者が組み合わさると、ユーザーは複雑な過程を自分で設計しなくてよくなる

• MCP なしで使う場合

  • MCP がなくても Skills は十分に有用である
  • Claude の組み込み機能（文書生成、コード実行など）だけでも:
    • 反復作業の標準化
    • 品質の一貫性確保
    • 作業速度の改善 が可能

• この章の重要メッセージ

• Skills は短期的なプロンプト最適化ではなく、継続的に蓄積される作業資産 である
• 「何ができるか」よりも「どう実行すべきかを固定すること」が核心である
• 以降の章では、この概念を土台として、実際の設計・運用段階へと拡張していく

第2章: 計画と設計（Planning and Design）

• この章は、Skills構築の成否が作成段階以前の設計品質でほぼ決まることを前提としている

• 技術実装より先に、どの問題を解決するのか、どのようなフローを固定するのかを明確にする必要がある

• 適切に設計されたSkillは実装が単純になり、テストと保守のコストも大幅に減る

• 出発点: ユースケース定義

  • スキルを作成する前に、必ず**2〜3個の具体的なユースケース（use case）**を定義しなければならない
  • ユースケースには抽象的な目的ではなく、実際のユーザーが話す文と結果まで含める必要がある

  • 良いユースケースの構成要素

    • ユーザーが達成したい目標
    • ユーザーが言いそうなトリガー文
    • 内部的に実行すべき段階的な作業
    • 使用するツール（Claudeの基本機能またはMCP）
    • 最終的な結果の状態
  • 例を通じて、「スプリント計画策定」のように開始条件–処理段階–完了状態が明確な定義の重要性を強調している

• 設計前に自問すべき重要な質問

  • ユーザーは何を終えたいのか
  • その結果のためにどのような多段階ワークフローが必要か
  • どの段階でどのツールが必要か
  • 人の判断が必要なドメイン知識やベストプラクティスをどこに内在化するか
  • これらの質問に明確に答えられないなら、Skillとして固定する準備ができていない状態である

• 観察された主要なSkillユースケースの種類

  • Category 1: ドキュメントおよびアセット生成

    • 一貫した品質が重要な成果物の生成に使われる
    • ドキュメント、プレゼンテーション、デザイン、コード、UI成果物などが含まれる
    • 特徴:
      • スタイルガイドとブランドルールを内蔵
      • 出力テンプレートを活用
      • 最終品質チェックリストを含む
    • 外部ツールなしでClaudeの基本機能だけで完結可能

  • Category 2: ワークフロー自動化

    • 複数の段階を繰り返し実行しなければならないプロセスに適している
    • 例: skill-creator
    • 特徴:
      • 段階ごとの進行と検証ポイントを含む
      • 構造化されたテンプレートを提供
      • 中間レビューと改善ループを内蔵
    • 結果よりもプロセスの安定性を重視する類型として説明されている

  • Category 3: MCP強化

    • MCPサーバーが提供するツールアクセスを実際に使えるワークフローへ変換する
    • 特徴:
      • 複数のMCP呼び出しを順番に組み合わせる
      • ユーザーが直接明示しなくてもよいコンテキストを自動で補完
      • MCPエラー状況への処理を内蔵
    • 単純な自動化ではなく、専門化された利用方法のカプセル化と定義されている

• 成功基準定義の重要性

  • Skillは「うまく動いているように見える」ことではなく、改善効果があるかどうかで評価すべきである
  • 成功基準は精密な数値ではなく、方向性を持つ基準として提示される

  • 定量的基準

    • 意図されたリクエストの大半で自動的にトリガーされる
    • スキル使用時にツール呼び出し回数とトークン使用量が減少する
    • MCP呼び出し失敗なしにワークフローを完了する

  • 定性的基準

    • ユーザーが次の段階を指示しなくても進行する
    • 繰り返し実行しても結果の構造と品質が一貫している
    • 新規ユーザーでも最初の試行で成功できる
  • 評価にはある程度**感覚的判断（vibes）**が含まれる可能性を認めつつ、比較基準は維持すべきことを明示している

• 技術要件の概要

  • Skillは固定されたディレクトリ構造に従わなければならない
  • SKILL.mdファイルは必須であり、名前は正確に一致していなければならない
  • フォルダ名とnameフィールドにはkebab-caseを使用する
  • Skillフォルダ内部にREADME.mdは置かない

• YAML frontmatterの役割

  • frontmatterはClaudeがスキルをいつロードするか判断する中核シグナルである
  • 最低限必要なフィールド:
    • name
    • description
  • descriptionには必ず次を含めなければならない:
    • スキルが何をするのか
    • いつ使うのか
    • ユーザーが言いそうな具体的表現
  • 技術的説明よりユーザー観点の言葉が重要である

• frontmatter設計原則

  • 1024文字以内に保つ
  • XMLタグの使用禁止
  • セキュリティ上の理由で特定の名前（claude、anthropic）の使用を制限
  • メタデータは任意だが、バージョン・作成者情報の記載を推奨

• SKILL.md本文の設計方針

  • 段階ごとに明確で実行可能な指示を提供
  • 例と期待結果をあわせて提示
  • よく発生するエラーと解決方法を含める
  • 過度な説明はreferencesディレクトリに分離

• Chapter 2の核心は、Skillsを「プロンプトの束」ではなく、意図を持ったワークフロー設計の成果物として扱うべきだという点にある

第3章: テストと反復改善 (Testing and Iteration)

• 本章は、Skillsを実際に信頼できるレベルまで引き上げるプロセスに焦点を当てる
• スキルは作成そのものよりも、いつロードされ、どのように実行され、結果が改善されるかを検証するプロセスが中核
• 利用範囲と影響度に応じてテスト強度を調整すべき点が重要

• テストレベルの選択

  • Skillsのテストは、求められる品質と配布範囲に応じて異なるレベルで実施できる

  • 手動テスト (Claude.ai)

    • Claude.aiで直接クエリを入力して動作を確認
    • 追加設定なしで素早い反復が可能
    • 初期設計の検証と迅速な修正に適している

  • スクリプトベースのテスト (Claude Code)

    • Claude Code環境でテストケースを自動化
    • 変更が蓄積する場合、回帰テストに有用
    • 内部チーム向けスキルに適している

  • APIベースのプログラムテスト

    • Skills APIを活用して定義済みテストセットを自動実行
    • 定量的比較と体系的な検証が可能
    • 大規模配布、エンタープライズ環境に適している
• 内部向けの小規模スキルと外部公開スキルでは、同一のテスト基準を必要としない

• 推奨アプローチ: まず1つの難しい作業から

  • 効果的なスキル制作者は、1つの難しい作業に集中して反復改善する
  • Claudeがその作業を安定して成功させる瞬間のアプローチを抽出し、Skillとして固定する
  • 幅広いテストよりも、強いシグナルを与える単一事例の反復のほうがより速い学習をもたらす
  • その後で初めて、さまざまなケースへ拡張したテストを実施する

• 主要なテスト領域

  • 1. トリガーテスト

    • 目的: スキルが適切な状況でのみ自動ロードされるかを検証
    • 含まれる項目:
      • 明確なリクエストでトリガーされる
      • 表現が変わったリクエストでもトリガーされる
      • 無関係なリクエストではロードされない
    • トリガー品質はdescriptionフィールドの設計と直結する

  • 2. 機能テスト

    • 目的: スキルが意図した結果を正確に生成するかを確認
    • 検証対象:
      • 出力結果の正確性
      • MCP呼び出しの成功可否
      • エラー処理の動作
      • エッジケースへの対応
    • 単純な成功可否ではなく、ワークフロー全体の完結性を基準に評価する

  • 3. 性能比較テスト

    • 目的: スキル使用前後の実質的な改善効果を確認
    • 比較項目:
      • メッセージ往復回数
      • MCP呼び出し失敗の有無
      • 総トークン使用量
    • スキルは「動作する」ではなく「より良くなる」ことを証明しなければならない

• skill-creatorを活用したテストと改善

  • skill-creatorはスキル設計と改善を支援するメタツール
  • 主な機能:
    • 自然言語の説明に基づくスキル草案の生成
    • SKILL.md形式とfrontmatterの自動生成
    • トリガー過多/不足リスクの検出
    • 目的に合ったテストケースの提案
  • 実行テストや定量評価を置き換えるものではない

• フィードバックに基づく反復改善

  • Skillsは固定的な成果物ではなく、継続的に磨き込むべき対象

  • トリガー不足のシグナル

    • スキルが自動でロードされない
    • ユーザーが手動でスキルを有効化する
    • 「これはいつ使うのか」という質問が発生する
    • 解決策: descriptionに具体的な表現と用語を追加

  • トリガー過多のシグナル

    • 無関係な質問でもスキルがロードされる
    • ユーザーがスキルを無効化するケースが発生する
    • 目的の混乱が生じる
    • 解決策: 範囲の縮小、否定トリガーの追加

  • 実行上の問題のシグナル

    • 結果の一貫性が不足する
    • MCPエラーまたは再試行が発生する
    • ユーザーによる修正介入が必要
    • 解決策: 指示の明確化、エラー処理の強化

• テスト段階の重要メッセージ

  • テストはスキルの正確性だけでなく信頼性を検証するプロセス
  • 「スキルが実行される」という基準では不十分
  • 「ユーザーが次の指示を出さなくても最後まで完遂できるか」が最終判断基準
• Chapter 3は、Skillsを実験的なツールから運用可能なワークフロー資産へと転換する段階

第4章: 配布と共有 (Distribution and Sharing)

• SkillsはMCPコネクタの価値を完成させる要素であり、同じツール接続であっても、スキルが併せて提供される場合のほうがより速く価値に到達できる
• ユーザーの立場では、MCPだけが提供されるコネクタよりも、すぐに実行可能なワークフローを含むコネクタが好まれる傾向がある
• この章では、2026年1月時点の配布方式、組織単位での配布、API活用、そして推奨運用戦略を整理する

• 現在の配布モデル（2026年1月時点）

  • 個人ユーザー向けの配布方式

    • Skillフォルダをローカルにダウンロード
    • 必要に応じてフォルダ全体をzipファイルに圧縮
    • Claude.aiで Settings → Capabilities → Skills の経路からアップロード
    • またはClaude Code環境のskillsディレクトリに直接配置
    • アップロード後、ユーザーが直接スキルを有効化する必要がある

  • 組織単位での配布

    • 管理者がワークスペース全体にスキルを配布可能
    • 2025年12月18日から組織単位配布機能を提供
    • 集中管理と自動アップデートをサポート
    • 組織内の標準ワークフローを強制または一貫して維持するのに適している

• オープンスタンダードとしてのSkills

  • Agent SkillsはMCPと同様にオープンスタンダードとして公開されている
  • 特定のプラットフォームに依存せず、同じスキルが複数のAIツールで動作することを目標としている
  • 一部のスキルは特定プラットフォームの機能を積極的に活用でき、この場合 compatibility フィールドに環境上の制約を明記できる
  • エコシステム参加者との協業を通じて標準を発展させている最中である

• APIを通じたSkills活用

  • API活用の目的

    • アプリケーション、自動化パイプライン、エージェントシステムなど、プログラムベースの利用シナリオに適している
    • UIを通じた手動利用ではなく、システムレベルでスキルを制御できる

  • 主な機能

    • /v1/skills エンドポイントを通じてスキル一覧の取得および管理
    • Messages APIリクエスト時に container.skills パラメータでスキルを指定
    • Claude Consoleを通じたバージョン管理および配布制御
    • Claude Agent SDKと連携してカスタムエージェントを構成可能

  • 利用環境の選択ガイド

    • Claude.ai / Claude Code:
      • エンドユーザーによる直接利用
      • 開発中の手動テストと迅速な反復
      • 個人単位、不定期のワークフロー
    • API:
      • アプリケーションへの組み込み
      • 大規模な本番配布
      • 自動化されたエージェントおよびパイプライン

  • 注意事項

    • APIベースでSkillsを利用する場合、Code Execution Toolベータが必要
    • セキュアな実行環境が前提となる

• 推奨配布戦略

  • 1. GitHub公開リポジトリの運用

    • スキル自体は1つのフォルダとして管理
    • リポジトリルートには人向けのREADMEを提供
    • インストール方法、利用目的、サンプルスクリーンショットの記載を推奨
    • Skillフォルダ内部にはREADME.mdを含めない

  • 2. MCPドキュメントとの連携

    • MCPコネクタのドキュメントでSkillも併せて紹介
    • MCP単独利用と比べたSkill組み合わせ時の価値を明確に説明
    • クイックスタートガイドを提供

  • 3. インストールガイドの提供

    • スキルのダウンロード方法を明記
    • Claude.aiまたはClaude Codeにインストールする手順を段階的に案内
    • MCPサーバー接続の確認手順を含める
    • 簡単なテストプロンプト例を提供

• スキルのポジショニング原則

  • 機能ではなく結果中心の説明

    • 内部実装や技術構造の説明よりも、ユーザーが得る結果を強調
    • 時間短縮、エラー削減、一貫性の確保といった効果を前面に出す

  • MCP + Skillsの組み合わせが重要

    • MCPはツールへのアクセスを提供
    • Skillsはそのツールをどう使うべきかに関する知識を提供
    • 2つの要素が組み合わさることで、AIベースの自動化が完成する
• 配布と共有は単なる伝達ではなく、ユーザーがスキルの価値を理解し、すぐに活用できるようにするためのプロセスである

Chapter 5: パターンとトラブルシューティング (Patterns and Troubleshooting)

• この章では、初期のSkillsユーザーおよび社内チームの事例から、繰り返し効果が実証された設計パターンと、実運用で頻繁に発生する問題の解決方法を整理する
• ここで示すパターンは規範ではなく、検証済みアプローチの集合であり、各スキルの目的に合わせて選択・組み合わせることを前提とする
• 核心的なメッセージは「ツールをつなぐこと」ではなく、問題を解決する流れを設計することにある

• アプローチの選択: 問題中心 vs ツール中心

  • Skillsの設計では、2つの観点のうちどちらかを選ぶことが重要

  • 問題中心(Problem-first)

    • ユーザーは達成したい結果を伝える
    • スキルが内部で適切なMCPツールと呼び出し順序を決定する
    • 例: 「プロジェクトワークスペースを作って」→ スキルがすべてのツール呼び出しを処理
    • 結果志向の体験に適している

  • ツール中心(Tool-first)

    • ユーザーはすでにMCP接続を理解している
    • スキルはそのツールをどう上手く使うかに関する専門知識を提供する
    • 例: Notion MCPの使い方、最適なワークフロー案内
    • 熟練ユーザーや社内ツールガイドに適している
• ほとんどのスキルはこのどちらかにより近く、これを明確に認識することが設計品質を左右する

• パターン1: 順次ワークフローオーケストレーション

  • 決められた順序で複数の段階を必ず実行しなければならない場合に適している
  • 各段階は前段階の結果に依存する
  • 段階ごとの検証や、失敗時のロールバック指針を含めることもできる
  • オンボーディング、アカウント作成、サブスクリプション設定のような業務に適している

• パターン2: 複数MCPの連携

  • 1つの結果のために複数のサービス(MCP)を連続して使う必要がある場合
  • 段階ごとにMCPを分離し、データ受け渡しの流れを明確に定義する
  • 次の段階へ進む前に検証が必須
  • デザイン → 保存 → タスク作成 → 通知のような複合ワークフローに適している

• パターン3: 反復的改善(Iterative Refinement)

  • 初期結果よりも反復によって品質が大きく改善する作業に適している
  • 下書き作成 → 検証 → 修正 → 再検証のループを明示的に設計する
  • 品質基準と反復終了条件を明確に定義しなければならない
  • レポート作成や文書品質改善の作業に効果的

• パターン4: 状況認識に基づくツール選択

  • 同じ目標でも状況に応じて最適なツールが変わる場合に使う
  • ファイルサイズ、タイプ、共同作業の有無など、明確な判断基準が必要
  • 選択理由をユーザーに説明して信頼性を確保する
  • ストレージ、ドキュメント管理、コード保存のフローに適している

• パターン5: ドメイン特化型インテリジェンスの内蔵

  • 単純なツール呼び出しを超えて、専門知識とルールを内在化したスキル
  • 作業実行前の判断・検証段階が核心
  • すべての意思決定過程を記録し、監査証跡を残せる
  • 金融、コンプライアンス、セキュリティなど高リスク領域に適している

• トラブルシューティングガイド

  • アップロード失敗

    • SKILL.md のファイル名が正確でない場合に発生する
    • YAML区切り文字(---)の欠落、引用符の閉じ忘れなどの形式エラーが原因
    • name フィールドに大文字や空白が含まれているとアップロードは拒否される

  • スキルがトリガーされない場合

    • description が抽象的すぎる、またはユーザー表現を反映できていない場合
    • 実際のユーザーが言いそうな文言を含むよう修正が必要
    • Claudeに「このスキルはいつ使うのか」と尋ねてデバッグできる

  • スキルが過度にトリガーされる場合

    • 範囲が広すぎる description が原因
    • 否定トリガー(Do NOT use when…)を追加する
    • 対象と除外対象を明確に区別する

  • MCP呼び出し失敗

    • MCPサーバーの接続状態を確認
    • 認証情報(APIキー、OAuthトークン)を点検
    • スキルなしでMCP単独呼び出しを行い、問題原因を切り分ける
    • ツール名の大文字・小文字が正確か確認する

  • 指示がうまく守られない場合

    • 指示が長すぎる、または要点が埋もれている場合
    • 重要な条件は上部に配置し、繰り返し強調する
    • 曖昧な表現ではなく、検証可能な条件リストを使う
    • 重要な検証はスクリプトとして実装するほうがより安定的

  • 大規模コンテキストによる性能低下

    • SKILL.md が過度に大きい場合に発生する
    • 詳細文書は references に分離する
    • 同時に有効化されたスキル数が多すぎる場合は削減を推奨
    • 20〜50個を超えるスキルの同時有効化では性能低下の可能性がある
• 「スキルは一度作って終わりのartefactではなく、パターン選択と反復的改善を通じて成熟していく運用対象である」

[kaydash]

Anthropicは本当に最高だ

[pluto]

本当に