skill-creator

Skill Creator

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

スキルについて

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

スキルが提供するもの

1. 専門的なワークフロー - 特定の分野における複数段階の手順
2. ツール連携 - 特定のファイル形式や API の操作手順
3. 分野の専門知識 - 企業固有の知識、スキーマ、ビジネスロジック
4. 同梱リソース - 複雑で反復的なタスク向けのスクリプト、リファレンス、アセット

基本原則

簡潔さが重要

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

Claude はすでに非常に賢いものと考えるのが基本です。 Claude がすでに知っていることは追加せず、Claude にないコンテキストだけを加えてください。情報を一つずつ吟味しましょう。「Claude に本当にこの説明が必要だろうか？」「この段落は、消費するトークンに見合う価値があるだろうか？」と考えてください。

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

適切な自由度を設定する

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

自由度が高い（テキストベースの指示）：複数の方法が有効な場合、判断が状況に左右される場合、またはヒューリスティクスに基づいて進める場合に使用します。

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

自由度が低い（特定のスクリプト、少数のパラメーター）：操作が壊れやすくエラーが発生しやすい場合、一貫性が重要な場合、または決まった順序に従う必要がある場合に使用します。

Claude が道を探す様子を想像してください。崖に挟まれた細い橋には具体的なガードレールが必要ですが（自由度は低く）、広々とした野原なら多くの進み方があります（自由度は高い）。

スキルの構成

各スキルは、必須の SKILL.md ファイルと、任意の同梱リソースで構成されます。

skill-name/
├── SKILL.md (required)
│   ├── YAML frontmatter metadata (required)
│   │   ├── name: (required)
│   │   ├── description: (required)
│   │   └── compatibility: (optional, rarely needed)
│   └── 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 フィールドと、license、metadata、compatibility などの任意フィールドを含みます。スキルを使用するタイミングを Claude が判断する際に読み込むのは name と description のみです。そのため、スキルの内容と使用すべき状況を、明確かつ包括的に記述してください。compatibility フィールドには、環境要件（対象製品、システムパッケージなど）を記載しますが、ほとんどのスキルでは必要ありません。
• 本文（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 が必要と判断したときにのみ読み込まれます
• ベストプラクティス: ファイルが大きい場合（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
• ユースケース: テンプレート、画像、アイコン、ボイラープレートコード、フォント、コピーまたは変更されるサンプルドキュメント
• メリット: 出力リソースをドキュメントから分離し、Claude がファイルをコンテキストに読み込まずに使用できるようにします

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

スキルには、その機能を直接サポートする必須ファイルのみを含めるべきです。以下のような、無関係なドキュメントや補助ファイルを作成しないでください。

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

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

段階的開示の設計原則

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

1. メタデータ（名前 + 説明） - 常にコンテキスト内（約 100 語）
2. SKILL.md 本文 - スキルがトリガーされたとき（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 のみを読み込みます。

パターン 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-editor スキルを作成し、「この PDF の回転を手伝ってください」のようなリクエストに対応する場合、分析から次のことがわかります。

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 スクリプトを実行してください。このスクリプトは、スキルに必要なものがすべて含まれた新しいテンプレートスキルディレクトリを手軽に生成するため、スキル作成のプロセスをより効率的かつ確実に進められます。

使用方法：

python3 plugins/dev-tools/skills/skill-creator/scripts/init_skill.py <skill-name> --path plugins/<category>/skills/

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

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

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

ステップ 4：スキルを編集する

新しく生成したスキルまたは既存のスキルを編集する際は、別の Claude インスタンスが使用するためのスキルを作成していることを念頭に置いてください。Claude にとって有益で、自明ではない情報を含めます。別の Claude インスタンスがタスクをより効果的に実行するうえで役立つ、手順に関する知識、ドメイン固有の詳細、再利用可能なアセットを検討してください。

スキルは自己完結している必要があります

スキルをインストールする他のユーザーは、あなたの ~/.claude/rules/、CLAUDE.md、MCP サーバー、Vault を利用できません。スキルに必要なものは、すべてスキル自体に含める必要があります。

