skill-creator

スキル作成ツール

このスキルは、効果的なスキルを作成するためのガイダンスを提供します。

スキルについて

スキルは、専門知識、ワークフロー、ツールを提供してClaudeの機能を拡張する、モジュール式の自己完結型パッケージです。特定の分野やタスクに特化した「オンボーディングガイド」のようなものと考えてください。Claudeを、どのモデルも完全には備えられない手続き的な知識を備えた汎用エージェントから専門エージェントへと変えます。

スキルのカテゴリ

スキルは、繰り返し実行するワークフローで最も力を発揮します。一般的なカテゴリは次の3つです。

1. ドキュメントとアセットの作成 — スタイルガイド、テンプレート、品質チェックリストを組み込んで、一貫性のあるドキュメント、プレゼンテーション、アプリ、デザインを生成します（例：frontend-design、docx-creator）
2. ワークフローの自動化 — 一貫した手法で複数ステップのプロセスを実行し、複数のMCPサーバー間の調整も行います（例：skill-creator、sprint-planner）
3. MCPの拡張 — 既存のMCPツールへのアクセスにワークフローのガイダンスを重ね、サービスで何ができるかだけでなく、効果的な使い方もClaudeに教えます（例：sentry-code-review）

設計の基本原則

段階的な情報開示

スキルは、コンテキストを効率的に管理するため、3段階の読み込みシステムを使用します。

1. メタデータ（名前＋説明） — 常にコンテキスト内にあります（約100語）
2. SKILL.mdの本文 — スキルが起動したときに読み込まれます（5,000語未満）
3. 同梱リソース — 必要に応じてClaudeが読み込みます（無制限*）

*スクリプトはコンテキストウィンドウに読み込まなくても実行できるため、無制限です。

合成可能性

Claudeは複数のスキルを同時に読み込めます。スキルはほかのスキルと連携してうまく動作するようにしてください。そのスキルだけが利用可能な機能だと想定してはいけません。

移植性

スキルはClaude.ai、Claude Code、APIで同じように動作します。一度作成すれば、変更を加えずにあらゆる環境で使用できます。

スキルとMCP

MCP連携では、スキルがツールへのアクセスに知識レイヤーを追加します。

	MCP（接続性）	スキル（知識）
提供するもの	ツールへのアクセスとリアルタイムデータ	ワークフローとベストプラクティス
答える問い	Claudeにできること	Claudeがどのように実行すべきか

スキルがなければ、MCPサーバーに接続するユーザーは自分でワークフローを見つけなければならず、結果にばらつきが生じ、サポートの負担も増します。スキルにベストプラクティスを組み込むことで、自動的に適用されます。

5つの実績あるパターン（逐次オーケストレーション、複数MCP間の調整、反復的な改善、コンテキストに応じたツール選択、ドメイン固有のインテリジェンス）については、references/workflow-patterns.mdを参照してください。

スキルの構成

すべてのスキルは、必須のSKILL.mdファイルと任意の同梱リソースで構成されます。

skill-name/
├── SKILL.md (required)
│   ├── YAML frontmatter metadata (required)
│   │   ├── name: (required)
│   │   └── description: (required)
│   └── Markdown instructions (required)
└── Bundled Resources (optional)
    ├── scripts/          - Executable code (Python/Bash/etc.)
    ├── references/       - Documentation loaded into context as needed
    └── assets/           - Files used in output (templates, icons, fonts, etc.)

重要：スキルフォルダー内にREADME.mdを含めないでください。 ドキュメントはすべてSKILL.mdまたはreferences/に記載します。スキルをホストするGitHubリポジトリの訪問者向けに、リポジトリのルートにREADMEを置くのは問題ありませんが、スキルフォルダー内に置いてはいけません。

SKILL.md

メタデータの品質： YAMLフロントマターのnameとdescriptionによって、Claudeがスキルを使用するタイミングが決まります。スキルが何を行うか、いつ使用するかを具体的に記述してください。「このスキルを使用してください」のような表現ではなく、「このスキルは、…の場合に使用します」のような三人称の表現を使ってください。

YAMLフロントマターのフィールド：

