スキル作成ガイド

Skill Creator

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

スキルについて

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

スキルが提供するもの

1. 専門ワークフロー - 特定ドメイン向けの複数ステップ手順
2. ツール連携 - 特定のファイル形式やAPIを扱うための指示
3. ドメイン専門知識 - 企業固有の知識、スキーマ、ビジネスロジック
4. バンドルリソース - 複雑で反復的なタスクのためのスクリプト、リファレンス、アセット

スキルの構成

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

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

SKILL.md (必須)

メタデータの品質: YAML frontmatterのnameとdescriptionは、Claudeがスキルを使用するタイミングを決定します。スキルの機能と使用タイミングについて具体的に記述してください。三人称を使用してください（例：「このスキルは...場合に使用すべき」）。

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

スクリプト (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が必要と判断した場合にのみ読み込まれる
• ベストプラクティス: ファイルが大きい場合（10,000語超）は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がファイルをコンテキストに読み込まずに使用できるようにする

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

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

1. メタデータ（名前＋説明） - 常にコンテキスト内 (~100語)
2. SKILL.md本文 - スキルトリガー時 (<5,000語)
3. バンドルリソース - 必要に応じてClaudeが使用 (無制限*)

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

スキル作成プロセス

スキルを作成するには、「スキル作成プロセス」を順に従ってください。適用できない明確な理由がある場合のみステップをスキップしてください。

ステップ1: 具体例を用いたスキルの理解

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

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

例えば、画像編集スキルを構築する場合、関連する質問は次のとおりです。

• 「画像編集スキルはどのような機能をサポートすべきですか？ 編集、回転、その他？」
• 「このスキルがどのように使用されるか、例をいくつか挙げていただけますか？」
• 「ユーザーが『この画像の赤目を除去して』とか『この画像を回転して』などと依頼するケースが考えられます。他にこのスキルが使用されると思う方法はありますか？」
• 「ユーザーがどのような発言をしたら、このスキルをトリガーすべきですか？」

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

スキルがサポートすべき機能の明確なイメージが得られたら、このステップを終了します。

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

具体例を効果的なスキルに変換するには、各例を次の手順で分析します。

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

例: 「このPDFを回転して」のようなクエリを処理するpdf-editorスキルを構築する場合、分析は次のようになります。

1. PDFの回転には毎回同じコードを書き直す必要がある
2. scripts/rotate_pdf.pyスクリプトをスキルに保存すると便利

例: 「TODOアプリを作って」や「歩数を追跡するダッシュボードを作って」のようなクエリを処理するfrontend-webapp-builderスキルを設計する場合、分析は次のようになります。

1. フロントエンドWebアプリの作成には毎回同じボイラープレートHTML/Reactが必要
2. ボイラープレートHTML/Reactプロジェクトファイルを含むassets/hello-world/テンプレートをスキルに保存すると便利

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

1. BigQueryへのクエリには毎回テーブルスキーマとリレーションシップを再発見する必要がある
2. テーブルスキーマを文書化したreferences/schema.mdファイルをスキルに保存すると便利

スキルの内容を確立するには、各具体例を分析して、含める再利用可能なリソース（スクリプト、リファレンス、アセット）のリストを作成します。

ステップ3: スキルの初期化

ここで、実際にスキルを作成します。

このステップは、開発しようとしているスキルがすでに存在し、反復またはパッケージ化が必要な場合のみスキップしてください。その場合は次のステップに進みます。

新しいスキルをゼロから作成する場合は、必ずinit_skill.pyスクリプトを実行してください。このスクリプトは、スキルに必要なすべてを自動的に含む新しいテンプレートスキルディレクトリを便利に生成し、スキル作成プロセスをより効率的かつ信頼性の高いものにします。

使用方法:

scripts/init_skill.py <スキル名> --path <出力ディレクトリ>

このスクリプトは:

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

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

ステップ4: スキルの編集

（新しく生成された、または既存の）スキルを編集するときは、スキルが別のClaudeインスタンス用に作成されていることを忘れないでください。Claudeにとって有益で非自明な情報を含めることに焦点を当ててください。どのような手続き的知識、ドメイン固有の詳細、または再利用可能なアセットが別のClaudeインスタンスがこれらのタスクをより効果的に実行するのに役立つかを検討してください。

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

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

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

SKILL.mdの更新

記述スタイル: スキル全体を命令形/不定詞形（動詞で始まる指示）で記述し、二人称は使用しないでください。客観的で教示的な言語を使用してください（例：「Xを行うには、Yを実行する」であり、「Xを行う必要がある場合」や「Xを行う必要があるなら」ではありません）。これにより、AIが消費する際の一貫性と明確さが維持されます。

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

1. スキルの目的は何ですか？（数文で）
2. スキルはいつ使用すべきですか？
3. 実際に、Claudeはスキルをどのように使用すべきですか？ 上記で開発したすべての再利用可能なスキルコンテンツを参照し、Claudeがそれらをどのように使用するかを理解できるようにする必要があります。

ステップ5: スキルのパッケージ化

スキルの準備ができたら、配布可能なzipファイルにパッケージ化し、ユーザーと共有します。パッケージ化プロセスは、最初にスキルを自動的に検証して、すべての要件を満たしていることを確認します。

scripts/package_skill.py <スキルフォルダへのパス>

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

scripts/package_skill.py <スキルフォルダへのパス> ./dist

パッケージ化スクリプトは:

1. スキルを自動検証し、以下をチェックします:

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

2. 検証が成功した場合、スキルをパッケージ化し、スキル名（例：my-skill.zip）のzipファイルを作成します。このファイルにはすべてのファイルが含まれ、配布用の適切なディレクトリ構造が維持されます。

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

ステップ6: 反復

スキルをテストした後、ユーザーが改善をリクエストする場合があります。これは多くの場合、スキルを使用した直後、スキルのパフォーマンスに関する新鮮なコンテキストがある状態で発生します。

反復ワークフロー:

1. 実際のタスクでスキルを使用する
2. 問題点や非効率性に気づく
3. SKILL.mdまたはバンドルリソースをどのように更新すべきかを特定する
4. 変更を実装し、再度テストする