Claudeスキル構築完全ガイド（和訳・要約）¶

📁 docs/it-learning/artifact/claude-skill-guide.md

原文: The Complete Guide to Building Skills for Claude 翻訳・要約日: 2026-03-12

目次¶

はじめに
基礎知識
計画と設計
テストと反復改善
配布と共有
パターンとトラブルシューティング
リソースと参考資料
付録：クイックチェックリスト
付録：YAMLフロントマター全フィールド

1. はじめに¶

スキルとは、Claudeに特定のタスクやワークフローを教えるための「フォルダとしてパッケージされた指示セット」。

スキルが有効な場面¶

繰り返し発生するワークフロー（フロントエンド設計生成、一貫した調査手法、チームのスタイルガイドに沿ったドキュメント作成、マルチステッププロセスの自動化）
Claudeの組み込み機能（コード実行、ドキュメント作成）との組み合わせ
MCPとの組み合わせ：生のツールアクセスを信頼性の高いワークフローに変換

このガイドから学べること¶

スキル構造のベストプラクティスと技術的要件
スタンドアローンスキルとMCP強化ワークフローのパターン
テスト・反復・配布の方法

2つの進め方¶

スタンドアローン構築派 → 「基礎」「計画と設計」「カテゴリ1〜2」を中心に読む
MCP強化派 → 「スキル+MCP」セクションと「カテゴリ3」が中心

2. 基礎知識¶

スキルの構成要素¶

your-skill-name/
├── SKILL.md          # 必須：YAMLフロントマター付きのMarkdown指示ファイル
├── scripts/          # 任意：実行可能コード（Python, Bash等）
├── references/       # 任意：必要に応じてロードされるドキュメント
└── assets/           # 任意：テンプレート、フォント、アイコン等

コア設計原則¶

プログレッシブ・ディスクロージャー（段階的開示）¶

スキルは3段階のシステムを使用する：

レベル	場所	内容
1段目	YAMLフロントマター	常にシステムプロンプトにロード。スキルをいつ使うか判断するための最小情報
2段目	SKILL.md本文	関連ありと判断したときにロード。完全な指示とガイダンス
3段目	リンクファイル	必要に応じてのみ読み込む追加ファイル

→ トークン使用量を最小化しながら専門知識を維持

コンポーザビリティ（組み合わせ可能性）¶

Claudeは複数のスキルを同時にロードできる。他のスキルの存在を前提としない設計を心がける。

ポータビリティ（移植性）¶

Claude.ai、Claude Code、APIいずれでも同一動作。一度作れば全サーフェスで機能する。

MCPとスキルの関係¶

MCP（接続性）	スキル（知識）
サービスへの接続（Notion、Asana、Linear等）	サービスの使い方を教える
リアルタイムデータアクセスとツール起動	ワークフローとベストプラクティスを記録
「Claudeが何をできるか」	「Claudeがどうすべきか」

キッチンの例え：MCPはプロキッチン（道具・食材・設備）、スキルはレシピ（価値あるものを作る手順）。

3. 計画と設計¶

ユースケースから始める¶

コードを書く前に、具体的なユースケースを2〜3個特定する。

良いユースケース定義の例：

ユースケース: スプリント計画
トリガー: 「このスプリントの計画を手伝って」「スプリントタスクを作成して」
ステップ:
  1. Linearから現在のプロジェクト状況を取得（MCP経由）
  2. チームの速度と capacity を分析
  3. タスク優先度を提案
  4. ラベルと見積もり付きでLinearにタスクを作成
結果: 完全に計画されたスプリントとタスク作成

3つの共通ユースケースカテゴリ¶

カテゴリ1: ドキュメント・アセット作成¶

目的: ドキュメント、プレゼン、アプリ、デザイン、コード等の高品質な成果物を一貫して作成
例: frontend-designスキル
テクニック:
スタイルガイドとブランド基準の埋め込み
一貫した出力のためのテンプレート構造
完成前のクオリティチェック
外部ツール不要（Claudeの組み込み機能を活用）

カテゴリ2: ワークフロー自動化¶

目的: 一貫した手法による複数ステップのプロセス（複数MCPサーバーにまたがる協調も含む）
例: skill-creatorスキル
テクニック:
バリデーションゲート付きのステップバイステップワークフロー
共通構造のテンプレート
組み込みのレビューと改善提案
反復的な改善ループ

カテゴリ3: MCP強化¶

目的: MCPサーバーが提供するツールアクセスを強化するワークフローガイダンス
例: sentry-code-reviewスキル（Sentryによる）
テクニック:
複数MCPコールの順次調整
ドメイン専門知識の埋め込み
ユーザーが指定しなくても済むコンテキスト提供
共通MCPエラーのハンドリング

