イントロダクション

整理日: 2026-03-16

スキルとは、特定のタスクやワークフローを扱う方法を教えるためにパッケージ化された一連の指示です。スキルは、あなたの特定のニーズに合わせてClaudeをカスタマイズするための最も強力な方法の一つです。毎回、あなたの好み、プロセス、専門知識を再説明する代わりに、スキルを使えば一度Claudeに教えるだけで、毎回その恩恵を受けることができます。

スキルは、繰り返し可能なワークフローを持つときに強力です：仕様からフロントエンドデザインを生成したり、一貫した方法論でリサーチを行ったり、チームのスタイルガイドに従った文書を作成したり、複数のステップからなるプロセスを調整したりします。スキルは、コード実行や文書作成など、Claudeの組み込み機能とうまく連携します。MCP統合を構築している方にとって、スキルは生のツールアクセスを信頼性の高い最適化されたワークフローに変えるためのもう一つの強力なレイヤーを追加します。

このガイドでは、効果的なスキルを構築するために必要なすべてのことをカバーします - 計画と構造からテストと配布まで。自分自身、チーム、またはコミュニティのためにスキルを構築している場合でも、実用的なパターンや実際の例が随所に見られます。

学べること：

スキル構造の技術要件とベストプラクティス
スタンドアロンのスキルとMCP強化ワークフローのパターン
様々なユースケースでうまく機能するパターン
スキルのテスト、反復、配布方法

対象者：

Claudeに特定のワークフローを一貫して実行させたい開発者
Claudeに特定のワークフローを実行させたいパワーユーザー
組織全体でClaudeの動作を標準化したいチーム

このガイドの2つの道

スタンドアロンのスキルを構築していますか？基本、計画とデザイン、カテゴリー1-2に焦点を当ててください。MCP統合を強化していますか？「スキル + MCP」セクションとカテゴリー3があなたのためのものです。両方の道は同じ技術要件を共有しますが、あなたのユースケースに関連するものを選択します。

このガイドから得られること：

最後には、1回の座で機能するスキルを構築できるようになります。スキルクリエーターを使用して最初の作業スキルを構築しテストするのに約15-30分かかると予想してください。

さあ、始めましょう。

第1章

基本原則

整理日: 2026-03-16

スキルとは何か？

スキルは次のものを含むフォルダーです：

SKILL.md（必須）：YAMLフロントマターを含むMarkdown形式の指示
scripts/（任意）：実行可能なコード（Python、Bashなど）
references/（任意）：必要に応じて読み込まれるドキュメント
assets/（任意）：出力に使用されるテンプレート、フォント、アイコン

構造図

flowchart TD
    A["scripts"]
    A --> B["主要な機能："]
    B --> C["パック"]
    C --> D["ケバブケースを使用: notion-project-se.."]
    D --> E["明示的な品質基準"]
    E --> F["Audit Trail"]
    style F fill:#c05746,color:#fff,stroke:none

コアデザイン原則

プログレッシブディスクロージャー

スキルは三層システムを使用します：

第一層（YAMLフロントマター）：常にClaudeのシステムプロンプトに読み込まれます。各スキルがいつ使用されるべきかを知るために必要な情報だけを提供し、すべてをコンテキストに読み込むことはありません。
第二層（SKILL.md本文）：Claudeがスキルが現在のタスクに関連していると考えたときに読み込まれます。完全な指示とガイダンスが含まれています。
第三層（リンクされたファイル）：スキルディレクトリ内にバンドルされた追加ファイルで、Claudeは必要に応じてナビゲートして発見することができます。

このプログレッシブディスクロージャーは、専門的な知識を維持しながらトークンの使用を最小限に抑えます。

コンポーザビリティ Claudeは複数のスキルを同時に読み込むことができます。あなたのスキルは他のスキルと一緒にうまく機能する必要があり、唯一の能力であると仮定してはいけません。

ポータビリティ スキルはClaude.ai、Claude Code、APIで同じように機能します。一度スキルを作成すれば、環境がスキルに必要な依存関係をサポートしている限り、すべてのプラットフォームで修正なしに機能します。

MCPビルダー向け：スキル + コネクタ

💡 MCPなしでスタンドアロンのスキルを構築していますか？計画と設計にスキップしてください - 後でここに戻ってくることができます。すでに稼働中のMCPサーバーを持っている場合、あなたは難しい部分を終えています。スキルはその上にある知識の層であり、あなたがすでに知っているワークフローとベストプラクティスを捉え、Claudeが一貫してそれらを適用できるようにします。

キッチンのアナロジー

MCPはプロのキッチンを提供します：ツール、材料、設備へのアクセス。

スキルはレシピを提供します：価値のあるものを作成するためのステップバイステップの指示。

一緒に、ユーザーが自分で全てのステップを理解することなく、複雑なタスクを達成できるようにします。

どのように連携するか:

MCP（接続性）

Claudeをあなたのサービスに接続します（Notion、Asana、Linearなど）
リアルタイムのデータアクセスとツールの呼び出しを提供します
Claudeができること

スキル（知識）

Claudeにあなたのサービスを効果的に使う方法を教えます
ワークフローとベストプラクティスをキャプチャします
Claudeがどのようにそれを行うべきか

これがあなたのMCPユーザーにとって重要な理由

スキルがない場合:

ユーザーはあなたのMCPを接続しますが、次に何をすべきかわかりません
"あなたの統合でXをどうやってやるの？"というサポートチケット
各会話はゼロから始まります
ユーザーが毎回異なるプロンプトを出すため、一貫性のない結果が得られます
実際の問題はワークフローのガイダンスであるのに、ユーザーはあなたのコネクタを非難します

スキルがある場合:

