name: skill-creator description: 効果的なスキルを作成するためのガイド。ユーザーが新しいスキルを作成したい場合（または既存のスキルを更新したい場合）に使用します。スキルは専門知識、ワークフロー、ツール統合によってClaudeの機能を拡張します。

Skill Creator

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

スキルについて

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

スキルが提供するもの

専門ワークフロー - 特定ドメインのための複数ステップの手順
ツール統合 - 特定のファイル形式やAPIを扱うための指示
ドメインの専門知識 - 企業固有の知識、スキーマ、ビジネスロジック
バンドルリソース - 複雑で反復的なタスクのためのscripts/、references/、assets/

基本原則

簡潔さが鍵

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

前提: Claudeはすでに賢い。 Claudeがまだ持っていないコンテキストのみを追加してください。各情報に疑問を持ちましょう: 「Claudeは本当にこの説明が必要か?」「この段落はトークンコストに見合うか?」

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

適切な自由度を設定

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

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

中程度の自由度（疑似コードまたはパラメータ付きスクリプト）: 推奨パターンが存在する場合、ある程度の変動が許容される場合、または設定が動作に影響する場合に使用します。

低い自由度（特定のスクリプト、少数のパラメータ）: 操作が壊れやすくミスが起きやすい場合、一貫性が重要な場合、たは特定の手順順序を必ず守る必要がある場合に使用します。

Claudeが道を探索していると考えてください: 崖のある狭い橋には特定のガードレールが必要（低い自由度）ですが、開けた野原なら多くのルートが許されます（高い自由度）。

スキルの構成要素

すべてのスキルは必須のSKILL.mdファイルと任意のバンドルリソースで構成されます:

skill-name/
├── SKILL.md (必須)
│   ├── YAML frontmatter metadata (必須)
│   │   ├── name: (必須)
│   │   └── description: (必須)
│   └── Markdownの手順 (必須)
└── Bundled Resources (オプション)
    ├── scripts/          - 実行可能なコード（Python/Bashなど）
    ├── references/       - 必要に応じてコンテキストに読み込まれるドキュメント
    └── assets/           - 出力で使用されるファイル（テンプレート、アイコン、フォントなど）

SKILL.md (必須)

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

Frontmatter (YAML): nameとdescriptionフィールドを含みます。これらはClaudeがスキルをいつ使用するかを決定するために読み取る唯一のフィールドです。スキルが何であるか、いつ使用すべきかを明確かつ包括的に説明することが非常に重要です。
Body (Markdown): スキルを使用するための指示とガイダンス。スキルが発火した後にのみ（必要なら）読み込まれます。

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

Scripts (`scripts/`)

確定的な信頼性が必要なタスク、または繰り返し書き直されるタスクのための実行可能なコード（Python/Bashなど）。

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

References (`references/`)

Claudeの作業手順や思考を支えるために、必要に応じてコンテキストへ読み込まれることを想定したドキュメント／参照資料です。

含めるべき場合: Claudeが作業中に参照すべきドキュメント
例: 財務スキーマ用のreferences/finance.md、会社のNDAテンプレート用のreferences/mnda.md、会社ポリシー用のreferences/policies.md、API仕様用のreferences/api_docs.md
使用例: データベーススキーマ、APIドキュメント、ドメイン知識、会社ポリシー、詳細なワークフローガイド
利点: SKILL.mdをスリムに保てる／Claudeが必要と判断した場合にのみ読み込まれます
ベストプラクティス: ファイルが大きい場合（1万語超）、SKILL.mdにgrep検索パターンを含めてください
重複を避ける: 情報は SKILL.md か参照ファイルのどちらか一方に置いてください。詳細な情報についてはreferencesファイルを優先してください（それが本当にスキルの中核でない限り）。これによりSKILL.mdをスリムに保ちながら、コンテキストウィンドウを占有せずに情報を発見可能にします。SKILL.mdには必須の手続き的指示とワークフローガイダンスのみを保持し、詳細なリファレンス資料、スキーマ、例はreferencesファイルに移動してください。

Assets (`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（段階的開示）

スキルは、コンテキストを効率的に管理するために3レベルの読み込みシステムを使用します:

メタデータ (name + description) - 常にコンテキスト内（~100トークン）
SKILL.md本文 - スキルがトリガーされたとき（推奨<5000トークン）
バンドルリソース - 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階層まで（深くネストしない）。パスは常にフォワードスラッシュ（/）を使用。
長いリファレンスファイルを構造化 - 100行を超えるファイルの場合、Claudeがプレビュー時に全体像を把握できるように、先頭に目次を含めてください。

スキル作成プロセス

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

具体的な例でスキルを理解する
再利用可能なスキルコンテンツ（scripts/、references/、assets/）を計画する
スキルを初期化する（init_skill.pyを実行）
スキルを編集する（リソースを実装しSKILL.mdを書く）
スキルをパッケージ化する（package_skill.pyを実行）
実際の使用に基づいて反復する

これらのステップを順番に従ってください。適用できない明確な理由がある場合にのみスキップしてください。

ステップ1: 具体的な例でスキルを理解する

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

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

例えば、image-editorスキルを構築する場合、関連する質問には以下が含まれます:

"image-editorスキルはどのような機能をサポートすべきですか? 編集、回転、他に何かありますか?"
"このスキルがどのように使用されるかの例を教えてください"
"ユーザーが『この画像から赤目を除去して』や『この画像を回転して』といったリクエストをすることを想像できます。このスキルが使用される他の方法を想像できますか?"
"このスキルをトリガーするためにユーザーは何と言いますか?"

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

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

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

具体的な例を効果的なスキルに変換するには、各例を以下のように分析します:

例をゼロから実行する方法を考える
これらのワークフローを繰り返し実行する際に役立つscripts/、references/、assets/を特定する

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

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

例: 「Todoアプリを作って」や「歩数を追跡するダッシュボードを作って」のようなクエリのためのfrontend-webapp-builderスキルを設計する場合、分析は以下を示します:

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

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

BigQueryのクエリには毎回テーブルスキーマと関係を再発見する必要がある
テーブルスキーマを文書化するreferences/schema.mdファイルをスキルに保存すると役立つ

スキルのコンテンツを確立するには、各具体例を分析して、含める再利用可能なリソース（scripts/、references/、assets/）のリストを作成します。

ステップ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

nameとdescriptionを含むYAML frontmatterを書きます:

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

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

Body

スキルとそのバンドルリソースを使用するための指示を書きます。

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

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

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

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

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

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

検証スキルを自動的に検証し、以下を確認:
- YAML frontmatterの形式と必須フィールド
- スキルの命名規則とディレクトリ構造
- 説明の完全性と品質
- ファイルの整理とリソース参照
パッケージ化 検証が成功した場合、スキル名にちなんだ.skillファイル（例: my-skill.skill）を作成し、すべてのファイルを含め、配布用の適切なディレクトリ構造を維持します。.skillファイルは.skill拡張子を持つzipファイルです。

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

ステップ6: 反復

スキルをテストした後、ユーザーは改善を要求する場合があります。これは、スキルがどのように実行されたかの新鮮なコンテキストを持って、スキルを使用した直後に起こることがよくあります。

反復ワークフロー:

実際のタスクでスキルを使用する
苦労や非効率に気付く
SKILL.mdまたはバンドルリソースをどのように更新すべきかを特定する
変更を実装して再度テストする

skill-creator

SKILL.md