skill-creator

スキル作成

このスキルでは、効果的なスキルを作成するための指針を提供します。

スキルについて

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

スキルが提供するもの

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

スキルの構成

すべてのスキルは、必須の 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 intended to be loaded into context as needed
    └── assets/           - Files used in output (templates, icons, fonts, etc.)

SKILL.md（必須）

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

バンドルリソース（任意）

スクリプト（scripts/）

確実な再現性が求められるタスクや、何度も書き直されるタスクに使用する実行可能なコード（Python/Bash など）です。

• 含めるタイミング：同じコードを繰り返し書き直している場合、または確実な再現性が必要な場合
• 例：PDF の回転タスク用の scripts/rotate_pdf.js
• メリット：トークン効率が高く、結果の再現性があり、コンテキストに読み込まずに実行できる場合があります
• 注記：パッチ適用や環境固有の調整を行うために、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
• 用途：テンプレート、画像、アイコン、ひな形コード、フォント、コピーまたは編集するサンプル文書
• メリット：出力用リソースをドキュメントから分離できるため、コンテキストに読み込まずにファイルを使用できます

段階的開示の設計原則

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

1. メタデータ（name + description）- 常にコンテキスト内にあります（約 100 語）
2. SKILL.md 本文 - スキルが起動したときに読み込まれます（5k 語未満）
3. バンドルリソース - Claude が必要に応じて読み込みます（無制限*）

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

スキル作成プロセス

スキルを作成するには、明確な理由があって該当しない場合を除き、「スキル作成プロセス」を順番に進めてください。

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

スキルの使用パターンをすでに明確に理解している場合に限り、このステップを省略してください。既存のスキルを扱う場合でも、このステップは役に立ちます。

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

たとえば、画像編集スキルを作成する場合、次のような質問が考えられます。

• 「画像編集スキルでは、どのような機能をサポートすべきですか？編集、回転、それ以外にもありますか？」
• 「このスキルがどのように使われるか、いくつか例を挙げてもらえますか？」
• 「『この画像の赤目を修正して』や『この画像を回転して』といった依頼が考えられます。他にも、このスキルの使い方として思い当たるものはありますか？」
• 「どのような依頼があれば、このスキルを使うべきでしょうか？」

ユーザーに一度に多くの質問をして負担をかけないようにしてください。最も重要な質問から始め、必要に応じて効果を高めるための質問を続けてください。

このステップは、スキルがサポートすべき機能を明確に把握できた時点で完了です。

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

具体例を効果的なスキルにするには、各例を次のように分析します。

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

例：「この PDF を回転するのを手伝って」という依頼に対応する pdf-editor スキルを作成する場合、分析結果は次のようになります。

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

例：「ToDo アプリを作って」や「歩数を追跡するダッシュボードを作って」という依頼に対応する frontend-webapp-builder スキルを設計する場合、分析結果は次のようになります。

1. フロントエンドのウェブアプリを作成するには、毎回同じ 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>

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

• 指定したパスにスキルディレクトリを作成する
• 適切なフロントマターと 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：スキルを検証する

スキルの準備ができたら、使用前にすべての要件を満たしていることを確認するため、quick_validate.py スクリプトで検証してください。

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

このスクリプトは次の項目を確認します。

• YAML フロントマターの形式と必須フィールド
• スキルの命名規則とディレクトリ構成
• 説明の完全性と品質
• ファイルの整理状況とリソース参照

エラーが報告された場合は修正し、検証に合格するまで再実行してください。

注： package_skill.py は使用しないでください。手動で展開する必要がある ZIP ファイルが作成され、一時ファイルが残るためです。スキルのディレクトリはすでに正しい場所にあり、パッケージ化する必要はありません。

ステップ 6：反復する

スキルをテストした後、ユーザーから改善を依頼される場合があります。スキルを使用した直後で、スキルの動作について新鮮な文脈があるときに依頼されることがよくあります。

反復ワークフロー：

1. 実際のタスクでスキルを使う
2. 難しかった点や非効率な点に気づく
3. SKILL.md または同梱リソースの更新内容を特定する
4. 変更を実装し、再度テストする