事前構築されたワークフローが必要に応じて自動的に起動します
一貫して信頼できるツールの使用
各インタラクションにベストプラクティスが組み込まれています
あなたの統合の学習曲線が低くなります

第2章

計画と設計

整理日: 2026-03-16

使用ケースから始める

コードを書く前に、スキルが実現すべき具体的な使用ケースを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

使用ケース: プロジェクトスプリント計画
トリガー: ユーザーが「このスプリントを計画する手伝いをして」または「スプリントタスクを作成する」と言う
ステップ:
1. Linearから現在のプロジェクト状況を取得（MCP経由）
2. チームの速度とキャパシティを分析
3. タスクの優先順位を提案
4. 適切なラベルと見積もりでLinearにタスクを作成
結果: タスクが作成された完全に計画されたスプリント

自問自答してください:

ユーザーは何を達成したいのか？
これにはどのような複数のステップのワークフローが必要か？
どのツールが必要か（組み込みまたはMCP？）
どのドメイン知識やベストプラクティスを組み込むべきか？

一般的なスキル使用ケースカテゴリ

Anthropicでは、3つの一般的な使用ケースを観察しました:

カテゴリ1: ドキュメントと資産の作成

使用目的: ドキュメント、プレゼンテーション、アプリ、デザイン、コードなど、一貫性のある高品質な出力を作成すること。実例: フロントエンドデザインスキル（docx、pptx、xlsx、pptのスキルも参照）

「高いデザイン品質を持つ独自のプロダクショングレードのフロントエンドインターフェースを作成します。ウェブコンポーネント、ページ、アーティファクト、ポスター、またはアプリケーションを構築する際に使用します。」

主な技術:

埋め込みスタイルガイドとブランド基準
一貫した出力のためのテンプレート構造
最終化前の品質チェックリスト
外部ツールは不要 - Claudeの組み込み機能を使用

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

使用目的：一貫した方法論から恩恵を受ける複数ステップのプロセス、複数のMCPサーバー間の調整を含む。

実例：スキルクリエータースキル

"新しいスキルを作成するためのインタラクティブガイド。ユーザーをユースケースの定義、フロントマターの生成、指示文の作成、検証へと導く。"

主な技術：

検証ゲートを伴う段階的ワークフロー
一般的な構造のためのテンプレート
内蔵のレビューと改善提案
反復的な精緻化ループ

カテゴリ3：MCP強化

使用目的：MCPサーバーが提供するツールアクセスを強化するためのワークフローガイダンス。

実例：sentry-code-reviewスキル（Sentryから）

"Sentryのエラーモニタリングデータを使用して、GitHubプルリクエストで検出されたバグを自動的に分析し修正します。"

主な技術：

複数のMCP呼び出しを順次調整
ドメインの専門知識を埋め込む
ユーザーが通常指定する必要があるコンテキストを提供
一般的なMCP問題のエラーハンドリング

成功基準を定義する

スキルが機能しているかどうかはどうやってわかりますか？

これらは目標としての指標であり、正確な閾値ではなく粗いベンチマークです。厳密さを目指しますが、感覚に基づく評価の要素があることを受け入れます。より堅牢な測定ガイダンスとツールを積極的に開発しています。

定量的指標：

関連するクエリの90％でスキルがトリガーされる – 測定方法：スキルをトリガーするはずのテストクエリを10～20件実行します。自動的に読み込まれる回数と明示的な呼び出しが必要な回数を追跡します。
Xツール呼び出しでワークフローを完了する – 測定方法：スキルを有効にした場合と無効にした場合で同じタスクを比較します。ツール呼び出しと消費トークンの合計をカウントします。
ワークフローごとに0回のAPI呼び出し失敗 – 測定方法：テスト実行中にMCPサーバーログを監視します。リトライ率とエラーコードを追跡します。

定性的指標：

ユーザーは次のステップについてClaudeに促す必要がない – 評価方法：テスト中に、どれだけの頻度でリダイレクトや明確化が必要かを記録します。ベータユーザーにフィードバックを求めます。
ユーザーの修正なしでワークフローが完了する  – 評価方法：同じリクエストを3～5回実行します。出力の構造的一貫性と品質を比較します。
セッション間での一貫した結果  – 評価方法：新しいユーザーが最初の試みで最小限のガイダンスでタスクを達成できるか？

技術要件

ファイル構造

your-skill-name/
├── SKILL.md #必須-メインスキルファイル
├── scripts/ #オプション-実行可能コード
│　├── process_data.py # 例
│　└── validate.sh # 例
├── references/ #オプション-ドキュメント
│　├── api-guide.md # 例
│　└── examples/ # 例
└── assets/ #オプション-テンプレート、など。
　└── report-template.md # 例

重要なルール

SKILL.mdの命名:

必ずSKILL.mdであること（大文字小文字を区別）
バリエーションは受け付けません（SKILL.MD、skill.mdなど）

スキルフォルダの命名:

ケバブケースを使用: notion-project-setup ✅
スペースは使用しない: Notion Project Setup ❌
アンダースコアは使用しない: notion_project_setup ❌
大文字は使用しない: NotionProjectSetup ❌

README.mdは不要:

スキルフォルダ内にREADME.mdを含めないでください
すべてのドキュメントはSKILL.mdまたはreferences/に入れます
注: GitHub経由で配布する際は、ユーザー向けにリポジトリレベルのREADMEが必要です — 配布と共有を参照してください。

YAMLフロントマター: 最も重要な部分

YAMLフロントマターはClaudeがスキルを読み込むかどうかを決定する方法です。これを正しく設定してください。

最小限の必須フォーマット

---
name: your-skill-name
description: What it does. Use when user asks to [specific
phrases].
---

name: your-skill-name description: それが何をするか。ユーザーが[specific phrases]を尋ねたときに使用します。

