create-skill

スキル作成

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

スキルについて

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

スキルが提供するもの

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

基本原則

簡潔さが重要

コンテキストウィンドウは共有の資源です。スキルは、システムプロンプト、会話履歴、ほかのスキルのメタデータ、実際のユーザーリクエストなど、必要なものすべてとコンテキストウィンドウを共有します。

まず、あなたにはすでに十分な能力があると考えてください。 まだ備えていないコンテキストだけを追加します。情報を一つずつ検討し、「この説明は本当に必要か？」「この段落はトークンを使う価値があるか？」と問いかけてください。

冗長な説明よりも、簡潔な例を優先します。

適切な自由度を設定する

タスクの壊れやすさと変動性に応じて、具体性のレベルを調整します。

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

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

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

道を進む自分を想像してください。崖に挟まれた細い橋では具体的なガードレールが必要ですが、広い野原ならさまざまな道を選べます。

スキルの構成

各スキルには、必須の 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 フィールドが含まれます。スキルをいつ使用するかの判断には、これらのフィールドのみを参照するため、スキルの内容と使用すべき場面を明確かつ包括的に記述することが非常に重要です。
• 本文（Markdown）：スキルを使用するための指示とガイダンスが含まれます。スキルが起動された後にのみ読み込まれます（起動される場合）。

バンドルリソース（任意）

スクリプト（scripts/）

確実で決定的な処理が必要なタスクや、繰り返し書き直されるタスクに使う実行可能なコードです。

• 含める場合：同じコードを何度も書き直している場合や、確実で決定的な処理が必要な場合
• 例：PDF の回転タスク向けの scripts/rotate_pdf.sh
• 利点：トークン効率が高く、処理が決定的で、コンテキストに読み込まずに実行できます
• 注記：パッチの適用や環境固有の調整を行うために、スクリプトを読む必要がある場合もあります

参照資料 (references/)

プロセスや思考に情報を与えるために、必要に応じてコンテキストへ読み込まれることを意図したドキュメントおよび参照資料です。

• 含めるべき場合: 作業中に参照すべきドキュメントがある場合
• 例: 財務スキーマ用の references/finance.md、会社の NDA テンプレート用の references/mnda.md、社内ポリシー用の references/policies.md、API 仕様用の references/api_docs.md
• ユースケース: データベーススキーマ、API ドキュメント、ドメイン知識、社内ポリシー、詳細なワークフローガイド
• メリット: SKILL.md を簡潔に保ち、必要と判断したときにのみ読み込まれます
• ベストプラクティス: ファイルが大きい場合 (>10k 語)、SKILL.md に grep 検索パターンを含めます
• 重複を避ける: 情報は SKILL.md または参照資料ファイルのどちらか一方に置くべきで、両方に置いてはいけません。スキルにとって真に中核でない限り、詳細情報には参照資料ファイルを優先してください。これにより SKILL.md を簡潔に保ちつつ、コンテキストウィンドウを圧迫せずに情報を発見できるようにします。SKILL.md には必須の手順指示とワークフローガイダンスのみを残し、詳細な参照資料、スキーマ、例は参照資料ファイルに移してください。

アセット (assets/)

コンテキストに読み込まれることを意図しておらず、むしろ生成する出力内で使用されるファイルです。

• 含めるべき場合: スキルが最終出力で使用されるファイルを必要とする場合
• 例: ブランドアセット用の assets/logo.png、PowerPoint テンプレート用の assets/slides.pptx、HTML/React ボイラープレート用の assets/frontend-template/、タイポグラフィ用の assets/font.ttf
• ユースケース: テンプレート、画像、アイコン、ボイラープレートコード、フォント、コピーまたは変更されるサンプルドキュメント
• メリット: 出力リソースをドキュメントから分離し、コンテキストに読み込むことなくファイルを使用できるようにします

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

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

• 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

必要な場合にのみ 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)

ユーザーが営業指標について尋ねた場合は、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 を選んだ場合は、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)

ユーザーがこれらの機能を必要とする場合にのみ、REDLINING.md または OOXML.md を読みます。

重要なガイドライン：

• 参照を深くネストしないでください - SKILL.md からの参照は 1 階層にとどめてください。すべてのリファレンスファイルは、SKILL.md から直接リンクしてください。
• 長いリファレンスファイルを構成してください - 100 行を超えるファイルには、プレビュー時に全体の範囲を把握できるよう、冒頭に目次を含めてください。

スキル作成のプロセス

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

1. 具体例を使ってスキルを理解する
2. 再利用可能なスキルの内容（スクリプト、リファレンス、アセット）を計画する
3. スキルを初期化する
4. スキルを編集する（リソースを実装し、SKILL.md を作成する）
5. 実際の使用状況に基づいて反復する

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

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

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

効果的なスキルを作成するには、そのスキルがどのように使われるかを具体例に基づいて明確に理解する必要があります。この理解は、ユーザーから直接得た例、または生成した例をユーザーからのフィードバックで検証することで得られます。

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

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

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

このスキルが対応すべき機能が明確になった時点で、このステップを終了します。

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

具体的な例を効果的なスキルにするには、各例を次の観点から分析します。

