skill-creator

⚠️ パフォーマンスに関する注意：この Skill には評価システム一式（Grader／Comparator／Analyzer）が含まれており、重要な Skill の作成時に適しています。シンプルな Skill では、評価の工程を省略できます。

Skill Creator

この Skill では、高品質な Skills を作成するための完全なワークフローを案内します。

Skills について

Skills は、専門分野の知識、ワークフロー、ツールを提供して Claude の能力を拡張する、モジュール型で自己完結したパッケージです。特定の分野やタスクの「オンボーディングガイド」と考えることができます。Skills によって、Claude は汎用エージェントから、手順に関する知識を備えた専門エージェントへと変わります。

Skills が提供する価値

1. 専門的なワークフロー - 特定分野における複数ステップのプロセス
2. ツールとの連携 - 特定のファイル形式や API を扱うための指示
3. 分野の専門知識 - 企業固有の知識、パターン、ビジネスロジック
4. リソースのパッケージ化 - 複雑で反復的なタスクのためのスクリプト、参考資料、アセット

基本原則

簡潔さを最優先する

コンテキストウィンドウは共有リソースです。Skills は、システムプロンプト、会話履歴、他の Skills のメタデータ、実際のユーザーリクエストなど、Claude が必要とするあらゆる情報とコンテキストウィンドウを共有します。

Claude はすでに非常に賢いことを前提にしてください。 Claude が持っていないコンテキストだけを追加します。情報をひとつずつ見直し、「この説明は本当に Claude に必要か」「この文章にかかるトークン数は妥当か」と問いかけてください。

長い説明の代わりに、簡潔な例を使います。

適切な自由度を設定する

タスクの壊れやすさと変動性に応じて、指示の具体性を設定します。

自由度	種類	使用場面
高自由度	テキストベースの指示	複数の方法が有効で、判断がコンテキストに依存する場合
中自由度	擬似コードまたはパラメーター付きスクリプト	推奨されるパターンがあり、ある程度の変化が許容される場合
低自由度	特定のスクリプト、少数のパラメーター	操作が壊れやすくエラーになりやすい場合、一貫性が重要な場合、特定の順序に従う必要がある場合

Claude が道を探す場面を想像してください。狭い崖の上の橋では具体的なガードレール（低自由度）が必要ですが、開けた野原では複数の経路を選べます（高自由度）。

Skill の構成

各 Skill は、必須の 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 が Skill を使用するタイミングを判断する唯一の手掛かりであるため、Skill の機能と起動条件を明確に説明することが重要です。
• Body (Markdown)：Skill の使用方法に関する説明とガイダンスです。Skill が有効になった後にのみ読み込まれます。

パッケージ化するリソース

Scripts (scripts/)

確実な処理結果が必要なタスクや、同じコードを繰り返し書き直すタスク向けの実行可能コードです。

• 含めるタイミング：同じコードを繰り返し書き直す場合、または確実な処理結果が必要な場合
• 例：PDF を回転するタスクの scripts/rotate_pdf.py
• 利点：トークン効率が高く、処理結果が安定しており、コンテキストに読み込まずに実行できます

References (references/)

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

• 含めるタイミング：Claude が参照するべきドキュメントがある場合
• 例：財務パターンの references/finance.md、API ドキュメントの references/api_docs.md
• ベストプラクティス：ファイルが大きい場合（>10k 字）は、SKILL.md に grep の検索パターンを記載します

Assets (assets/)

コンテキストへの読み込みを想定せず、Claude が生成する出力に使用するファイルです。

• 含めるタイミング：最終出力に使用するファイルが Skill に必要な場合
• 例：ブランドアセットの assets/logo.png、テンプレートの assets/frontend-template/

Skill に含めないもの

Skill には、その機能を直接支える必須ファイルのみを含めてください。次のような余分なドキュメントや補助ファイルは作成しないでください。

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

Skill には、AI エージェントがそのタスクを実行するために必要な情報だけを含めてください。作成に至った経緯に関する補足情報、セットアップやテストの手順、ユーザー向けドキュメントなどは含めないでください。ドキュメントファイルを追加すると、雑然として混乱を招くだけです。

段階的開示の設計原則

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

1. メタデータ（name + description） - 常にコンテキスト内にあります（約100語）
2. SKILL.md の本文 - Skill の起動時に読み込まれます（<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 (overview and navigation)
└── reference/
    ├── finance.md (revenue, billing metrics)
    ├── sales.md (opportunities, pipeline)
    ├── product.md (API usage, features)
    └── marketing.md (campaigns, attribution)

ユーザーが売上指標について尋ねた場合、Claude は sales.md だけを読み込みます。

同様に、複数のフレームワークやバリエーションに対応するスキルでは、バリエーションごとに整理してください。