これだけで始めることができます。

フィールド要件

**name（**必須）:

ケバブケースのみ
スペースや大文字は使用しない
フォルダ名と一致する必要があります

description（必須）:

必ず両方を含めること: – スキルが何をするか – いつ使用するか（トリガー条件）
1024文字未満
XMLタグ（<または>）は含めない
ユーザーが言うかもしれない具体的なタスクを含める
関連する場合はファイルタイプに言及する

ライセンス（オプション）：

スキルをオープンソースにする場合に使用
一般的：MIT、Apache-2.0

互換性（オプション）

1-500文字
環境要件を示します：例：対象製品、必要なシステムパッケージ、ネットワークアクセスのニーズなど。

**メタデータ（**オプション）：

任意のカスタムキー-バリューペア
推奨：著者、バージョン、mcp-server
例：

```yaml metadata: 　author: ProjectHub 　version: 1.0.0 mcp-server: projecthub ```

セキュリティ制限

フロントマターで禁止されている:

XMLの角括弧（< >）
名前に「claude」または「anthropic」を含むスキル（予約済み）

理由: フロントマターはClaudeのシステムプロンプトに表示されます。悪意のあるコンテンツが指示を注入する可能性があります。

効果的なスキルの記述

説明フィールド

Anthropicのエンジニアリングブログによると："このメタデータは...各スキルがいつ使用されるべきかを知るために必要な情報を提供しますが、すべてをコンテキストに読み込むことはありません。" これは段階的開示の最初のレベルです。

構造：

[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".

# 良い - 特定かつ実行可能な説明: Figmaデザインファイルを分析し、開発者向けの引き渡しドキュメントを生成します。ユーザーが.figファイルをアップロードしたり、「デザイン仕様」、「コンポーネントドキュメント」、または「デザインからコードへの引き渡し」を求めるときに使用します。 # 良い - トリガーフレーズを含む説明: スプリント計画、タスク作成、ステータストラッキングを含むLinearプロジェクトワークフローを管理します。ユーザーが「スプリント」、「Linearタスク」、「プロジェクト計画」と言及したり、「チケットを作成する」と要求したときに使用します。 # 良い - 明確な価値提案の説明: PayFlowのエンドツーエンドの顧客オンボーディングワークフロー。アカウント作成、支払い設定、サブスクリプション管理を処理します。ユーザーが「新しい顧客をオンボードする」、「サブスクリプションを設定する」、または「PayFlowアカウントを作成する」と言ったときに使用します。

悪い説明の例:

# 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

> 整理日: 2026-03-16

# Instructions
### Step 1: [First Major Step]
Clear explanation of what happens.

xample:
bash
python scripts/fetch_data.py --project-id PROJECT_ID
Expected output: [describe what success looks like]

--- 名前: あなたのスキル説明: [...] --- # あなたのスキル名 # 指示 ### ステップ 1: [最初の主要ステップ] 何が起こるかの明確な説明。例: ```bash python scripts/fetch_data.py --project-id PROJECT_ID 期待される出力: [成功がどのように見えるかを説明してください]

(必要に応じてステップを追加してください)

例

例 1: [一般的なシナリオ]

ユーザーが言う: "新しいマーケティングキャンペーンを設定して"

アクション: 1. MCPを介して既存のキャンペーンを取得 2. 提供されたパラメータで新しいキャンペーンを作成結果: 確認リンク付きでキャンペーンが作成されました

(必要に応じてさらに例を追加してください)

トラブルシューティング

エラー: [一般的なエラーメッセージ]

原因: [なぜそれが発生するのか]

解決策: [修正方法]

(必要に応じてさらにエラーケースを追加してください)

指示のベストプラクティス

具体的かつ実行可能であること

✅ 良い例:

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)

Run`python scripts/validate.py --input {filename}`を実行してデータ形式を確認してください。検証が失敗した場合、一般的な問題は以下の通りです： - 必須フィールドが欠けている（CSVに追加してください） - 無効な日付形式（YYYY-MM-DDを使用）

❌ 悪い:

Validate the data before proceeding.

進む前にデータを検証してください。

エラーハンドリングを含める

# Common Issues

> 整理日: 2026-03-16

### 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] >
Reconnect

# 一般的な問題 ### MCP接続失敗「接続が拒否されました」と表示された場合： 1. MCPサーバーが稼働しているか確認：設定 > 拡張機能をチェック 2. APIキーが有効であることを確認 3. 再接続を試みる：設定 > 拡張機能 > [あなたのサービス] > 再接続

バンドルされたリソースを明確に参照する