成功基準の定義¶

定量的指標： - スキルが関連クエリの90%でトリガー - ワークフローをX回のツールコールで完了 - APIコール失敗率0

定性的指標： - ユーザーが次のステップを指示しなくてよい - ユーザー修正なしでワークフロー完了 - セッション間で一貫した結果

技術的要件¶

必須ルール¶

項目	正	誤
ファイル名	`SKILL.md`（大文字小文字厳密）	`SKILL.MD`, `skill.md`
フォルダ名	`notion-project-setup`（ケバブケース）	`Notion Project Setup`（スペース不可、大文字不可）
README.md	スキルフォルダ内に入れない	スキルフォルダにREADME.md を配置

YAMLフロントマター（最重要部分）¶

最小限の必須形式：

---
name: your-skill-name
description: 何をするか。[具体的なフレーズ]でユーザーが聞いたときに使う。
---

nameフィールド： - ケバブケースのみ - スペース・大文字なし - フォルダ名と一致させる

descriptionフィールド： - 「何をするか」と「いつ使うか（トリガー条件）」の両方を必ず含める - 1024文字以内 - XMLタグ（<または>）禁止 - ユーザーが実際に言いそうな具体的なフレーズを含める

セキュリティ制約： - フロントマター内でXML角括弧（< >）は使用不可 - 名前に"claude"や"anthropic"を含めてはいけない（予約済み）

良い・悪いdescriptionの例¶

良い例：

# 具体的でアクション可能
description: FigmaデザインファイルをAnalysisし、開発者向けハンドオフドキュメントを生成。
  .figファイルのアップロード時、「デザイン仕様書」「コンポーネントドキュメント」を求めるときに使用。

# トリガーフレーズを含む
description: Linearプロジェクトワークフローを管理（スプリント計画、タスク作成、ステータス管理）。
  「スプリント」「Linearタスク」「プロジェクト計画」や「チケットを作って」というときに使用。

悪い例：

# 漠然としすぎ
description: プロジェクトの支援をします。

# トリガーなし
description: 高度なマルチページドキュメントシステムを作成します。

指示文の推奨構造¶

---
name: your-skill
description: [...]
---

# スキル名

## ステップ1: [最初の主要ステップ]
何が起きるかの明確な説明。

## 例
### 例1: [一般的なシナリオ]
ユーザーが言う: "新しいマーケティングキャンペーンを設定して"
アクション:
1. MCPで既存キャンペーンを取得
2. 指定パラメータで新キャンペーン作成
結果: 確認リンク付きでキャンペーン作成完了

## トラブルシューティング
エラー: [一般的なエラーメッセージ]
原因: [なぜ発生するか]
解決策: [修正方法]

指示文のベストプラクティス： - 具体的でアクション可能に: 「データを検証してから進む」ではなく、具体的なコマンドと期待する出力を書く - エラーハンドリングを含める: 接続失敗、認証エラーの対処手順を記載 - バンドルリソースを明示的に参照: references/api-patterns.md を参照するよう明示 - プログレッシブ・ディスクロージャーを使う: SKILL.md はコア指示に集中、詳細は references/ に移動

4. テストと反復改善¶

3段階のテストレベル¶

レベル	方法	特徴
手動テスト	Claude.aiで直接実行	高速な反復、セットアップ不要
スクリプトテスト	Claude Code で自動化	変更間の再現性あり
プログラムテスト	Skills API 経由	システマチックな評価スイート

推奨テスト手法¶

1. トリガーテスト¶

トリガーすべき:
- "新しいProjectHubワークスペースのセットアップを手伝って"
- "ProjectHubにプロジェクトを作成したい"

トリガーすべきでない:
- "サンフランシスコの天気は？"
- "Pythonコードを書いて"

2. 機能テスト¶

テスト: 5タスクでプロジェクトを作成
条件: プロジェクト名「Q4 Planning」、5件のタスク説明
実行時: スキルがワークフローを実行
期待:
  - ProjectHubにプロジェクトが作成される
  - 正しいプロパティで5タスクが作成される
  - 全タスクがプロジェクトにリンクされる
  - APIエラーなし

3. パフォーマンス比較¶

指標	スキルなし	スキルあり
ユーザーの指示	毎回手動入力	自動ワークフロー実行
メッセージ往復	15往復	確認質問2回のみ
APIコール失敗	3回（リトライ必要）	0回
トークン消費	12,000	6,000

skill-creatorスキルの活用¶

skill-creatorスキル（Claude.ai/Claude Codeで利用可能）でできること： - 自然言語説明からスキルを生成 - 適切なフロントマターとSKILL.mdの生成 - トリガーフレーズと構造の提案 - 問題点のフラグ（漠然とした説明、トリガー不足等） - エッジケースのテストケース提案

