Skill Creator

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

スキルについて

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

スキルが提供するもの

1. 特殊なワークフロー - 特定ドメイン向けの多段階手順
2. ツール統合 - 特定のファイル形式や API との連携方法に関する指示
3. ドメイン専門知識 - 企業固有の知識、スキーマ、ビジネスロジック
4. バンドルされたリソース - 複雑で繰り返しのあるタスク向けのスクリプト、参考資料、アセット

コア原則

簡潔さが最重要

コンテキストウィンドウは公共の資源です。スキルは、システムプロンプト、会話履歴、他のスキルのメタデータ、実際のユーザーリクエストなど、Claude が必要とするすべてのものとコンテキストウィンドウを共有します。

デフォルトの前提: Claude はすでに非常に賢い。 Claude がすでに知っていないコンテキストのみを追加してください。各情報に疑問を持つ: 「Claude は本当にこの説明が必要か?」「このパラグラフはトークンコストの価値があるか?」

冗長な説明より簡潔な例を優先してください。

適切な自由度を設定する

タスクの脆弱性と可変性に合わせて具体性のレベルを調整してください:

高い自由度 (テキストベースの指示): 複数のアプローチが有効な場合、決定がコンテキストに依存する場合、またはヒューリスティクスがアプローチを導く場合に使用します。

中程度の自由度 (疑似コードまたはパラメータ付きスクリプト): 好ましいパターンが存在する場合、何らかのバリエーションが許容される場合、または設定が動作に影響する場合に使用します。

低い自由度 (特定のスクリプト、少数のパラメータ): 操作が脆弱でエラーが起きやすい場合、一貫性が重要な場合、または特定の順序に従う必要がある場合に使用します。

Claude を経路を探索するものと考えてください: 崖がある狭い橋には具体的なガードレール (低い自由度) が必要で、広い平原は多くのルートを許容します (高い自由度)。

スキルの構成要素

すべてのスキルは必須の SKILL.md ファイルと、オプションのバンドルされたリソースで構成されます:

skill-name/
├── SKILL.md (必須)
│   ├── YAML frontmatter メタデータ (必須)
│   │   ├── name: (必須)
│   │   └── description: (必須)
│   └── Markdown 指示 (必須)
└── バンドルされたリソース (オプション)
    ├── scripts/          - 実行可能コード (Python/Bash など)
    ├── references/       - 必要に応じてコンテキストに読み込むことを想定したドキュメント
    └── assets/           - 出力で使用されるファイル (テンプレート、アイコン、フォントなど)

SKILL.md (必須)

すべての SKILL.md は以下で構成されます:

• Frontmatter (YAML): name と description フィールドを含みます。スキルを使用するタイミングを Claude が判断するために読み込む唯一のフィールドのため、スキルが何であり、いつ使用すべきかを明確かつ包括的に説明することが非常に重要です。
• 本体 (Markdown): スキル使用のための指示とガイダンス。スキルがトリガーされた後にのみ読み込まれます (読み込まれる場合)。

バンドルされたリソース (オプション)

スクリプト (scripts/)

決定論的な信頼性が必要な、または繰り返し書き直されるタスク向けの実行可能コード (Python/Bash など)。

• 含める場合: 同じコードが繰り返し書き直されている場合、または決定論的な信頼性が必要な場合
• 例: PDF 回転タスク向けの scripts/rotate_pdf.py
• 利点: トークン効率が良く、決定論的で、コンテキストに読み込まなくても実行できる可能性がある
• 注意: スクリプトは Claude がパッチ適用または環境固有の調整のために読む必要がある場合があります

リファレンス (references/)

Claude がプロセスと思考の過程で参照するためにコンテキストに必要に応じて読み込まれることを想定したドキュメントと参考資料。

• 含める場合: Claude が作業中に参照すべきドキュメンテーションがある場合
• 例: 財務スキーマ向けの references/finance.md、企業 NDA テンプレート向けの references/mnda.md、企業ポリシー向けの references/policies.md、API 仕様向けの references/api_docs.md
• 用途: データベーススキーマ、API ドキュメンテーション、ドメイン知識、企業ポリシー、詳細なワークフローガイド
• 利点: SKILL.md をスリムに保ち、Claude が必要と判断した場合のみ読み込まれます
• ベストプラクティス: ファイルが大きい場合 (10k 語以上)、SKILL.md に grep 検索パターンを含めてください
• 重複の回避: 情報は SKILL.md またはリファレンスファイルのいずれか一方に存在すべきで、両方には含めません。詳細情報についてはリファレンスファイルを優先します。スキルの中核でない限り、SKILL.md をスリムに保ちながら、コンテキストウィンドウを浪費せずに情報を発見可能にするためです。SKILL.md には本質的な手続き指示とワークフローガイダンスのみを保ち、詳細な参考資料、スキーマ、例はリファレンスファイルに移動してください。