Before writing queries, consult \`references/api-patterns.md\`
for:
- Rate limiting guidance
- Pagination patterns
- Error codes and handling

クエリを書く前に、`references/api-patterns.md`を参照してください: - レート制限のガイダンス - ページネーションパターン - エラーコードと処理

プログレッシブディスclosureを使用する

SKILL.mdはコアの指示に集中させ、詳細なドキュメントは`references/`に移動してリンクを貼ること。（三層システムの動作については、コアデザイン原則を参照してください。）

第3章

テストと反復

整理日: 2026-03-16

スキルは、ニーズに応じてさまざまなレベルの厳密さでテストできます：

Claude.aiでの手動テスト - クエリを直接実行し、動作を観察します。迅速な反復、セットアップは不要です。
Claude Codeでのスクリプトテスト - 変更に対して繰り返し検証するためのテストケースを自動化します。
スキルAPIを介したプログラムテスト - 定義されたテストセットに対して体系的に実行される評価スイートを構築します。

品質要件とスキルの可視性に合ったアプローチを選択してください。小規模なチームによって内部で使用されるスキルは、数千のエンタープライズユーザーに展開されるスキルとは異なるテストニーズがあります。

プロのヒント：拡張する前に単一のタスクで反復する

推奨テストアプローチ

初期の経験に基づくと、効果的なスキルテストは通常、3つの領域をカバーします：

1. テストのトリガー **目標：**スキルが適切なタイミングで読み込まれることを確認します。 テストケース：

✅ 明白なタスクでトリガーされる
✅ 言い換えたリクエストでトリガーされる
無関係なトピックではトリガーされない

例のテストスイート：

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)

トリガーされるべき： - "新しいProjectHubワークスペースを設定する手伝いをして" - "ProjectHubでプロジェクトを作成する必要があります" - "Q4計画のためにProjectHubプロジェクトを初期化する" トリガーされないべき： - "サンフランシスコの天気は？" - "Pythonコードを書く手伝いをして" - "スプレッドシートを作成する"（ProjectHubスキルがシートを扱う場合を除く）

2. 機能テスト

目標: スキルが正しい出力を生成することを確認する。 テストケース:

有効な出力が生成される
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

テスト: 5つのタスクを持つプロジェクトを作成する前提: プロジェクト名「Q4計画」、5つのタスク説明実行時: スキルがワークフローを実行するその結果: - ProjectHubにプロジェクトが作成される - 5つのタスクが正しいプロパティで作成される - すべてのタスクがプロジェクトにリンクされる - APIエラーなし

3. パフォーマンス比較

目標: スキルがベースラインに対して結果を改善することを証明する。成功基準を定義するためのメトリクスを使用します。比較がどのように見えるかは以下の通りです。

ベースライン比較:

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

スキルを使用しない場合: - ユーザーが毎回指示を提供 - 15回のやり取りメッセージ - 再試行が必要な失敗したAPIコールが3回 - 12,000トークン消費スキルを使用した場合: - 自動ワークフロー実行 - 2つの明確化質問のみ - 失敗したAPIコールなし - 6,000トークン消費

スキルクリエイターのスキルを使用して

スキルクリエイターのスキル - Claude.aiのプラグインディレクトリから利用可能、またはClaude Code用にダウンロード可能 - は、スキルの構築と反復を支援します。MCPサーバーがあり、上位2〜3のワークフローを知っていれば、1回のセッションで機能的なスキルを構築してテストできます - 通常は15〜30分で。

スキルの作成:

自然言語の説明からスキルを生成する
フロントマター付きの正しくフォーマットされたSKILL.mdを生成する
トリガーフレーズと構造を提案する

スキルのレビュー:

一般的な問題をフラグ付けする（曖昧な説明、トリガーの欠如、構造的な問題）
過剰/不足トリガーのリスクを特定する
スキルの目的に基づいてテストケースを提案する

反復的改善:

スキルを使用してエッジケースや失敗に遭遇した後、それらの例をスキルクリエイターに持ち帰る
例: "このチャットで特定された問題と解決策を使用して、スキルが[specific edge case]を処理する方法を改善する"

使用方法:

"Use the skill-creator skill to help me build a skill for [your use case]"

"スキルクリエイターのスキルを使って、[あなたのユースケース]のためのスキルを構築する手助けをしてください"

注意: スキルクリエイターはスキルの設計と洗練を手助けしますが、実行はしません。自動テストスイートや定量的評価結果を生成することはありません。

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

スキルは生きた文書です。次に基づいて反復することを計画してください:

アンダートリガー信号:

スキルが必要なときに読み込まれない
ユーザーが手動で有効にする
いつ使用するかについてのサポート質問

解決策: 説明に詳細とニュアンスを追加する - 特に技術用語のキーワードを含めることができます

オーバートリガー信号:

スキルが無関係なクエリに対して読み込まれる
ユーザーが無効にする
目的についての混乱

解決策: ネガティブトリガーを追加し、より具体的にする

実行の問題:

結果が不一致 APIコールの失敗ユーザーの修正が必要

解決策: 指示を改善し、エラーハンドリングを追加する

第4章

配布と共有

整理日: 2026-03-16

スキルはMCP統合をより完全にします。ユーザーがコネクタを比較する際、スキルを持つものは価値への迅速な道を提供し、MCPのみの代替品に対して優位性を与えます。

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

個々のユーザーがスキルを取得する方法：

スキルフォルダーをダウンロード
フォルダーを圧縮（必要な場合）
設定 > 機能 > スキルからClaude.aiにアップロード
またはClaude Codeスキルディレクトリに配置

組織レベルのスキル：

管理者はスキルをワークスペース全体に展開できます（2025年12月18日出荷）
自動更新
中央管理

オープンスタンダード

私たちはエージェントスキルをオープンスタンダードとして公開しました。MCPと同様に、スキルはツールやプラットフォームを超えて移植可能であるべきだと考えています。同じスキルはClaudeや他のAIプラットフォームを使用していても機能するべきです。ただし、一部のスキルは特定のプラットフォームの機能を最大限に活用するように設計されており、著者はスキルの互換性フィールドでこれを示すことができます。私たちはエコシステムのメンバーとスタンダードについて協力しており、初期の採用に興奮しています。

APIを介したスキルの使用

プログラム的なユースケース - スキルを活用したアプリケーション、エージェント、または自動化されたワークフローを構築する場合 - APIはスキルの管理と実行を直接制御します。

主要な機能：

スキルのリストと管理のための**`/v1/skills`**エンドポイント
**`container.skills`**パラメータを介してメッセージAPIリクエストにスキルを追加
Claude Consoleを通じたバージョン管理と管理
カスタムエージェントを構築するためのClaude Agent SDKと連携

APIを介してスキルを使用する場合とClaude.aiを使用する場合：

ユースケースと最適な表面

エンドユーザーがスキルと直接対話する → Claude.ai / Claude Code
開発中の手動テストと反復 → Claude.ai / Claude Code
個別のアドホックワークフロー → Claude.ai / Claude Code
プログラム的にスキルを使用するアプリケーション → API
大規模な本番展開 → API
自動化されたパイプラインとエージェントシステム → API

注意: APIのスキルには、スキルが実行するために必要な安全な環境を提供するコード実行ツールのベータ版が必要です。

実装の詳細については、次を参照してください:

今日の推奨アプローチ

まず、GitHubでパブリックリポジトリとしてスキルをホストし、明確なREADME（人間の訪問者向け - これはスキルフォルダとは別で、README.mdを含めてはいけません）とスクリーンショット付きの使用例を用意します。次に、スキルへのリンクを含むMCPドキュメントにセクションを追加し、両者を一緒に使用することの価値を説明し、クイックスタートガイドを提供します。

1. GitHubでホストする

オープンソーススキル用のパブリックリポジトリ
インストール手順を含む明確なREADME
使用例とスクリーンショット

2. MCPリポジトリに文書化する

MCPドキュメントからスキルへのリンク
両者を一緒に使用することの価値を説明
クイックスタートガイドを提供

3. インストールガイドを作成する

# Installing the [Your Service] skill

> 整理日: 2026-03-16

1. Download the skill:
 - Clone repo: \`git clone https: /github.com/yourcompany/
 skills\`
 - Or download ZIP from Releases

2. Install in Claude:
 - Open Claude.ai > Settings > skills
 - Click "Upload skill"
 - Select the skill folder (zipped)

3. Enable the skill:
 - Toggle on the [Your Service] skill
 - Ensure your MCP server is connected

4. Test:
 - Ask Claude: "Set up a new project in [Your Service]"

# [あなたのサービス] スキルのインストール 1. スキルをダウンロード: - リポジトリをクローン: `git clone https://github.com/ yourcompany/skills` - または、リリースからZIPをダウンロード 2. Claudeにインストール: - Claude.aiを開く > 設定 > スキル - 「スキルをアップロード」をクリック - スキルフォルダ（圧縮）を選択 3. スキルを有効にする: - [あなたのサービス] スキルをオンに切り替え - MCPサーバーが接続されていることを確認 4. テスト: - Claudeに聞いてみて: 「[あなたのサービス] で新しいプロジェクトを設定して」