使い方: "skill-creatorスキルを使って[ユースケース]のスキルを作るのを手伝って"

フィードバックベースの反復¶

症状	原因	解決策
スキルが発動しない	descriptionが不十分	キーワード・技術用語を追加
スキルが過剰発動	descriptionが広すぎる	ネガティブトリガーを追加、より具体的に
実行が不安定	指示が不明確	エラーハンドリングと指示を改善

5. 配布と共有¶

個人ユーザーへの配布方法（2026年1月時点）¶

スキルフォルダをダウンロード
フォルダをZIPに圧縮
Claude.ai → 設定 → Capabilities → Skills からアップロード
または Claude Code のスキルディレクトリに配置

組織レベルのスキル¶

管理者がワークスペース全体にスキルを展開可能（2025年12月18日リリース）
自動更新・集中管理

オープン標準¶

Anthropicはスキルをオープン標準として公開。MCPと同様に、さまざまなプラットフォームでポータブルに動作することを目指す。

Skills API での利用¶

- /v1/skills エンドポイントでリスト・管理
- Messages API リクエストに container.skills パラメータでスキルを追加
- Claude Agent SDK との連携

ユースケース	最適な実行環境
エンドユーザーが直接スキルを使用	Claude.ai / Claude Code
開発中の手動テストと反復	Claude.ai / Claude Code
個人・アドホックなワークフロー	Claude.ai / Claude Code
プログラムによるスキル利用アプリ	API
本番環境での大規模展開	API
自動化パイプラインとエージェントシステム	API

GitHubでの公開推奨手順¶

GitHubでホスト: パブリックリポジトリ、人間向けREADME（スキルフォルダの外に置く）
MCPドキュメントに記載: スキルへのリンク、両方使う価値の説明、クイックスタートガイド

インストールガイドを作成:

1. スキルをダウンロード
2. Claude.ai → 設定 → Skills で"スキルをアップロード"
3. スキルをオンにする
4. MCPサーバーが接続されていることを確認
5. テスト: "【サービス名】に新しいプロジェクトを設定して"

スキルの価値訴求¶

アウトカム（成果）にフォーカス：

良い例: 「ProjectHubスキルを使うと、手動で30分かかるプロジェクトワークスペースの
セットアップ（ページ・データベース・テンプレート含む）を数秒で完了できます。」

悪い例: 「ProjectHubスキルはYAMLフロントマターとMarkdown指示が入った
フォルダで、MCPサーバーツールを呼び出します。」

6. パターンとトラブルシューティング¶

2つのアプローチ¶

問題ファースト: 「プロジェクトワークスペースを設定したい」→スキルが適切なMCPコールを順番に実行
ツールファースト: 「Notion MCPが接続されている」→スキルが最適なワークフローとベストプラクティスを教える

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

特定の順序でマルチステップ処理が必要な場合に使用。

## ワークフロー: 新規顧客オンボーディング

### ステップ1: アカウント作成
MCPツールを呼び出す: `create_customer`

### ステップ2: 支払い設定
MCPツールを呼び出す: `setup_payment_method`

### ステップ3: サブスクリプション作成
MCPツールを呼び出す: `create_subscription`

### ステップ4: ウェルカムメール送信
MCPツールを呼び出す: `send_email`

キーテクニック：明示的なステップ順序、ステップ間の依存関係、各段階での検証、失敗時のロールバック手順

パターン2: マルチMCP協調¶

複数サービスにまたがるワークフローに使用（例: デザイン→開発ハンドオフ）。

## Phase 1: デザインエクスポート（Figma MCP）
## Phase 2: アセット保存（Drive MCP）
## Phase 3: タスク作成（Linear MCP）
## Phase 4: 通知（Slack MCP）

パターン3: 反復的改善¶

品質が繰り返しで向上する場合に使用（例: レポート生成）。

## 初期ドラフト
## クオリティチェック（検証スクリプト実行）
## 改善ループ（問題に対処 → 再生成 → 再検証）
## 最終化

パターン4: コンテキスト対応ツール選択¶

同じ結果でもコンテキストによって使うツールが異なる場合。

## 決定木
1. ファイルタイプとサイズを確認
2. 最適な保存先を決定:
   - 大ファイル (>10MB): クラウドストレージMCP
   - コラボドキュメント: Notion/Docs MCP
   - コードファイル: GitHub MCP

パターン5: ドメイン固有の知識¶

ツールアクセス以上の専門知識が必要な場合（例: 金融コンプライアンス）。