---
name: skill-name-in-kebab-case          # required; lowercase, hyphens only, max 64 chars
description: What it does and when.     # required; WHAT + WHEN, max 1024 chars
license: MIT                            # optional; for open-source skills
allowed-tools: "Bash(python:*) WebFetch" # optional; restrict available tools
compatibility: Requires internet access  # optional; environment requirements, 1-500 chars
metadata:                               # optional; custom key-value pairs
  author: Your Name
  version: 1.0.0
  mcp-server: your-service-name
  tags: [automation, productivity]
---

セキュリティ上の制限：

• フロントマター内では、XMLの山かっこ（< >）をどこにも使用しないでください（システムプロンプトに表示されます）
• 「claude」または「anthropic」を接頭辞に含む名前は予約されています

効果的な説明の書き方 — 構成：[何をするか] + [いつ使うか] + [主な機能]

# Good — specific trigger phrases
description: Manages Linear project workflows including sprint planning and task
  creation. Use when user mentions "sprint", "Linear tasks", "project planning",
  or asks to "create tickets".

# Good — file types + trigger phrases
description: Analyzes Figma design files and generates developer handoff docs.
  Use when user uploads .fig files or asks for "design specs" or
  "design-to-code handoff".

# Bad — too vague, no triggers
description: Helps with projects.

過剰な起動を防ぐため、明示的な除外事項を追加してください。

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

同梱リソース（任意）

スクリプト（scripts/）

決定論的な信頼性が求められるタスクや、繰り返し書き直されるタスクに使用する実行可能なコード（Python／Bash など）です。

• 含める場合：同じコードを繰り返し書き直す場合、または決定論的な正確性が重要な場合
• 例：PDF の回転タスク用の scripts/rotate_pdf.py
• 利点：トークン効率が高く、決定論的で、コンテキストに読み込まずに実行できる場合があります
• 注記：パッチ適用や環境固有の調整のために、スクリプトを読み込む必要がある場合もあります

リファレンス（references/）

Claude のプロセスや思考に役立てるため、必要に応じてコンテキストに読み込むドキュメントや参考資料です。

• 含める場合：作業中に Claude が参照するドキュメント
• 例：データベーススキーマ用の references/schema.md、API 仕様用の references/api_docs.md、会社のポリシー用の references/policies.md
• ベストプラクティス：ファイルが大きい場合（>10k 語）は、SKILL.md に grep 検索パターンを記載します
• 重複を避ける：情報は SKILL.md または references ファイルのいずれかに記載し、両方には記載しないでください。SKILL.md は簡潔に保ち、詳細な参考資料、スキーマ、例は references ファイルに移します。

アセット（assets/）

Claude が生成する出力に使用するファイルで、コンテキストには読み込まれません。

• 含める場合：スキルが最終出力に含まれるファイルを必要とする場合
• 例：ブランド素材用の assets/logo.png、PowerPoint テンプレート用の assets/slides.pptx、HTML／React のひな形用の assets/frontend-template/
• 利点：出力用リソースをドキュメントと分離でき、コンテキストに読み込まずに Claude がファイルを使用できます

スキルの作成プロセス

スキルを作成するには、明確な理由がある場合にのみ手順を省略し、以下の順序で進めます。

ステップ 1：具体例を用いてスキルを理解する

使用パターンがすでに明確に把握できている場合にのみ省略します。

対象を絞った質問をして、具体的なユースケースを 2～3 件集めます。一度に質問しすぎてユーザーを圧倒しないようにします。

• 「このスキルはどのような機能をサポートすべきですか？」
• 「このスキルがどのように使われるか、例を挙げてもらえますか？」
• 「このスキルを使うには、ユーザーはどのように指示しますか？」

また、作成前に成功基準を定めます。

定量的な目標（大まかな基準）：

• 関連するクエリの約 90％でスキルが起動する（代表的なプロンプト 10～20 件でテスト）
• ワークフローごとのツール呼び出し回数が一貫している（スキルの有効／無効で比較）
• ワークフローごとの API 呼び出し失敗が 0 件（MCP に依存する場合）

定性的な目標：

• ワークフローの途中で Claude を誘導し直す必要がない
• セッションをまたいでも結果が一貫している
• 新しいユーザーが最小限のガイダンスで、初回からタスクを完了できる

機能の内容と成功の定義が明確になった時点で終了します。

ステップ 2：再利用可能なスキルの内容を計画する

具体例を効果的なスキルに変えるため、各例について次の点を分析します。