cloud-deploy/
├── SKILL.md (workflow + provider selection)
└── references/
    ├── aws.md (AWS deployment patterns)
    ├── gcp.md (GCP deployment patterns)
    └── azure.md (Azure deployment patterns)

ユーザーが 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. 反復的に改善する - 実際の使用フィードバックに基づいてスキルを最適化する

明確に該当しない理由がある場合にのみ、その手順を省略し、これらの手順に従ってください。

ステップ 5：評価と品質保証

スキルを作成した後は、厳格な品質評価を実施する必要があります。3 エージェント評価システムを使用します。

5.1 Grader（採点者）

役割：スキルの出力品質を厳格に評価します。

評価項目：

• 正確性 (1-5)：出力は質問に正確に答えていますか？
• 完全性 (1-5)：必要な手順をすべて網羅していますか？
• 実行可能性 (1-5)：指示は明確で実行可能ですか？
• 境界条件への対応 (1-5)：エラーや例外に適切に対処していますか？

判定基準：

• 平均点 ≥ 4.0/5 → 合格
• いずれかの項目が < 3 → 不合格
• それ以外 → 反復後に再評価

5.2 Comparator（ブラインド比較者）

役割：出力元を知らない状態で、スキルの出力とスキルを使わない出力を比較します。

比較項目：

• タスク達成度 (40%)：どちらがより適切に問題を解決していますか？
• コード品質 (25%)：どちらがより標準的で保守しやすいですか？
• 明確さ (20%)：どちらの説明がより明確ですか？
• 境界条件への対応 (15%)：どちらがより多くの境界条件を考慮していますか？

判定基準：

• スキルの出力が明らかに優れている割合が ≥ 60% → 評価合格
• それ以外 → 問題を診断して調整

5.3 Analyzer（分析者）

役割：評価データを集約し、原因を分析して改善案を提示します。

分析内容：

• 全体統計（合格率、平均点）
• 項目別分析（最高点／最低点／平均点）
• 成功パターン（再現可能な特徴）
• 失敗原因（根本的な問題）
• 改善案（P0/P1/P2 の優先順位順）

判定基準：

• P0 の改善案 < 1 → リリース可能
• P0 の改善案 ≥ 1 → 必ず修正
• P1 の改善案 < 3 → リリース可能
• P1 の改善案 ≥ 3 → 反復後にリリース

評価フローチャート

新 Skill → 收集测试用例 → Grader 评估
    ↓
  {通过?} 
  ├─ 是 → Comparator 盲测
  └─ 否 → 返回改进 → 重新收集用例
    ↓
  {A 更好?}
  ├─ 是 → Analyzer 分析
  └─ 否 → 问题诊断 → 调整 Skill
    ↓
  {改进建议 < 3?}
  ├─ 是 → 发布
  └─ 否 → 迭代改进

簡易評価ガイド

シンプルなスキル（< 3KB）：

1. テストケースを 5 件用意する
2. Grader による評価（1 回）
3. Comparator によるブラインドテスト（1 回）
4. 合格したらリリースする

複雑なスキル（> 10KB または複数機能）：

1. テストケースを 20 件用意する（ハッピーパス 10 件 + エッジケース 10 件）
2. Grader による評価（3 回、各回で最適化）
3. Comparator によるブラインドテスト（2 回）
4. Analyzer による完全な分析
5. 提案に基づいて反復する
6. 最終リリース審査を行う

詳細な評価ドキュメント：完全なエージェント定義、評価テンプレート、ベストプラクティスについては、AGENTS.md を参照してください。

ステップ 6：反復的な改善

評価フィードバックに基づき、継続的に最適化します。

1. 実際のフィードバックを収集する

   • ユーザーの利用データ（使用回数、成功率）
   • 評価結果（Grader/Comparator/Analyzer）
   • エラーレポートと境界条件

2. 優先順位を決める

   • P0：コア機能に影響するバグ
   • P1：重要なユーザー体験上の問題
   • P2：最適化の提案

3. 小刻みに反復する

   • 各反復では 1～2 件の問題に集中する
   • 一度に大幅な変更を加えることは避ける
   • 変更のたびに再評価する

4. リリースのペース

   • シンプルな修正：随時リリース
   • 機能の調整：毎週リリース
   • 大幅な変更：毎月リリース

ステップ 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 <skill-name> --path <output-directory>

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

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

name と description を含む YAML frontmatter を記述してください。

• 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. パッケージ化：検証に合格した場合、スキル名に基づく名前（例：my-skill.skill）の .skill ファイルを作成します。このファイルにはすべてのファイルが含まれ、配布に適したディレクトリ構造が維持されます。.skill ファイルは、拡張子が .skill の ZIP ファイルです。

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

ステップ 6：反復する

スキルをテストした後、ユーザーから改善を求められることがあります。多くの場合、これはスキルを使用した直後に、その性能に関する新鮮なコンテキストがある状態で行われます。

反復ワークフロー：

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