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)
│   │   └── 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 が必要と判断したときだけ読み込まれます
• ベストプラクティス: ファイルが大きい場合（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 がプレビュー時に全体の範囲を把握できるよう、先頭に目次を含めてください。

スキル作成のプロセス

スキルの作成には、次の手順が含まれます。

0. タスク履歴からユーザーの意図を把握し、理解を確認する
1. ファイルを使った計画用の TODO リストを作成し、唯一の実行トラッカーとして使用する
2. 具体例を使ってスキルを理解する
3. 再利用可能なスキルの内容（スクリプト、リファレンス、アセット）を計画する
4. スキルを初期化する（init_skill.py を実行する）
5. スキルを編集する（リソースを実装し、SKILL.md を作成する）
6. スキルをパッケージ化する（package_skill.py を実行する）
7. 実際の使用結果に基づいて反復する

明確に該当しない理由がある場合にのみ手順を省略し、それ以外はこの順序で進めてください。

ステップ 0（必須）：タスク履歴からユーザーの意図を把握する

このステップは必須です。完了する前に、スキルを初期化または編集してはいけません。

ユーザーがスキルの作成や更新を依頼する場合、その依頼は通常、最近のタスク履歴に基づいています。まず、次の情報から意図を再構成する必要があります。

• 最近のタスクに関するメッセージと結果（成功／失敗、および修正された点）
• 現在有効なスキルと、それらが対応できたこと、または対応できなかったこと
• 繰り返し示されているユーザーの好みや制約（トーン、対象者、構成、範囲）

先に進む前に、自然な言葉で理解内容をユーザーに説明し、確認を求めてください。

ユーザー向けのコミュニケーション要件（必須）：

• 自然な会話調の中国語で 3～6 文にしてください。
• 定型的な出力形式、二言語の見出し、「理解結果 / Understanding Summary」のようなラベルは使用しないでください。
• ユーザーが本当に再利用したいものに焦点を当ててください。
  • 繰り返し活用できる能力として形にしたい目標
  • 直近のタスクから引き継ぐ価値のある方法や好み
  • 推奨するスキルの粒度とその理由（単発のトピックではなく、能力レベルで）
• 最初の確認メッセージでは、技術的な名称の詳細を並べないでください。必要であれば、方向性を示す簡潔な名称を 1 つだけ挙げてください。
• 最後に確認の質問を 1 つ置き、ユーザーの返答を待ってください。

内部確認リスト（推論用であり、ユーザー向けの固定テンプレートではありません）：

1. ユーザーの目標
2. 背景と対象者
3. タスク履歴から再利用できる成功した方法
4. ユーザーの好みと厳格な制約
5. 推奨するスキルの粒度
6. 提案するスキルの方向性／名称

推奨するトーンの例：

我理解你是想把这次任务里“如何写好一类通知”的经验沉淀成可复用能力，而不是只复用这一次的具体内容。
从刚才的过程看，可复用的关键是：受众定位、语气控制、信息结构和人文关怀表达。
所以更合适的沉淀粒度是“编写通知”这类能力型技能，后续可覆盖放假通知、制度通知等相近场景。
我这样理解对吗？如果对，我们就按这个方向进入生成步骤。

続行する前に、ユーザーから明示的な確認を得る必要があります。

ステップ 1（必須）：Plan-With-Files TODO を作成して維持する

このステップは必須であり、ステップ 0 の確認直後に実行します。

次の場所に TODO トラッカーファイルを作成します。

./output/skill-creation.todo.md

テンプレートを使用します。

references/plan-with-files.todo-template.md

実行ルール：

• すべての実装アクションを、明示的なファイルパスを含む 1 つの TODO 項目に対応させます。
• ステータスを継続的に更新します。
  • [ ] 未着手
  • [-] 進行中
  • [x] 完了
  • [!] ブロック中
• 現在のステップが [x] になるまで、次の主要なステップを実行しないでください。
• TODO ファイルを進捗状況の唯一の情報源とし、実態を正確に反映させてください。

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

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

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

たとえば、画像エディターのスキルを構築する場合、次のような質問が参考になります。

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

ユーザーに負担をかけないよう、1 回のメッセージで質問しすぎないでください。まず最も重要な質問をし、効果を高めるために必要に応じて追加で質問します。

スキルがサポートすべき機能が明確になったら、このステップを完了とし、TODO ファイルに完了を記録します。

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

具体例を効果的なスキルに落とし込むため、各例を次の観点から分析します。

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 ファイルをスキルに保存しておくと便利です

スキルの内容を決めるために、具体例をそれぞれ分析し、含める再利用可能なリソース（スクリプト、リファレンス、アセット）の一覧を作成します。具体的なファイル単位のタスクを TODO ファイルに追加します。

ステップ 4：スキルの初期化

ここで、実際にスキルを作成します。

開発中のスキルがすでに存在し、反復やパッケージ化が必要な場合に限り、このステップを省略してください。その場合は、次のステップに進みます。

新しいスキルを一から作成する場合は、必ず init_skill.py スクリプトを実行してください。このスクリプトを使うと、スキルに必要なものがすべて自動的に含まれる新しいテンプレートスキルディレクトリが生成されるため、スキルの作成をより効率的かつ確実に進められます。

使用方法：

scripts/init_skill.py <skill-name> --path <output-directory>

このスクリプトは、以下を実行します。

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

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

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

新しく生成したスキルまたは既存のスキルを編集するときは、そのスキルが別のClaudeインスタンスで使われることを忘れないでください。Claudeにとって有益で、すぐには分からない情報を盛り込んでください。手順に関する知識、ドメイン固有の詳細、再利用可能なアセットのうち、別のClaudeインスタンスがこれらのタスクをより効果的に実行するのに役立つものを検討してください。

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

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

• 複数ステップのプロセス：順次ワークフローと条件ロジックについては、references/workflows.mdを参照してください
• 特定の出力形式や品質基準：テンプレートと例のパターンについては、references/output-patterns.mdを参照してください
• タスク実行の追跡：plan-with-filesのTODO構成については、references/plan-with-files.todo-template.mdを参照してください

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

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

実装を始めるには、まず上記で特定した再利用可能なリソース、つまり 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フロントマターには、ほかのフィールドを含めないでください。

本文

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

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

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

scripts/package_skill.py <path/to/skill-folder> ./output --todo ./output/skill-creation.todo.md

出力ディレクトリの指定は任意です。

scripts/package_skill.py <path/to/skill-folder> ./output --todo ./output/skill-creation.todo.md

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

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

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

2. TODO ゲートを検証します（--todo が指定されている場合）。パッケージ化の前に、前提となるタスクが完了していることを確認します。

3. 検証に合格した場合、スキルをパッケージ化します。スキル名を付けた .zip ファイル（例：my-skill.zip）を作成し、配布に適したディレクトリ構造を保ったまま、すべてのファイルを含めます。タスクの出力領域ですぐに成果物を見つけられるよう、./output への出力を推奨します。

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

ステップ 7：反復

スキルをテストした後、ユーザーから改善を求められることがあります。多くの場合、スキルの動作を新鮮な視点で把握している、スキルを使った直後に行われます。

反復のワークフロー：

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