アセット (assets/)

コンテキストに読み込まれることを想定していないが、Claude が生成する出力内で使用されるファイル。

• 含める場合: スキルが最終出力で使用されるファイルが必要な場合
• 例: ブランドアセット向けの assets/logo.png、PowerPoint テンプレート向けの assets/slides.pptx、HTML/React ボイラープレート向けの assets/frontend-template/、タイポグラフィ向けの assets/font.ttf
• 用途: テンプレート、画像、アイコン、ボイラープレートコード、フォント、コピーまたは変更対象のサンプルドキュメント
• 利点: 出力リソースをドキュメンテーションから分離し、Claude がファイルをコンテキストに読み込まずに使用できるようにします

スキルに含めるべきでないもの

スキルには、その機能を直接サポートする本質的なファイルのみを含めるべきです。以下のような余分なドキュメンテーション補助ファイルは作成しないでください:

• README.md
• INSTALLATION_GUIDE.md
• QUICK_REFERENCE.md
• CHANGELOG.md
• など

スキルには、AI エージェントがタスクを実行するために必要な情報のみを含めるべきです。スキル作成に使用されたプロセスに関する補助的なコンテキスト、セットアップとテスト手順、ユーザー向けドキュメントなどは含めるべきではありません。追加のドキュメンテーションファイルを作成すると、単に雑然さと混乱が増えるだけです。

プログレッシブディスクロージャー設計原則

スキルは、コンテキストを効率的に管理するために3段階のローディングシステムを使用します:

1. メタデータ (名前 + 説明) - 常にコンテキスト内 (~100 語)
2. SKILL.md 本体 - スキルがトリガーされた場合 (<5k 語)
3. バンドルされたリソース - Claude が必要に応じて (無制限。スクリプトはコンテキストウィンドウに読み込まずに実行できるため)

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

SKILL.md 本体を本質的な内容に保ち、コンテキスト肥大化を最小化するため 500 行以下に保ってください。このリミットに近づいた場合、コンテンツを別ファイルに分割してください。コンテンツを他のファイルに分割する場合、SKILL.md からそれらを参照し、いつ読むかを明確に説明することが非常に重要です。これにより、スキルの読者はそれらが存在することを認識し、いつ使用するかを知ることができます。

重要な原則: スキルが複数のバリエーション、フレームワーク、またはオプションをサポートする場合、SKILL.md にはコアワークフローと選択ガイダンスのみを保ちます。バリエーション固有の詳細 (パターン、例、設定) は別のリファレンスファイルに移動してください。

パターン 1: 高レベルガイドとリファレンス

# PDF Processing

## Quick start

Extract text with pdfplumber:
[code example]

## Advanced features

- **Form filling**: See [FORMS.md](FORMS.md) for complete guide
- **API reference**: See [REFERENCE.md](REFERENCE.md) for all methods
- **Examples**: See [EXAMPLES.md](EXAMPLES.md) for common patterns

Claude は必要な場合のみ FORMS.md、REFERENCE.md、EXAMPLES.md を読み込みます。

パターン 2: ドメイン固有の構成

複数のドメインをサポートするスキルの場合、無関連なコンテキストの読み込みを避けるためドメイン別にコンテンツを組織化してください:

bigquery-skill/
├── SKILL.md (概要とナビゲーション)
└── reference/
    ├── finance.md (収益、請求メトリクス)
    ├── sales.md (機会、パイプライン)
    ├── product.md (API 使用、機能)
    └── marketing.md (キャンペーン、アトリビューション)

ユーザーが営業メトリクスについて質問した場合、Claude は sales.md のみを読みます。

同様に、複数のフレームワークまたはバリエーションをサポートするスキルの場合、バリエーション別に組織化してください:

cloud-deploy/
├── SKILL.md (ワークフロー + プロバイダー選択)
└── references/
    ├── aws.md (AWS デプロイメントパターン)
    ├── gcp.md (GCP デプロイメントパターン)
    └── azure.md (Azure デプロイメントパターン)

ユーザーが AWS を選択した場合、Claude は aws.md のみを読みます。

パターン 3: 条件付き詳細

基本的なコンテンツを表示し、詳細なコンテンツにリンクしてください:

# DOCX Processing

## Creating documents

Use docx-js for new documents. See [DOCX-JS.md](DOCX-JS.md).

## Editing documents

For simple edits, modify the XML directly.

**For tracked changes**: See [REDLINING.md](REDLINING.md)
**For OOXML details**: See [OOXML.md](OOXML.md)

Claude はユーザーがこれらの機能を必要とする場合のみ REDLINING.md または OOXML.md を読みます。

重要なガイドライン:

• 深くネストされたリファレンスを避ける - リファレンスを SKILL.md から 1 階層深くに保ってください。すべてのリファレンスファイルは SKILL.md から直接リンクされるべきです。
• 長いリファレンスファイルを構造化する - 100 行以上のファイルの場合、Claude がプレビュー時に全体の範囲を見られるよう、上部に目次を含めてください。

スキル作成プロセス

スキル作成には以下のステップが含まれます:

1. 具体的な例によってスキルを理解する
2. 再利用可能なスキルコンテンツを計画する (スクリプト、リファレンス、アセット)
3. スキルを初期化する (init_skill.py を実行)
4. スキルを編集する (リソースを実装して SKILL.md を書く)
5. スキルをパッケージする (package_skill.py を実行)
6. 実際の使用に基づいて反復する

これらのステップを順番に従ってください。明確な理由がない限り、スキップしないでください。

ステップ 1: 具体的な例によってスキルを理解する

スキルの使用パターンがすでに明確に理解されている場合のみこのステップをスキップしてください。既存のスキルで作業する場合でも価値が残ります。

効果的なスキルを作成するには、スキルがどのように使用されるかについて具体的な例を明確に理解してください。この理解は、直接ユーザーの例またはユーザーフィードバックで検証された生成例から来ることができます。

たとえば、画像編集スキルを構築する場合、関連する質問には以下が含まれます:

• 「画像編集スキルはどの機能をサポートすべきか? 編集、回転、その他?」
• 「このスキルがどのように使用されるかの例を示してもらえますか?」
• 「『この画像の赤目を削除してください』や『この画像を回転してください』など、ユーザーが要求することを想像できます。このスキルが使用される他の方法はありますか?」
• 「スキルをトリガーするべきユーザーは何と言いますか?」

ユーザーを圧倒しないようにするために、単一のメッセージで質問が多すぎないようにしてください。最も重要な質問から始めて、より高い効果のために必要に応じてフォローアップしてください。

スキルがサポートすべき機能の明確な感覚があるときにこのステップを終了してください。

ステップ 2: 再利用可能なスキルコンテンツを計画する

具体的な例を効果的なスキルに変えるには、各例を以下のように分析してください:

1. ゼロからこの例を実行する方法を検討する
2. これらのワークフローを繰り返し実行する際にどのスクリプト、リファレンス、アセットが役立つかを特定する

例: 「PDF を回転させるのを手伝ってください」のようなクエリを処理するために pdf-editor スキルを構築する場合、分析は以下を示します:

1. PDF を回転させるには毎回同じコードを書き直す必要があります
2. scripts/rotate_pdf.py スクリプトをスキルに保存すると役立ちます

例: 「To Do アプリを作成してください」または「歩数を追跡するダッシュボードを作成してください」のようなクエリ向けの frontend-webapp-builder スキルを設計する場合、分析は以下を示します:

1. フロントエンド webapp を書くには毎回同じボイラープレート HTML/React が必要です
2. ボイラープレート HTML/React プロジェクトファイルを含む assets/hello-world/ テンプレートをスキルに保存すると役立ちます

例: 「今日ログインしたユーザーは何人?」のようなクエリを処理するために big-query スキルを構築する場合、分析は以下を示します:

1. BigQuery をクエリするには毎回テーブルスキーマと関係を再発見する必要があります
2. テーブルスキーマを文書化した references/schema.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 インスタンスが使用することを念頭に置いてください。Claude にとって有益で自明ではない情報を含めてください。別の Claude インスタンスがこれらのタスクをより効果的に実行するのに役立つ手続き知識、ドメイン固有の詳細、または再利用可能なアセットを検討してください。

実証済みの設計パターンを学ぶ

スキルのニーズに基づいて以下の有用なガイドを参照してください:

• 多段階プロセス: references/workflows.md を参照して、順序立ったワークフローと条件付きロジックを確認してください
• 特定の出力形式または品質基準: references/output-patterns.md を参照してテンプレートと例パターンを確認してください

これらのファイルには効果的なスキル設計に対する確立されたベストプラクティスが含まれています。

再利用可能なスキルコンテンツから始める

実装を開始するには、上記で特定した再利用可能なリソースから始めてください: scripts/、references/、assets/ ファイル。このステップはユーザー入力を必要とする場合があることに注意してください。たとえば、brand-guidelines スキルを実装する場合、ユーザーはブランドアセットまたはテンプレートを assets/ に保存するか、ドキュメンテーションを references/ に保存する必要があるかもしれません。

追加されたスクリプトは、実際に実行してバグがないことと、出力が期待されるものであることを確認するため、テストする必要があります。類似したスクリプトが多くある場合、すべてが機能することへの信頼を確保しながら完了時間のバランスを取るため、代表的なサンプルのみテストする必要があります。

スキルに不要な例ファイルとディレクトリは削除すべきです。初期化スクリプトは構造を示すために scripts/、references/、assets/ に例ファイルを作成しますが、ほとんどのスキルはそれらすべてを必要としません。

SKILL.md を更新する

作成ガイドライン: 常に命令形/不定詞形を使用してください。

Frontmatter

YAML frontmatter を name と description で書いてください:

• name: スキル名
• description: これはスキルの主要なトリガーメカニズムで、Claude がスキルをいつ使用するかを理解するのに役立ちます。
  • スキルが何を行うか、およびいつ使用するかについての特定のトリガー/コンテキストの両方を含めてください。
  • すべての「このスキルを使用する場合」情報をここに含める - 本体には含めません。本体はトリガー後にのみ読み込まれるため、本体の「このスキルを使用する場合」セクションは Claude にとって役立ちません。
  • docx スキルの説明例: 「追跡版変更、コメント、フォーマット保存、テキスト抽出のサポートを備えた包括的なドキュメント作成、編集、分析。Claude が専門的なドキュメント (.docx ファイル) を操作する必要がある場合に使用: (1) 新規ドキュメント作成、(2) コンテンツ変更または編集、(3) 追跡版変更の操作、(4) コメント追加、またはその他のドキュメントタスク」

YAML frontmatter に他のフィールドを含めないでください。

本体

スキルとそのバンドルされたリソースを使用するための指示を書いてください。

ステップ 5: スキルをパッケージする

スキルの開発が完了したら、ユーザーと共有される配布可能な .skill ファイルにパッケージ化する必要があります。パッケージプロセスは、すべての要件を満たしていることを確認するためにスキルを自動的に検証します:

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

オプションの出力ディレクトリ指定:

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

パッケージスクリプトは以下を行います:

1. 検証 スキルを自動的に、以下をチェックして:

   • YAML frontmatter の形式と必須フィールド
   • スキルの命名規則とディレクトリ構造
   • 説明の完全性と品質
   • ファイル構成とリソースリファレンス

2. パッケージ 検証に成功した場合、スキルをパッケージ化し、スキル名に基づいて名付けられた .skill ファイル (例: my-skill.skill) を作成します。これには、配布に適した、すべてのファイルと正しいディレクトリ構造が含まれます。.skill ファイルは .skill 拡張子を持つ zip ファイルです。

検証に失敗した場合、スクリプトはエラーを報告し、パッケージを作成せずに終了します。検証エラーを修正し、パッケージングコマンドを再度実行してください。

ステップ 6: 反復する

スキル使用後、ユーザーは改善をリクエストする可能性があります。これはしばしばスキル使用直後に、スキルがどのように動作したかについて新しいコンテキストで発生します。

反復ワークフロー:

1. 実際のタスクでスキルを使用する
2. 努力や非効率を認識する
3. SKILL.md またはバンドルされたリソースをどのように更新すべきかを特定する
4. 変更を実装して再度テストする