依存しないもの	代わりに...
あなたの ~/.claude/rules/*.md	ガイダンスを SKILL.md または references/ に記載する
あなたのプロジェクトまたはグローバルの CLAUDE.md	関連するコンテキストをスキルに直接含める
特定の MCP サーバー（Brain、Vault など）	MCP の使用を任意にするか、必要なものを記載する
あなたの settings.local.json の権限設定	スキルに必要な権限を記載し、ユーザーが追加できるようにする
環境固有のパスやツール	検出ロジックを使用するか、前提条件を記載する

テスト：Claude Code を新規インストールしたユーザーが、このスキルを使えるでしょうか？ 個人設定がないと動作しない場合、そのスキルは自己完結していません。

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

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

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

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

Bash コマンドの連結ではなく、スクリプトを優先する

スキルの手順で、複数のソースからのデータ収集、ファイルのスキャン、一括操作を行う場合は、個々の bash コマンドを列挙するのではなく、Claude にスクリプトを作成して実行するよう指示してください。bash コマンドを実行するたびに、ユーザーの個別の承認が必要です。10 個のコマンドを実行する手順では、承認プロンプトが 10 回表示されます。

代わりに……	次のように指示します……
「git log を実行し、次に grep、その後 jq を実行する……」	「git の履歴を収集し、パターンを抽出して、要約を出力する Python スクリプトを作成してください。/tmp から実行してください。」
「各ファイルに対して cat を実行し、確認する……」	「条件に一致するすべてのファイルをスキャンし、構造化されたレポートを返すスクリプトを作成してください。」
「この 5 つの curl コマンドを実行する……」	「API を呼び出して結果を集約するスクリプトを作成してください。」

目安：1 つの論理的な操作に 3 つ以上の bash コマンドが必要な場合は、スクリプトにしてください。Write を 1 回、Bash の実行を 1 回なら、複数回の承認ではなく、承認は 2 回で済みます。

保存先：スクリプトは /tmp ではなく、プロジェクト内の .claude/scripts/ に保存してください。プロジェクトのスクリプトはプロジェクトの進化の一部となり、今後のセッションでも利用できます。使い捨ての一時的な操作には、/tmp のみを使用してください。

再利用可能なスキルの内容から始める

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

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

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

SKILL.md を更新する

記述ガイドライン： 常に命令形または不定詞形を使用してください。

フロントマター

name と description を含む YAML フロントマターを記述します。

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

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

本文

スキルと同梱リソースの使用手順を記述します。

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

スキルの開発が完了したら、配布用にパッケージ化できます。

claude.ai（Web インターフェース）向け：

python3 plugins/dev-tools/skills/skill-creator/scripts/package_skill.py <path/to/skill-folder>

これにより、claude.ai にアップロードする .skill ファイル（zip 形式）が作成されます。

Claude Code（CLI）向け：

スキルはディレクトリとして動作するため、パッケージ化は不要です。直接インストールします。

# Install from this repo
/plugin install ./skills/<skill-name>

# Or add a repo as a marketplace
/plugin marketplace add owner/repo-name
/plugin install <bundle-name>

パッケージ化スクリプトでは、次の処理が行われます。

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

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

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

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

一括パッケージ化：

# Package all Claude AI-compatible skills
python3 plugins/dev-tools/skills/skill-creator/scripts/package_all.py --claude-ai-only

# Package all skills
python3 plugins/dev-tools/skills/skill-creator/scripts/package_all.py

# List skills and compatibility
python3 plugins/dev-tools/skills/skill-creator/scripts/package_all.py --list

2 つの環境に対応するスキル

スキルは Claude AI（Web）と Claude Code（CLI）の両方で動作します。両方の環境向けに構築する場合は、次の違いに注意してください。

機能	Claude AI	Claude Code
ファイル出力	/mnt/user-data/outputs/	ローカルファイルシステム
ユーザーとの対話	ask_user_input ツール	ターミナルプロンプト
Web 検索	組み込みの web_search ツール	WebSearch ツール
シェルコマンド	利用不可	Bash ツール
サブエージェント	利用不可	Task ツール（Explore、Plan など）
MCP ツール	接続時は同じ名前	接続時は同じ名前
アーティファクト	HTML、React をインラインでレンダリング	利用不可

互換性の指定： ローカルファイルシステム、bash、または CLI ツールを必要とするスキルでは、フロントマターに compatibility: claude-code-only を追加してください。このフィールドがないスキルは、両方の環境で動作すると見なされます。

---
name: my-cli-skill
description: "..."
compatibility: claude-code-only
---

2 つの環境に対応するスキルの作成： 環境に応じて動作を変えるスキルを作成する場合は、「環境に関する注意事項」セクションを追加してください。

## Environment Notes

- **Claude AI:** Save output files to `/mnt/user-data/outputs/`. Use `present_files` to share.
- **Claude Code:** Save output files to the project directory or path specified by the user.

説明文のトリガーフレーズ： description フィールドは、主なトリガーメカニズムです。Claude はこれを使って、スキルを有効にするかどうかを判断します。スキルの機能だけでなく、ユーザーが実際に使いそうな具体的なフレーズも含めてください。例：「ユーザーが『ファビコンを作って』、『アイコンを生成して』、『ファビコンパッケージを作成して』と言ったとき、またはファビコンが不足していると述べたときに使用します。」

ステップ 6：反復

スキルをテストした後、ユーザーから改善を求められることがあります。多くの場合、スキルの動作をまだよく覚えている、使用直後のタイミングで依頼されます。

反復ワークフロー：

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