skill_creator

スキル作成

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

スキルについて

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

スキルが提供するもの

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

基本原則

簡潔さが重要

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

基本的な前提：Claude はすでに非常に高い能力を備えています。 Claude がすでに知っていることは追加せず、それ以外のコンテキストだけを加えてください。情報の一つひとつについて、「Claude に本当にこの説明が必要か？」「この段落はトークンを使う価値があるか？」と問い直してください。

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

適切な自由度を設定する

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

自由度が高い（テキストベースの指示）：複数の方法が有効な場合、状況に応じて判断する場合、またはヒューリスティックに沿って進める場合に使います。

自由度が中程度（疑似コードやパラメーター付きスクリプト）：望ましいパターンがある一方で、ある程度の違いが許容される場合や、設定が動作に影響する場合に使います。

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

Claude が道を探しているところを想像してください。崖に挟まれた細い橋には具体的なガードレール（低い自由度）が必要ですが、開けた場所ならさまざまなルートを選べます（高い自由度）。

スキルの構成

すべてのスキルには、必須の 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（必須）

すべての SKILL.md は次の要素で構成されます。

• フロントマター（YAML）：name と description のフィールドを含みます。スキルを使用するかどうかを Claude が判断する際に読み取るのはこの 2 つのフィールドだけです。そのため、スキルの内容と使用すべき場面を明確かつ包括的に記述することが非常に重要です。
• 本文（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 が必要と判断したときだけ読み込まれます
• ベストプラクティス: ファイルが大きい場合（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 が利用できます

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

スキルには、その機能を直接支える必須ファイルだけを含めるべきです。以下のような付随的なドキュメントや補助ファイルは作成しないでください。

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

スキルには、AI エージェントが当面の作業を遂行するために必要な情報だけを含めるべきです。スキルを作成する過程に関する補足的な文脈、セットアップやテストの手順、ユーザー向けのドキュメントなどは含めるべきではありません。追加のドキュメントファイルは、雑然さと混乱を増やすだけです。

段階的開示（Progressive Disclosure）の設計原則

スキルは、コンテキストを効率的に管理するために三段階の読み込みの仕組みを用います。

1. メタデータ（name + description） - 常にコンテキストに存在（約 100 語）
2. SKILL.md の本文 - スキルが発動したときに読み込み（5,000 語未満）
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. 実際の使用状況に基づいて反復する

明確に該当しない理由がある場合に限り、その手順を省略し、それ以外は順番どおりに進めてください。

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

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

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

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

• 「画像エディタースキルでは、どのような機能に対応すべきですか？編集、回転、それ以外にもありますか？」
• 「このスキルをどのように使うか、例をいくつか挙げてもらえますか？」
• 「『この画像の赤目を除去して』や『この画像を回転して』といった依頼が考えられます。他にも、どのような使い方があると思いますか？」
• 「どのような依頼があれば、このスキルを起動すべきですか？」

ユーザーを圧倒しないよう、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 インスタンスがこれらのタスクをより効果的に実行するために役立つ、手順に関する知識、ドメイン固有の詳細、再利用可能なアセットを検討してください。

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

スキルのニーズに応じて、次の便利なガイドを参照してください。

• 複数ステップのプロセス：順次ワークフローと条件分岐については references/workflows.md を参照してください
• 特定の出力形式または品質基準：テンプレートとサンプルのパターンについては references/output-patterns.md を参照してください

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

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

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

追加したスクリプトは、バグがなく、出力が期待どおりであることを確認するため、実際に実行してテストしてください。似たスクリプトが多数ある場合は、完了までの時間とのバランスを取りながら、すべてが正しく動作するという確信を得るために、代表的なサンプルだけをテストすれば十分です。

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

SKILL.md を更新する

執筆ガイドライン： 常に命令形または不定詞形を使ってください。

フロントマター

name と description を含む YAML フロントマターを記述してください。

• name：スキル名
• description：スキルを呼び出すための主な仕組みであり、Claude がスキルを使うべき状況を理解するのに役立ちます。
  • スキルが行うことと、使用すべき具体的なトリガーや状況の両方を含めてください。
  • 「いつ使うか」に関する情報はすべてここに含めてください。本文には含めないでください。本文はトリガー後にのみ読み込まれるため、「このスキルを使う場面」のセクションを本文に置いても Claude の役には立ちません。
  • docx スキルの description の例：「変更履歴、コメント、書式の保持、テキスト抽出に対応した、ドキュメントの包括的な作成、編集、分析。Claude が業務用ドキュメント（.docx ファイル）を扱う必要がある場合に使用： （1）新しいドキュメントの作成、（2）コンテンツの変更や編集、（3）変更履歴の操作、（4）コメントの追加、その他のドキュメント関連作業」

YAML フロントマターには、ほかのフィールドを含めないでください。

本文

スキルと、同梱されているリソースの使い方を指示してください。

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

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

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

任意の出力ディレクトリを指定できます：

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

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

1. 検証：次の項目を確認し、スキルを自動的に検証します。

   • YAML フロントマターの形式と必須フィールド
   • スキルの命名規則とディレクトリ構造
   • description の網羅性と品質
   • ファイル構成とリソース参照

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

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

ステップ 6：反復する

スキルのテスト後、ユーザーから改善を求められることがあります。スキルを使った直後に、実際の動作について新鮮な記憶がある状態で依頼されることがよくあります。

Skill Creator v1.1 - Enhanced

🔄 ワークフロー

出典： Anthropic Building Effective Agents ＆ Agentic Design Patterns

フェーズ 1：定義とスコープ設定

• 単一の役割：スキルの目的が 1 つだけであることを確認してください（Unix Philosophy）。「何でもできる」スキルを作らないでください。
• トリガーの定義：スキルがいつ呼び出されるか（Description）を明確に定義してください。どのような言葉や状況が対象ですか？
• 具体的な入力：スキルの動作に必要な入力（Inputs）を列挙してください（ファイル、テキスト、API Key）。

ステージ 2：実装戦略

• 段階的な情報開示：すべてを SKILL.md に詰め込まないでください。詳細は references/ フォルダーに移し、必要に応じて読み込ませます。
• フューショットプロンプティング：指示を出す代わりに、例を示してください。「これをして」と言うのではなく、「入力例 → 出力例」を示します。
• 適切なエラー処理：API がダウンした場合やファイルがない場合など、Scripts フォルダー内のコードがエラー発生時にどう動作するかを計画します。

ステージ 3：パッケージ化と検証

• メタデータの確認：tags と category の各フィールドが正しく入力されていることを確認します。
• トークンの節約：SKILL.md ファイルが不要に冗長になっていないことを確認します。Claude はすでに賢いので、「こんにちは」の言い方を教える必要はありません。
• セルフテスト：Skill をパッケージ化する前に、自分の環境（シミュレーション）でテストします。

チェックポイント

ステージ	検証
1	Skill 名は verb-noun 形式ですか？（例：create-database、analyze-logs）。
2	Description フィールドは 1024 文字未満ですか？（コンテキストウィンドウの効率化）。
3	scripts/ 内のコードは本番環境で使える状態ですか？（エラー処理が含まれていますか？）。