スキルの位置付け

スキルの説明方法は、ユーザーがその価値を理解し、実際に試すかどうかを決定します。README、ドキュメント、またはマーケティングでスキルについて書く際は、これらの原則を念頭に置いてください。

機能ではなく成果に焦点を当てる:

✅ 良い例:

"The ProjectHub skill enables teams to set up complete project
workspaces in seconds — including pages, databases, and
templates — instead of spending 30 minutes on manual setup."

「ProjectHubスキルは、チームが数秒で完全なプロジェクトワークスペースを設定できるようにします — ページ、データベース、テンプレートを含む — 手動設定に30分を費やす代わりに。」

❌ 悪い例:

"The ProjectHub skill is a folder containing YAML frontmatter
and Markdown instructions that calls our MCP server tools."

「ProjectHubスキルは、YAMLフロントマターとMarkdown指示を含むフォルダで、私たちのMCPサーバーツールを呼び出します。」

MCP + スキルのストーリーを強調する:

"Our MCP server gives Claude access to your Linear projects.
Our skills teach Claude your team's sprint planning workflow.
Together, they enable AI-powered project management."

「私たちのMCPサーバーは、ClaudeにあなたのLinearプロジェクトへのアクセスを提供します。私たちのスキルは、Claudeにあなたのチームのスプリント計画ワークフローを教えます。これにより、AI駆動のプロジェクト管理が可能になります。」

第5章

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

整理日: 2026-03-16

これらのパターンは、初期の採用者や内部チームによって作成されたスキルから生まれました。それらは、私たちがうまく機能するのを見てきた一般的なアプローチを表しており、処方的なテンプレートではありません。

アプローチの選択：問題優先 vs. ツール優先

ホームデポのように考えてみてください。あなたは「キッチンキャビネットを修理する必要がある」と言って店に入るかもしれません - そして従業員が適切なツールを指し示します。あるいは、新しいドリルを選んで、その特定の仕事にどう使うかを尋ねるかもしれません。

スキルも同じように機能します：

問題優先：「プロジェクトワークスペースを設定する必要がある」→ あなたのスキルは、適切なMCPコールを適切な順序で調整します。ユーザーは結果を説明し、スキルがツールを扱います。
ツール優先：「Notion MCPが接続されている」→ あなたのスキルは、Claudeに最適なワークフローとベストプラクティスを教えます。ユーザーはアクセスを持ち、スキルが専門知識を提供します。

ほとんどのスキルは一方向に傾いています。どのフレーミングがあなたのユースケースに適しているかを知ることで、以下の適切なパターンを選択するのに役立ちます。

パターン1：逐次ワークフローオーケストレーション

使用するタイミング：ユーザーが特定の順序で複数のステッププロセスを必要とする場合。

例の構造：

# Workflow: Onboard New Customer

> 整理日: 2026-03-16