1. 最初から実行する方法を検討する
2. 繰り返し実行する際に役立つスクリプト、リファレンス、アセットを特定する

ユースケース	分析	リソース
「この PDF を回転して」	同じコードを毎回書き直す	scripts/rotate_pdf.py
「ToDo アプリを作って」	同じ HTML／React のひな形を毎回使う	assets/hello-world/ テンプレート
「ログインしたユーザー数は？」	テーブルスキーマを毎回再確認する	references/schema.md
「Sentry 経由でこの PR をレビューして」	複雑な複数 MCP のワークフロー	SKILL.md に記載する構造化された手順

含める再利用可能なリソースの一覧を作成します。

ステップ 3：スキルを初期化する

スキルがすでに存在し、反復のみが必要な場合に限り、スキップしてください。

新しいスキルをゼロから作成する場合は、必ず init_skill.py スクリプトを実行してください。

scripts/init_skill.py <skill-name> --path <output-directory>

このスクリプトは次の処理を行います。

• 適切な構成でスキルディレクトリを作成します
• frontmatter と TODO プレースホルダーを含む SKILL.md テンプレートを生成します
• サンプルのリソースディレクトリとして scripts/、references/、assets/ を作成します
• カスタマイズまたは削除できるサンプルファイルを各ディレクトリに追加します

初期化後、必要に応じて生成された SKILL.md とサンプルファイルをカスタマイズまたは削除してください。

ステップ 4：スキルを編集する

このスキルは、別の Claude インスタンスが使用するために作成されています。手順に関する知識、ドメイン固有の詳細、そして自明ではない再利用可能なアセットに重点を置いてください。

まず再利用可能なスキルの内容から始める

ステップ 2 で特定したリソース（scripts/、references/、assets/ ファイル）を最初に実装してください。ドメイン固有の内容（ブランドアセット、会社のポリシー、API ドキュメントなど）には、ユーザーからの入力が必要な場合があります。

スキルに不要なサンプルファイルは削除してください。初期化スクリプトは構成を示すプレースホルダーを作成しますが、ほとんどのスキルですべてが必要になるわけではありません。

SKILL.md を更新する

文体： 二人称ではなく、命令形／不定詞形（動詞から始める）を使用してください。「X を達成するには、Y を実行する」と書き、「Y を実行するべきです」とは書かないでください。これにより、AI が理解しやすい一貫した明確な内容になります。

SKILL.md を完成させるため、次の質問に答えてください。

1. このスキルの目的は何ですか？
2. どのような場合に使用すべきですか？
3. バンドルされている各リソースを Claude がどのように使用すべきですか？

重要な指示のガイドライン：

• 重要な指示は上部に配置し、## Critical または ## Important の見出しを使用してください
• 必ず従う必要がある検証では、言語による指示よりも決定的なスクリプトを優先してください。コードは信頼できますが、言語の解釈はそうではありません。

  CRITICAL: Before calling create_project, run scripts/validate_input.py
  

• 詳細なドキュメントは references/ に移動してリンクし、SKILL.md は 5,000 語未満にしてください
• 順序が重要な手順は明示的に番号を付け、手順間の依存関係を記載してください

MCP を強化するスキルでは、次の内容も含めてください。

• 正確な MCP ツール名（サーバー上の表記と大文字・小文字を一致させる）
• ワークフローの各段階での検証
• よくある MCP の障害（認証、レート制限、タイムアウト）へのエラー処理

ステップ 5：スキルをテストする

次の 3 種類のテストを実行してください。

1. トリガーテスト — スキルは適切なタイミングで読み込まれますか？

• スキルを起動するはずの明確なクエリをテストします
• それらのクエリを言い換えたバージョンをテストします
• 無関係なトピックでは起動しないことを確認します
• デバッグのヒント：「[skill name] スキルはどのような場合に使用しますか？」と Claude に尋ねます。Claude が説明を引用するため、不足点が明らかになります

2. 機能テスト — スキルは正しい出力を生成しますか？

• 有効な出力が生成されることを確認します
• API／MCP 呼び出しが成功することを確認します（該当する場合）
• エラー処理の経路をテストします
• エッジケースを網羅します

3. パフォーマンスの比較 — スキルによって結果は改善しますか？

