スキルクリエイター

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

スキルについて

スキルは、拡張可能な LLM パワードシステムであるエージェントに特化した機能を備えさせるモジュール型の自己完結型パッケージです。各スキルはドメイン固有の知識、最適化されたワークフロー、カスタムビルトツールを提供し、汎用エージェントをドメインスペシャリストに変えます。

静的なモデルトレーニングとは異なり、スキルはプラグアンドプレイコンポーネントとして機能します。大規模言語モデルが本来的に欠落している正確な手続き知識を注入し、複雑なタスクの確実な実行を実現します。このモジュール式アプローチにより、スキルは独立して組み合わせ、更新、または置き換えることができます。コアエージェントを再トレーニングせずに新しいドメインへの適応を加速させます。

スキルが提供するもの

特化したワークフロー - 特定のドメイン向けマルチステップ手続き
ツール統合 - 特定のファイル形式または API を操作するための指示
ドメイン専門知識 - 企業固有の知識、スキーマ、ビジネスロジック
バンドルされたリソース - 複雑で反復的なタスク向けスクリプト、参考資料、アセット

コア原則

簡潔さが重要

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

デフォルトの想定：エージェントは既に非常に賢い。 エージェントが既に持っていない情報のみを追加してください。各情報に疑問を持ってください：「エージェントは本当にこの説明が必要か？」「このパラグラフはトークンコストに見合う価値があるか？」

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

適切な自由度を設定する

タスクの脆弱性と可変性のレベルに特異性を合わせます：

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

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

低自由度（特定のスクリプト、少数のパラメータ）: オペレーションが脆弱でエラーが発生しやすい場合、一貫性が重要な場合、または特定のシーケンスに従う必要がある場合に使用します。

パスを探索することと考えてください：崖がある狭い橋には特定のガードレール（低自由度）が必要です。一方、開けた野原は多くのルートが可能です（高自由度）。

スキルの構造

すべてのスキルは必須の SKILL.md ファイルとオプションのバンドルされたリソースで構成されます：

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

SKILL.md（必須）

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

Frontmatter（YAML）: name フィールドと description フィールドを含みます。これらは Claude がスキルをいつ使用するかを判断するために読み込む唯一のフィールドです。したがって、スキルが何であり、いつ使用すべきかを明確かつ包括的に説明することが非常に重要です。
本文（Markdown）: スキル使用のための指示とガイダンス。スキルがトリガーされた後でのみ読み込まれます（読み込まれる場合のみ）。

バンドルされたリソース（オプション）

スクリプト（`scripts/`）

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

含める場合: 同じコードが繰り返し書き直される場合または確定的な信頼性が必要な場合
例: PDF 回転タスク向けの scripts/rotate_pdf.py
メリット: トークン効率的、確定的、コンテキストに読み込まずに実行される可能性あり
注意: スクリプトはパッチ適用または環境固有の調整のためにエージェントによって読み込まれる必要がある場合があります

参考資料（`references/`）

エージェントのプロセスと思考をガイドするため、必要に応じてコンテキストに読み込まれる予定のドキュメントと参考資料。

含める場合: エージェントが作業中に参照すべきドキュメント用
例: 財務スキーマ向けの references/finance.md、企業 NDA テンプレート向けの references/mnda.md、企業ポリシー向けの references/policies.md、API 仕様向けの references/api_docs.md
ユースケース: データベーススキーマ、API ドキュメント、ドメイン知識、企業ポリシー、詳細なワークフローガイド
メリット: SKILL.md を見やすく保つ、エージェントが必要と判断した場合にのみ読み込まれる
ベストプラクティス: ファイルが大きい場合（10,000 語超）、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
ユースケース: テンプレート、画像、アイコン、ボイラープレートコード、フォント、コピーまたは変更される見本ドキュメント
メリット: 出力リソースをドキュメントから分離、Claude がコンテキストに読み込まずにファイルを使用可能

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

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

README.md
INSTALLATION_GUIDE.md
QUICK_REFERENCE.md
CHANGELOG.md
その他

スキルには、AI エージェントが手元のジョブを実行するために必要な情報のみを含めるべきです。それを作成するプロセスに関する補助的なコンテキスト、セットアップとテストの手続き、ユーザー向けドキュメント、その他は含めるべきではありません。追加ドキュメントファイルを作成すると、混乱と複雑さが増すだけです。

プログレッシブディスクロージャー設計原則

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