1. 例のタスクを一から実行する方法を検討する
2. これらのワークフローを繰り返し実行する際に、どのようなスクリプト、リファレンス、アセットが役立つかを特定する

例：「この PDF を回転するのを手伝って」のような問い合わせに対応する edit-pdf スキルを作成する場合、分析によって次のことがわかります。

1. PDF を回転するには、毎回同じコードを書き直す必要がある
2. scripts/rotate_pdf.sh スクリプトをスキルに保存しておくと役立つ

例：「ToDo アプリを作って」や「歩数を記録するダッシュボードを作って」のような問い合わせに対応する build-frontend-webapp スキルを設計する場合、分析によって次のことがわかります。

1. フロントエンドのウェブアプリを作成するには、毎回同じ HTML／React のボイラープレートを書く必要がある
2. ボイラープレートの HTML／React プロジェクトファイルを含む assets/hello-world/ テンプレートをスキルに保存しておくと役立つ

例：「今日ログインしたユーザー数は？」のような問い合わせに対応する query-bigquery スキルを作成する場合、分析によって次のことがわかります。

1. BigQuery にクエリを実行するには、毎回テーブルのスキーマと関係を再確認する必要がある
2. テーブルのスキーマを記載した references/schema.md ファイルをスキルに保存しておくと役立つ

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

ステップ 3：スキルを初期化する

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

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

スキルの命名規則

スキルが実行するアクションを明確に伝えるため、必ず動詞を使った名前にしてください。

• ✅ 良い例：execute-plan、create-report、analyze-logs、deploy-app
• ❌ 悪い例：plan-executor、report-creator、log-analyzer、app-deployer

動詞を先頭に置くと、スキルの機能がすぐにわかります。また、スキルの指示全体で使われている命令形／不定詞形にも沿っています。

スキルの配置場所

デフォルト：ユーザーがグローバルスキルを明示的に指定しない限り、プロジェクトローカルのスキルを作成します。

新しいスキルを一から作成する場合は、プロジェクトローカルのスキルディレクトリに作成します。

• プロジェクトローカル（デフォルト）：{{local_skills_path}}/<skill-name>/ - スキルはプロジェクト固有で、ほかのプロジェクトには影響しません。ほとんどのスキルで安全なデフォルトです。
• グローバル（明示的に指定された場合のみ）：{{global_skills_path}}/<skill-name>/ - スキルはすべてのプロジェクトで利用できます。ユーザーがグローバルスキルを明示的に求めた場合、またはスキルがすべてのプロジェクトで本当に再利用可能な場合に限り、この場所を使用してください。

構成には、次のものを含めます。

• YAML フロントマター（名前、説明）と Markdown 本文を含む SKILL.md
• 実行可能なコード（例：process.sh、validate.sh）を格納する scripts/ ディレクトリ
• 必要に応じて読み込むドキュメントを格納する references/ ディレクトリ
• 出力に使用するファイルを格納する assets/ ディレクトリ

初期化の例（デフォルトのプロジェクトローカル）：

mkdir -p {{local_skills_path}}/edit-pdf/{scripts,references,assets}
cat > {{local_skills_path}}/edit-pdf/SKILL.md << 'EOF'
---
name: edit-pdf
description: TODO - Describe what this skill does and when to use it
---

# Edit PDF

TODO - Add skill instructions here
EOF

cat > {{local_skills_path}}/edit-pdf/scripts/rotate.sh << 'EOF'
#!/bin/bash
# Rotate PDF using pdftk
pdftk "$1" cat 1-endright output "$2"
EOF

chmod +x {{local_skills_path}}/edit-pdf/scripts/rotate.sh

ユーザーがグローバルスキルを明示的に指定した場合は、代わりに次を使用します。

mkdir -p {{global_skills_path}}/edit-pdf/{scripts,references,assets}
cat > {{global_skills_path}}/edit-pdf/SKILL.md << 'EOF'
---
name: edit-pdf
description: TODO - Describe what this skill does and when to use it
---

# Edit PDF

TODO - Add skill instructions here
EOF

cat > {{global_skills_path}}/edit-pdf/scripts/rotate.sh << 'EOF'
#!/bin/bash
# Rotate PDF using pdftk
pdftk "$1" cat 1-endright output "$2"
EOF

chmod +x {{global_skills_path}}/edit-pdf/scripts/rotate.sh

初期化後、必要に応じて生成されたファイルをカスタマイズします。

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

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

実績のある設計パターンを学ぶ

スキルのニーズに応じて、以下の参考ガイドを確認してください。

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

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

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

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

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

スキルに不要なサンプルファイルやディレクトリは削除してください。

SKILL.md を更新する

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

フロントマター

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

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

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

本文

スキルとそのバンドルされたリソースを使用するための手順を記述します。

新しいスキルを読み込む

スキルが完成したら、新しく作成したスキルを読み込むために、新しいセッションを開始することをユーザーに提案してください。スキルは各セッションの開始時に読み込まれるため、新しいスキルは現在のセッションでは利用できません。新しいセッションを開始することで、スキルが適切に登録され、使用可能になります。

ステップ 5: 反復する

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

反復ワークフロー:

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