• 同じタスクをスキルあり／なしで実行します
• やり取りの往復回数、失敗した API 呼び出し回数、消費トークン数を比較します

効果的な反復戦略： Claude が成功するまで、難易度の高いタスクを 1 つに絞ってください。その後、うまくいった方法をスキルに取り込みます。動作する基盤ができたら、網羅性を高めるために複数のテストケースへと拡張してください。

ステップ 6：スキルをパッケージ化する

scripts/package_skill.py <path/to/skill-folder>

出力ディレクトリは任意です。

scripts/package_skill.py <path/to/skill-folder> ./dist

パッケージ化スクリプトは次の処理を行います。

1. スキルを検証し、次の項目を確認します。

   • YAML frontmatter の形式と必須フィールド
   • 命名規則とディレクトリ構成
   • 説明の完全性と品質
   • スキルフォルダー内に README.md がないこと

2. 検証に合格した場合、配布可能な zip ファイルにパッケージ化します

検証に失敗した場合は、検証エラーを修正して再実行してください。

ステップ 7：配布する

個人／オープンソースの場合：

1. GitHub で公開し、人間の訪問者向けにリポジトリレベルの README を用意します（スキルフォルダー内ではありません）
2. MCP を強化するスキルの場合は、MCP のドキュメントからスキルにリンクし、両方を一緒に使うメリットを説明します
3. Settings > Capabilities > Skills > Upload へユーザーを案内するインストールガイドを用意します

組織の場合（2026 年 1 月以降）：

• 管理者は Claude Console を通じて、ワークスペース全体にスキルをデプロイできます
• 自動更新と一元管理を利用できます

プログラムまたは API から使用する場合：

• /v1/skills エンドポイントを使用して、スキルの一覧表示と管理を行います
• container.skills パラメーターを使って、Messages API リクエストにスキルを追加します
• Code Execution Tool ベータ版が必要です

ステップ 8：反復する

テスト後、確認できた兆候に基づいて改善します。

トリガー不足（関連するクエリでスキルが読み込まれない、ユーザーが手動で呼び出している）：

• 説明に、より具体的なトリガーフレーズを追加します
• 技術用語やユーザーが実際に使う正確な表現を含めます
• Claude に「[skill name] はどのようなときに使いますか？」と尋ね、見落としを明らかにします

トリガー過多（無関係なクエリでスキルが読み込まれる、ユーザーが無効にしている）：

• 否定的なトリガー（「次の場合には使わないでください…」）を追加します
• より具体的な表現で説明の対象範囲を絞ります

実行上の問題（結果に一貫性がない、ユーザーが出力を修正する、MCP 呼び出しに失敗する）：

• 重要な指示を SKILL.md の冒頭に移します
• 曖昧な表現を、決定論的な検証スクリプトに置き換えます
• 手順の順序とエラー処理を明示します

トラブルシューティング

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

エラー	原因	対処方法
"Invalid frontmatter"	--- 区切りがない、または引用符が閉じられていない	区切りを追加し、YAML 構文を修正します
"Invalid skill name"	名前にスペース、大文字、またはアンダースコアが含まれている	kebab-case に名前を変更します
"Could not find SKILL.md"	ファイル名が正確に SKILL.md ではない	ファイル名を変更します（大文字と小文字を区別します）

指示に従わない

• 重要な指示を冒頭に移し、## Critical ／ ## Important の見出しを使用します
• 言語ベースの検証を、実行可能なスクリプトに置き換えます（コードは決定論的です）
• 指示は簡潔かつ明確にし、詳細な内容は references/ に移します
• Claude が手順を省略する場合：「時間をかけてください。速度より品質を優先してください。検証手順を省略しないでください。」を追加します（SKILL.md よりもユーザーのプロンプトに置いた場合に最も効果的です）

スキルのコンテキストが大きすぎる／応答が遅い

• SKILL.md は 5,000 語未満にします
• 詳細なドキュメントは references/ に移し、SKILL.md からリンクします
• 同時に有効にするスキルは 20～50 個に制限します

リソース

• Anthropic のスキルに関するドキュメント
• スキルのサンプルリポジトリ — anthropics/skills
• スキルのベストプラクティスガイド
• Claude Developers Discord — コミュニティサポート
• references/workflow-patterns.md — MCP と自動化ワークフローの実証済みパターン 5 つ