### Step 1: Create Account
Call MCP tool: \`create_customer\`
Parameters: name, email, company

### Step 2: Setup Payment
Call MCP tool: \`setup_payment_method\`
Wait for: payment method verification

### Step 3: Create Subscription
Call MCP tool: \`create_subscription\`
Parameters: plan_id, customer_id (from Step 1)

### Step 4: Send Welcome Email
Call MCP tool: \`send_email\`
Template: welcome_email_template

## ワークフロー：新しい顧客をオンボードする ### ステップ1：アカウントを作成する MCPツールを呼び出す：`create_customer` パラメータ：名前、メール、会社 ### ステップ2：支払いを設定する MCPツールを呼び出す：`setup_payment_method` 待機する：支払い方法の確認 ### ステップ3：サブスクリプションを作成する MCPツールを呼び出す：`create_subscription` パラメータ：plan_id、customer_id（ステップ1から） ### ステップ4：ウェルカムメールを送信する MCPツールを呼び出す：`send_email` テンプレート：welcome_email_template

主要な技術：

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

パターン2：マルチMCP調整

**使用するタイミング：**ワークフローが複数のサービスにまたがる場合。

例：デザインから開発への引き渡し

### Phase 1: Design Export (Figma MCP)
1. Export design assets from Figma
2. Generate design specifications
3. Create asset manifest

### Phase 2: Asset Storage (Drive MCP)
1. Create project folder in Drive
2. Upload all assets
3. Generate shareable links

### Phase 3: Task Creation (Linear MCP)
1. Create development tasks
2. Attach asset links to tasks
3. Assign to engineering team

### Phase 4: Notification (Slack MCP)
1. Post handoff summary to #engineering
2. Include asset links and task references

### フェーズ1：デザインエクスポート（Figma MCP） 1. Figmaからデザイン資産をエクスポート 2. デザイン仕様を生成 3. 資産マニフェストを作成 ### フェーズ2：資産ストレージ（Drive MCP） 1. Driveにプロジェクトフォルダを作成 2. すべての資産をアップロード 3. 共有可能なリンクを生成 ### フェーズ3：タスク作成（Linear MCP） 1. 開発タスクを作成 2. タスクに資産リンクを添付 3. エンジニアリングチームに割り当て ### フェーズ4：通知（Slack MCP） 1. #engineeringに引き渡しの概要を投稿 2. 資産リンクとタスクの参照を含める

主要な技術：

明確なフェーズの分離
MCP間のデータの受け渡し
次のフェーズに進む前の検証
中央集権的なエラーハンドリング

パターン3：反復的な改善

**使用するタイミング：**出力の品質が反復によって向上する場合。

例：レポート生成

## Iterative Report Creation

### Initial Draft
1. Fetch data via MCP
2. Generate first draft report
3. Save to temporary file

### Quality Check
1. Run validation script: \`scripts/check_report.py\`
2. Identify issues:
 - Missing sections
 - Inconsistent formatting
 - Data validation errors

### Refinement Loop
1. Address each identified issue
2. Regenerate affected sections
3. Re-validate
4. Repeat until quality threshold met

### Finalization
1. Apply final formatting
2. Generate summary
3. Save final version

## 反復レポート作成 ### 初期ドラフト 1. MCPを介してデータを取得 2. 初回ドラフトレポートを生成 3. 一時ファイルに保存 ### 品質チェック 1. 検証スクリプトを実行：`scripts/check_report.py` 2. 問題を特定： - 欠落しているセクション - 一貫性のないフォーマット - データ検証エラー ### 改善ループ 1. 特定された各問題に対処 2. 影響を受けたセクションを再生成 3. 再検証 4. 品質基準が満たされるまで繰り返す ## 最終化 1. 最終フォーマットを適用 2. 概要を生成 3. 最終版を保存

主要な技術：

明示的な品質基準
反復的な改善
検証スクリプト
反復をやめるべきタイミングを知る

パターン4: コンテキストに応じたツール選択

使用するタイミング: 同じ結果を得るために、コンテキストに応じて異なるツールを使用する。

例: ファイルストレージ

## Smart File Storage

### Decision Tree
1. Check file type and size
2. Determine best storage location:
 - Large files (>10MB): Use cloud storage MCP
 - Collaborative docs: Use Notion/Docs MCP
 - Code files: Use GitHub MCP
 - Temporary files: Use local storage

### Execute Storage
Based on decision:
- Call appropriate MCP tool
- Apply service-specific metadata
- Generate access link

### Provide Context to User
Explain why that storage was chosen

## スマートファイルストレージ ### 意思決定ツリー 1. ファイルの種類とサイズを確認 2. 最適なストレージ場所を決定: - 大きなファイル（>10MB）: クラウドストレージMCPを使用 - コラボレーション文書: Notion/Docs MCPを使用 - コードファイル: GitHub MCPを使用 - 一時ファイル: ローカルストレージを使用 ### ストレージの実行決定に基づいて: - 適切なMCPツールを呼び出す - サービス特有のメタデータを適用 - アクセスリンクを生成 ### ユーザーへのコンテキスト提供なぜそのストレージが選ばれたのかを説明

主要な技術:

明確な意思決定基準
フォールバックオプション
選択肢についての透明性

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

使用するタイミング: あなたのスキルがツールへのアクセスを超えた専門知識を追加する場合。

例: 財務コンプライアンス

## Payment Processing with Compliance

### Before Processing (Compliance Check)
1. Fetch transaction details via MCP
2. Apply compliance rules:
 - Check sanctions lists
 - Verify jurisdiction allowances
 - Assess risk level
3. Document compliance decision

### Processing
IF compliance passed:
 - Call payment processing MCP tool
 - Apply appropriate fraud checks
 - Process transaction
ELSE:
 - Flag for review
 - Create compliance case

### Audit Trail
- Log all compliance checks
- Record processing decisions
- Generate audit report

## コンプライアンスを伴う支払い処理 ## 処理前（コンプライアンスチェック） 1. MCPを介して取引詳細を取得 2. コンプライアンスルールを適用: - 制裁リストを確認 - 管轄権の許可を確認 - リスクレベルを評価 3. コンプライアンス決定を文書化 ## 処理コンプライアンスが通過した場合: - 支払い処理MCPツールを呼び出す - 適切な詐欺チェックを適用 - 取引を処理そうでない場合: - レビューのためにフラグを立てる - コンプライアンスケースを作成 ### 監査トレイル - すべてのコンプライアンスチェックをログに記録 - 処理決定を記録 - 監査報告書を生成

主要な技術:

論理に埋め込まれたドメイン専門知識
行動前のコンプライアンス
包括的な文書化
明確なガバナンス

トラブルシューティング

スキルがアップロードされない

エラー: "アップロードされたフォルダーにSKILL.mdが見つかりませんでした"

原因: ファイル名が正確にSKILL.mdではない

解決策:

SKILL.mdに名前を変更する（大文字小文字を区別）
確認方法: ls -laでSKILL.mdが表示されるべき

エラー: "無効なフロントマター"

原因: YAMLフォーマットの問題

一般的な間違い:

# Wrong - missing delimiters
name: my-skill
description: Does things

# Wrong - unclosed quotes
name: my-skill
description: "Does things

# Correct
---
name: my-skill
description: Does things
---

# 誤り - デリミタが欠けている name: my-skill description: 物事を行う # 誤り - クォートが閉じていない name: my-skill description: "物事を行う # 正しい --- name: my-skill description: 物事を行う ---

エラー: "無効なスキル名"

原因: 名前にスペースや大文字が含まれている

# Wrong
name: My Cool Skill

# Correct
name: my-cool-skill

# 誤り name: My Cool Skill # 正しい name: my-cool-skill

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

症状: スキルが自動的に読み込まれない

修正: 説明フィールドを見直してください。「説明フィールド」で良い/悪い例を参照してください。

クイックチェックリスト:

あまりにも一般的ではないか？（"プロジェクトを手伝う"では機能しない）
ユーザーが実際に言うトリガーフレーズを含んでいるか？
該当する場合、関連するファイルタイプに言及しているか？

デバッグアプローチ:

クロードに聞いてみてください: "[スキル名]スキルはいつ使用しますか？" クロードが説明を引用します。欠けている部分に基づいて調整してください。

スキルが頻繁にトリガーされる

症状: スキルが無関係なクエリに対して読み込まれる

解決策:

ネガティブトリガーを追加する

description: Advanced data analysis for CSV files. Use for
statistical modeling, regression, clustering. Do NOT use for
simple data exploration (use data-viz skill instead).

description: CSVファイルの高度なデータ分析。統計モデル、回帰、クラスタリングに使用。単純なデータ探索には使用しないでください（代わりにデータビジュアリゼーションスキルを使用）。

2. より具体的に

# Too broad
description: Processes documents

# More specific
description: Processes PDF legal documents for contract review

# あまりにも広い説明: 文書を処理します # より具体的説明: 契約レビューのためにPDF法的文書を処理します

3. Clarify scope

description: PayFlow payment processing for e-commerce. Use
specifically for online payment workflows, not for general
financial queries.

説明: eコマース向けのPayFlow決済処理。一般的な財務問い合わせではなく、オンライン決済ワークフロー専用に使用してください。

MCP接続の問題

症状: スキルは読み込まれるがMCP呼び出しが失敗する

チェックリスト:

MCPサーバーが接続されていることを確認する – Claude.ai: 設定 > 拡張機能 > [あなたのサービス] – "接続済み"のステータスが表示されるべき
認証を確認する – APIキーが有効で期限切れでないこと – 適切な権限/スコープが付与されていること – OAuthトークンが更新されていること
MCPを独立してテストする – ClaudeにスキルなしでMCPを直接呼び出させる – "[サービス] MCPを使って私のプロジェクトを取得して" – これが失敗した場合、問題はスキルではなくMCPである
ツール名を確認する – スキルが正しいMCPツール名を参照していること – MCPサーバーのドキュメントを確認する – ツール名は大文字と小文字を区別する

指示が守られていない

症状: スキルは読み込まれるがClaudeが指示に従わない

一般的な原因:

指示が冗長すぎる – 指示を簡潔に保つ – 箇条書きや番号付きリストを使用する – 詳細な参照は別のファイルに移動する
指示が埋もれている – 重要な指示を最上部に置く – ## 重要または## クリティカルの見出しを使用する – 必要に応じて重要なポイントを繰り返す
Ambiguous language

# Bad
Make sure to validate things properly

# Good
CRITICAL: Before calling create_project, verify:
- Project name is non-empty
- At least one team member assigned
- Start date is not in the past

# 悪い物事を適切に検証することを確認してください # 良い重要: create_projectを呼び出す前に確認してください: - プロジェクト名が空でないこと - 少なくとも1人のチームメンバーが割り当てられていること - 開始日が過去でないこと

高度な技術: 重要な検証のために、言語指示に依存するのではなく、プログラム的にチェックを実行するスクリプトをバンドルすることを検討してください。コードは決定論的ですが、言語の解釈はそうではありません。このパターンの例としてOfficeスキルを参照してください。

4. "怠惰"をモデル化する 明示的な励ましを追加する:

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

# パフォーマンスノート - これを徹底的に行うために時間をかけてください - 速度よりも品質が重要です - 検証ステップを省略しないでください

注: これをユーザープロンプトに追加する方がSKILL.mdに追加するよりも効果的です

大規模なコンテキストの問題

**症状：**スキルが遅い、または応答が劣化しているように見える

原因： • スキルコンテンツが大きすぎる • 同時に有効になっているスキルが多すぎる • すべてのコンテンツが読み込まれ、段階的開示が行われていない

解決策：

SKILL.mdのサイズを最適化する – 詳細なドキュメントをreferences/に移動する – インラインではなく参照にリンクする – SKILL.mdを5,000語未満に保つ
有効なスキルを減らす – 同時に有効になっているスキルが20〜50を超えていないか評価する – 選択的な有効化を推奨する – 関連する機能のためのスキル「パック」を検討する

第6章

リソースと参考文献

整理日: 2026-03-16

初めてスキルを構築する場合は、まずベストプラクティスガイドを参照し、その後必要に応じてAPIドキュメントを参照してください。

公式ドキュメント

Anthropicリソース：

ブログ投稿:

サンプルスキル

公開スキルリポジトリ：

GitHub: anthropics/skills
Contains Anthropic-created skills you can customize

ツールとユーティリティ

スキルクリエイタースキル：

Built into Claude.ai and available for Claude Code
Can generate skills from descriptions
Reviews and provides recommendations
Use: "Help me build a skill using skill-creator"

検証：

skill-creator can assess your skills
Ask: "Review this skill and suggest improvements"

サポートを受ける

技術的な質問については：

General questions: Community forums at the Claude Developers Discord

バグ報告については：

GitHub Issues: anthropics/skills/issues
Include: Skill name, error message, steps to reproduce

参照A: クイックチェックリスト

整理日: 2026-03-16

このチェックリストを使用して、アップロード前後にスキルを検証してください。より早く始めたい場合は、スキルクリエーターを使用して初稿を生成し、その後このリストを確認して、何も見落としていないか確認してください。

始める前に

2-3の具体的なユースケースを特定
使用するツールを特定（組み込みまたはMCP）
このガイドとサンプルスキルをレビュー
フォルダ構造を計画

開発中

フォルダ名はケバブケース
SKILL.mdファイルが存在（正確なスペル）
YAMLフロントマターに---区切りがある
nameフィールド: ケバブケース、スペースなし、大文字なし
descriptionにはWHATとWHENが含まれる
XMLタグ（< >）はどこにもない
指示は明確で実行可能
エラーハンドリングが含まれている
例が提供されている
参照が明確にリンクされている

アップロード前

明らかなタスクでトリガーをテスト
言い換えリクエストでトリガーをテスト
無関係なトピックでトリガーしないことを確認
機能テストが合格
ツール統合が機能する（該当する場合）
.zipファイルとして圧縮

アップロード後

実際の会話でテスト
過剰/不足トリガーを監視
ユーザーフィードバックを収集
説明と指示を反復
メタデータのバージョンを更新

参照B: YAMLフロントマター

整理日: 2026-03-16

必須フィールド

---
name: skill-name-in-kebab-case
description: What it does and when to use it. Include specific
trigger phrases.
---

--- name: スキル名-ケバブケース description: それが何をするか、いつ使用するかを説明します。特定のトリガーフレーズを含めてください。 ---

すべてのオプションフィールド

name: skill-name
description: [required description]
license: MIT # Optional: License for open-source
allowed-tools: "Bash(python:*) Bash(npm:*) WebFetch" # Optional:
Restrict tool access
metadata: # Optional: Custom fields
 author: Company Name
 version: 1.0.0
 mcp-server: server-name
 category: productivity
 tags: [project-management, automation]
 documentation: https: /example.com/docs
 support: [email protected]

名前: スキル名説明: [必須の説明] ライセンス: MIT # オプション: オープンソースのライセンス許可されたツール: "Bash(python:*) Bash(npm:*) WebFetch" # オプション: ツールアクセスの制限メタデータ: # オプション: カスタムフィールド著者: 会社名バージョン: 1.0.0 MCPサーバー: サーバー名カテゴリ: 生産性タグ: [プロジェクト管理, 自動化] ドキュメント: https: /example.com/docs サポート: [email protected]

セキュリティノート

許可されている:

すべての標準YAMLタイプ（文字列、数値、ブール値、リスト、オブジェクト）
カスタムメタデータフィールド
長い説明（最大1024文字）

禁止されている:

XMLの角括弧（< >） - セキュリティ制限
YAML内でのコード実行（安全なYAML解析を使用）
"claude"または"anthropic"プレフィックスで名付けられたスキル（予約済み）

このガイドのパターンを示す完全な生産準備が整ったスキルのために:

ドキュメントスキル - PDF、DOCX、PPTX、XLSXの作成
サンプルスキル - 様々なワークフローパターン
パートナースキルディレクトリ - Asanaなどの様々なパートナーからのスキルを表示, Atlassian、Canva、Figma、Sentry、Zapierなど

これらのリポジトリは最新の状態を保ち、ここでカバーされているものを超えた追加の例を含んでいます。クローンして、あなたのユースケースに合わせて修正し、テンプレートとして使用してください。

翻訳元のオリジナル版 The Complete Guide to Building Skills for Claude

何か間違いや問題があればご連絡ください。 @ysk_en までご連絡ください。

目次

イントロダクション

基本原則

スキルとは何か？

構造図

コアデザイン原則

MCPビルダー向け：スキル + コネクタ

キッチンのアナロジー

これがあなたのMCPユーザーにとって重要な理由

計画と設計

使用ケースから始める

一般的なスキル使用ケースカテゴリ

成功基準を定義する

技術要件

効果的なスキルの記述

例

トラブルシューティング

テストと反復

推奨テストアプローチ

スキルクリエイターのスキルを使用して

配布と共有

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

オープンスタンダード

APIを介したスキルの使用

今日の推奨アプローチ

スキルの位置付け

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

パターン1：逐次ワークフローオーケストレーション

パターン2：マルチMCP調整

パターン3：反復的な改善

パターン4: コンテキストに応じたツール選択

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

トラブルシューティング

MCP接続の問題

リソースと参考文献

公式ドキュメント

ツールとユーティリティ

サポートを受ける

参照A: クイックチェックリスト

始める前に

開発中

アップロード前

アップロード後

参照B: YAMLフロントマター

必須フィールド

すべてのオプションフィールド

セキュリティノート