メタデータ（name + description） - 常にコンテキストに存在（約 100 語）
SKILL.md 本文 - スキルがトリガーされた場合（5,000 語未満）
バンドルされたリソース - エージェントが必要に応じて（無制限。スクリプトはコンテキストウィンドウに読み込まずに実行できるため）

プログレッシブディスクロージャーパターン

SKILL.md 本文を本質的で 500 行未満に保ち、コンテキストの膨張を最小化します。この上限に近づく場合は、コンテンツを別ファイルに分割します。コンテンツを他のファイルに分割する場合、SKILL.md からそれらを参照し、いつ読むかを明確に説明することが重要です。スキル読者がそれらの存在を認識し、いつ使用するかを知るようにするためです。

主要原則： スキルが複数のバリエーション、フレームワーク、またはオプションをサポートする場合、SKILL.md にはコアワークフローと選択ガイダンスのみを保持します。バリエーション固有の詳細（パターン、例、コンフィグレーション）を別の参考資料ファイルに移動します。

パターン 1: 高レベルガイドと参考資料

# PDF 処理

## クイックスタート

pdfplumber でテキストを抽出：
[コード例]

## 高度な機能

- **フォーム記入**: 完全なガイドは [references/FORMS.md](FORMS.md) を参照
- **API リファレンス**: すべてのメソッドは [references/REFERENCE.md](references/REFERENCE.md) を参照
- **例**: 一般的なパターンは [references/EXAMPLES.md](references/EXAMPLES.md) を参照

エージェントは FORMS.md、REFERENCE.md、または EXAMPLES.md を必要な場合にのみ読み込みます。

パターン 2: ドメイン固有の整理

複数のドメインをサポートするスキル向けに、無関係なコンテキストが読み込まれないようドメイン別にコンテンツを整理します：

bigquery-skill/
├── SKILL.md (概要とナビゲーション)
└── reference/
    ├── finance.md (収益、請求指標)
    ├── sales.md (機会、パイプライン)
    ├── product.md (API 使用、機能)
    └── marketing.md (キャンペーン、属性)

ユーザーが売上指標について質問する場合、エージェントは sales.md のみを読みます。

同様に、複数のフレームワークまたはバリエーションをサポートするスキル向けに、バリエーション別に整理します：

cloud-deploy/
├── SKILL.md (ワークフロー + プロバイダー選択)
└── references/
    ├── aws.md (AWS デプロイメントパターン)
    ├── gcp.md (GCP デプロイメントパターン)
    └── azure.md (Azure デプロイメントパターン)

ユーザーが AWS を選択する場合、エージェントは aws.md のみを読みます。

パターン 3: 条件付き詳細

基本的なコンテンツを表示し、高度なコンテンツへリンク：

# DOCX 処理

## ドキュメント作成

新しいドキュメントに docx-js を使用します。[references/DOCX-JS.md](references/DOCX-JS.md) を参照。

## ドキュメント編集

簡単な編集の場合は、XML を直接変更します。

**変更追跡**: [references/REDLINING.md](references/REDLINING.md) を参照
**OOXML 詳細**: [references/OOXML.md](references/OOXML.md) を参照

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

重要なガイドライン：

深くネストされた参考資料を回避 - 参考資料を SKILL.md から 1 レベル深く保ちます。すべての参考資料ファイルは SKILL.md から直接リンクするべきです。
長い参考資料ファイルを構造化 - 100 行超のファイルについては、エージェントがプレビュー時に全体的な範囲を確認できるように、上部に目次を含めます。

スキル作成プロセス

スキル作成にはこれらのステップが含まれます：

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

それらが適用されない明確な理由がない限り、この順序で各ステップに従ってください。

ステップ 0: `uv` のインストール確認

必須アクション:

まず、次を実行して uv がシステムで利用可能かどうかを確認します：
```
uv --version
```
このコマンドが失敗する場合（例：「command not found」）：

ユーザーにこのコマンドを提供します：
```
curl -LsSf https://astral.sh/uv/install.sh | sh
```
- 重大な制限:
  - ⚠️ このコマンドを自分で実行しないでください - システムファイルを変更します
  - ⚠️ ユーザーに手動でレビューして実行させる必要があります
- ユーザーへの必須警告:
  - 「このコマンドはインターネットからスクリプトをダウンロードして実行します。これは本来的なセキュリティリスクを伴います。」
  - 「信頼できるソースからのコマンドのみを実行してください。スクリプトの安全性を以下で確認してください：https://docs.astral.sh/uv/getting-started/installation/」
  - 「環境で利用可能な場合は、代替インストール方法の使用を検討してください。」