## 処理前（コンプライアンスチェック）
## 処理（コンプライアンス通過した場合）
## 監査証跡（全コンプライアンスチェックを記録）

トラブルシューティング一覧¶

スキルがアップロードできない¶

エラー	原因	解決策
"Could not find SKILL.md in uploaded folder"	ファイル名が正確に`SKILL.md`でない	大文字小文字を確認してリネーム
"Invalid frontmatter"	YAMLフォーマットエラー	`---`区切り文字を確認、クォートが閉じているか確認
"Invalid skill name"	スペースや大文字を含む	ケバブケースに修正

スキルがトリガーされない¶

descriptionフィールドを改善（具体的なキーワード・ユーザーが実際に使うフレーズを追加）
デバッグ方法: 「【スキル名】スキルはいつ使いますか？」とClaudeに聞く → descriptionを引用して返答してくれる

スキルが過剰にトリガーされる¶

# ネガティブトリガーを追加
description: CSVファイルの高度なデータ分析用。統計モデリング、回帰分析に使用。
  単純なデータ探索には使わない（data-vizスキルを使うこと）。

MCPコールが失敗する¶

MCPサーバーが接続されているか確認
認証情報（APIキー、OAuthトークン）を確認
スキルなしでMCPを直接テスト
ツール名が大文字小文字含め正確か確認

指示が守られない¶

指示が冗長すぎる → 箇条書き・番号リストに整理、詳細はreferences/に移動
重要な指示が埋もれている → 先頭に置く、## 重要ヘッダーを使う
言語が曖昧 → スクリプトによるプログラム的検証を使う（コードは決定論的）

モデルの「怠け」対策 → 明示的に励ます：

## パフォーマンスノート
- 時間をかけて徹底的に行うこと
- 速度より品質を優先
- 検証ステップをスキップしない

コンテキストサイズの問題（動作が遅い・品質低下）¶

SKILL.md を最適化（詳細ドキュメントをreferences/へ移動、5,000語以内を目安）
同時有効スキル数を減らす（20〜50が目安）

7. リソースと参考資料¶

公式ドキュメント（Anthropic）¶

Best Practices Guide
Skills Documentation
API Reference
MCP Documentation

ブログ記事¶

Introducing Agent Skills
Engineering Blog: Equipping Agents for the Real World
Skills Explained
How to Create Skills for Claude
Building Skills for Claude Code
Improving Frontend Design through Skills

ツール¶

skill-creatorスキル: Claude.ai/Claude Codeに組み込み、スキル生成・レビュー・推奨
公開スキルリポジトリ: GitHub: anthropics/skills

付録A：クイックチェックリスト¶

開始前¶

2〜3の具体的なユースケースを特定した
必要なツール（組み込みまたはMCP）を特定した
このガイドとサンプルスキルを確認した

開発中¶

アップロード前¶

明白なタスクでトリガーテスト済み
言い換えたリクエストでトリガーテスト済み
無関係なトピックでトリガーされないことを確認
機能テスト通過
ツール連携動作確認（該当する場合）
.zipファイルに圧縮

アップロード後¶

実際の会話でテスト
トリガー過多・少なを監視
ユーザーフィードバックを収集
descriptionと指示を反復改善
メタデータのバージョンを更新

付録B: YAMLフロントマター全フィールド¶

---
name: skill-name-in-kebab-case           # 必須
description: 何をするかと、いつ使うか。具体的なトリガーフレーズを含める。  # 必須
license: MIT                              # 任意: オープンソースの場合のライセンス
allowed-tools: "Bash(python:*) WebFetch" # 任意: ツールアクセス制限
metadata:                                 # 任意: カスタムフィールド
  author: Company Name
  version: 1.0.0
  mcp-server: server-name
  category: productivity
  tags: [project-management, automation]
  documentation: https://example.com/docs
  support: support@example.com
---

セキュリティルール： - XMLタグ（< >）は禁止（システムプロンプトへの注入対策） - YAML内でのコード実行も禁止（safe YAMLパーシング） - 名前に"claude"や"anthropic"プレフィックスは禁止（予約済み）

まとめ・MyLabへの適用ポイント¶

既存スキルの見直し: descriptionが「何をするか＋いつ使うか」を両方含んでいるか確認
スキル名の統一: ケバブケースで統一（既存スキルは概ね対応済み）
progressiveディスクロージャーの活用: 大きなスキルはSKILL.mdを軽量に保ち、詳細をreferences/に分離
skill-creatorの活用: 新スキル作成時にまずskill-creatorで雛形を作る
トリガーテストの実施: 「〇〇スキルはいつ使いますか？」でClaudeにdescriptionを確認させる

Claudeスキル構築 完全ガイド（和訳・要約）¶

目次¶