確認: ユーザーがインストール後、以下で成功を確認します：
```
uv --version
```

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

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

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

たとえば、画像エディタスキルを構築する場合、関連する質問には以下が含まれます：

「画像エディタスキルはどのような機能をサポートすべきですか？編集、回転、その他？」
「このスキルの使用例を提供できますか？」
「ユーザーが『この画像から赤目を除去してください』や『この画像を回転してください』のような要求をすることを想像できます。このスキルが使用されると思われる他の方法はありますか？」
「ユーザーがこのスキルをトリガーすべき場合、何を言いますか？」

ユーザーを圧倒しないため、単一メッセージで多くの質問をしないようにしてください。最も重要な質問から始め、より良い効果のために必要に応じて後続質問を行ってください。

スキルがサポートすべき機能の明確な理解がある場合、このステップを終了します。

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

具体的な例を効果的なスキルに変えるため、各例を以下により分析します：

最初から例を実行する方法を検討する
これらのワークフローを繰り返し実行する場合、どのスクリプト、参考資料、アセットが役立つかを特定する

例：「PDF をこの PDF を回転させるのを手助けしてください」のようなクエリを処理する pdf-editor スキルを構築する場合、分析結果：

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

例：「Todo アプリを構築してください」または「手順を追跡するダッシュボードを構築してください」のようなクエリ向けに frontend-webapp-builder スキルを設計する場合、分析結果：

フロントエンドウェブアプリの記述には、毎回同じボイラープレート HTML/React が必要です
ボイラープレート HTML/React プロジェクトファイルを含む assets/hello-world/ テンプレートをスキルに保存するのが役立つでしょう

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

BigQuery をクエリするには、毎回テーブルスキーマと関係を再発見する必要があります
テーブルスキーマをドキュメント化する references/schema.md ファイルをスキルに保存するのが役立つでしょう

スキルのコンテンツを確立するため、各具体的な例を分析して、含める再利用可能なリソースのリスト（スクリプト、参考資料、アセット）を作成します。

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

この時点で、スキルを実際に作成する時間です。

スキルが既に存在し、反復またはパッケージ化が必要な場合のみこのステップをスキップします。この場合は、次のステップに進みます。

最初からスキルを新規作成する場合、常に scripts/init_skill.py スクリプトを実行してください。このスクリプトは、スキルが必要とするすべてを自動的に含む新しいテンプレートスキルディレクトリを生成し、スキル作成プロセスを非常に効率的で信頼性の高いものにします。

使用方法：

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

スクリプトは：

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

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

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

（新規生成または既存の）スキルを編集する場合、スキルが別のエージェントインスタンスで使用するために作成されていることを思い出してください。別のエージェントインスタンスに有利で明白でない情報を含めます。どの手続き知識、ドメイン固有の詳細、または再利用可能なアセットが別のエージェントインスタンスがこれらのタスクをより効果的に実行するのを支援するかを検討します。

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

スキルのニーズに基づいてこれらの参考ガイドを参照：

マルチステッププロセス: 順序ワークフローと条件ロジックについては 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: これはスキルの主要なトリガーメカニズムであり、エージェントがスキルをいつ使用すべきかを理解するのに役立ちます。
- スキルが何をするかと、いつ使用するかの特定のトリガー/コンテキストの両方を含めます。
- すべての「いつ使用するか」情報をここに含めてください - 本文には含めません。本文はトリガー後にのみ読み込まれるため、本文の「このスキルを使用する場合」セクションはエージェントに役立ちません。
- docx スキル向け説明の例：「専門ドキュメント（.docx ファイル）の操作が必要な場合の包括的なドキュメント作成、編集、分析。変更追跡、コメント、フォーマット保持、テキスト抽出をサポート。エージェントが以下の場合に使用：(1) 新しいドキュメントを作成、(2) コンテンツを変更または編集、(3) 変更追跡を使用、(4) コメントを追加、またはその他のドキュメントタスク」

YAML frontmatter に他のフィールドを含めません。

本文

スキルと付属リソースの使用方法に関する指示。

ステップ 5: スキルをパッケージ化する

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

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

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

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

パッケージ化スクリプトは：

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

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

ステップ 6: 反復する

スキルをテストした後、ユー

ライセンス: Apache-2.0(寛容ライセンスのため全文を引用しています) · 原本リポジトリ

SKILL.md 本文