agent-skill-creator

スキル作成

Claude.ai、Claude Code、API で使える、効果的で移植性の高いスキルを作成します。スキルとは、再利用可能なワークフローを一度だけ記述し、一貫して適用するためのフォルダー化された指示セットです。

スキルの構造

skill-name/
├── SKILL.md              # Required: YAML frontmatter + markdown instructions
├── scripts/              # Optional: executable code for deterministic tasks
├── references/           # Optional: docs loaded into context as needed
└── assets/               # Optional: files used in output (templates, images, fonts)

SKILL.md

2 つの部分で構成されます。

1. フロントマター（YAML）— name と description のフィールド。常にコンテキストに含まれます。スキルがいつ起動するかを決定します。
2. 本文（Markdown）— 指示、ワークフロー、同梱リソースへの参照。スキルの起動後にのみ読み込まれます。

同梱リソース

ディレクトリ	用途	コンテキストに読み込まれるか
scripts/	決定的な処理を行う実行可能コード（Python/Bash）	Claude が読み取る場合のみ
references/	Claude が作業中に参照するドキュメント	必要に応じて
assets/	出力に使用するファイル（テンプレート、画像、フォント）	いいえ — 出力で直接使用

README.md、CHANGELOG.md、その他の補足ドキュメントファイルは含めないでください。

基本原則

コンテキストの予算

コンテキストウィンドウは共有されています。Claude がすでに把握している内容は含めないでください。冗長な説明より、簡潔な例を優先してください。すべての段落は、そのトークンコストに見合う必要があります。不要な段落は削除してください。

上限：SKILL.md の本文は 5,000 語未満にしてください。詳細な内容は references/ に移してください。

自由度

タスクの壊れやすさに合わせて具体性を調整します。

• 高い自由度（テキストによるガイダンス）— 複数の有効な方法があり、状況に応じて異なります
• 中程度の自由度（疑似コード／パラメーター化されたスクリプト）— 推奨パターンがあり、ある程度の変化は許容されます
• 低い自由度（厳密なスクリプト）— 壊れやすい操作で、一貫性が重要です

段階的な情報開示

3 層で読み込むことで、コンテキストの使用量を最小限に抑えます。

1. フロントマター（100 語未満）— 常にコンテキストに含まれます
2. SKILL.md の本文（5,000 語未満）— スキルの起動時に読み込まれます
3. 同梱リソース（無制限）— 必要に応じて読み込まれます

SKILL.md は簡潔に保ってください。300 行を超える場合は、参照ファイルに分割してください。分割したファイルについては、いつ読むべきかを明記した説明とともに、必ず SKILL.md から参照してください。

組み合わせやすさと移植性

• スキルは、互いに指示が競合することなく共存できる必要があります
• スキルは Claude.ai、Claude Code、API で動作する必要があります
• 環境固有のツールに強く依存しないでください

ワークフロー

1. 理解する

作成に着手する前に、具体的なユースケースを集めます。

開始条件：スキルの作成または改善を求めるユーザーの依頼。

実施内容：

• スキルがどのように使われるか、具体例を 2～3 件特定します
• 各例について、起動条件、実行する手順、期待される結果を確認します
• 要点を絞って質問し、一度に多くの質問をしてユーザーに負担をかけないようにします

完了条件：スキルの対象範囲、起動条件、期待される出力が明確になっていること。

2. 計画する

スキルに必要な再利用可能なリソースを決定します。

開始条件：ステップ 1 で具体化したユースケース。

実施内容：

• 各ユースケースについて、毎回書き直すものがないか確認します。それをスキルに含めます。
• リソースを分類します。
  • 繰り返し書き直すコード → scripts/
  • 繰り返し参照する知識 → references/
  • 出力に使用するテンプレート／アセット → assets/
• SKILL.md の構成を決めます。よく使われるパターンについては references/workflows.md を参照してください。

完了条件：作成するリソースの一覧と SKILL.md の概要ができていること。

3. 構築

スキルフォルダーを作成し、その内容を記述します。

開始条件：ステップ 2 のリソース一覧と SKILL.md の概要。

アクション：

1. 上記の構成に従ってスキルフォルダーを作成します。環境で scripts/init_skill.py が利用できる場合は、ひな形の作成に活用します。

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

   利用できない場合は、フォルダーと SKILL.md を手動で作成します。

2. まず同梱リソースを作成します — スクリプト、リファレンス、アセットを用意します。スクリプトを実行してテストします。不要なひな形ファイルは削除します。

3. SKILL.md を作成します：

   • フロントマター：説明の定型については references/description-authoring.md に従います
   • 本文：命令形または不定詞形を使います。ワークフローのステップまたはタスクのカテゴリごとに構成します。
   • 本文は簡潔に保ち、詳細はリファレンスを参照するようにします
   • スキルがすべての構造要件を満たしていることを確認するため、references/validation-checklist.md に照らして検証します

4. 未使用のひな形を削除します — サンプルファイルと空のディレクトリを削除します。

完了条件：すべてのリソースと SKILL.md を含む、完成したスキルフォルダー。

4. テスト

トリガーと出力品質を検証します。

開始条件：ステップ 3 で完成したスキル。

アクション：

• トリガーテスト（肯定および否定のプロンプト）を実行します
• 実際のタスクで機能テストを実行します
• ベースライン（スキルなし）と結果を比較します

詳細なテスト方法と成功基準については、references/testing-iteration.md を参照してください。

完了条件：関連するプロンプト 10 件中 9 件でスキルが起動し、一貫した出力が得られること。

5. 反復

実際の使用に基づいて改善します。

開始条件：テスト結果またはユーザーからのフィードバック。

アクション：

• 問題を診断します：トリガー不足、過剰なトリガー、または実行失敗
• references/testing-iteration.md に従って、対象を絞った修正を適用します
• 影響を受ける箇所を再テストします

完了条件：実際の利用シーンで成功基準を満たすこと。

パッケージ化

完成したスキルを .skill ファイル（拡張子が .skill の zip ファイル）としてパッケージ化します。scripts/package_skill.py が利用できる場合は、自動で検証およびパッケージ化されるため、これを使用します。

scripts/package_skill.py <path/to/skill-folder> [output-directory]

利用できない場合は、アーカイブのルートに SKILL.md が配置されるようにして、スキルフォルダーを手動で zip 圧縮します。

リファレンスガイド

スキルのニーズに応じて、以下を参照してください。

• 説明とトリガー：references/description-authoring.md — 定型、トリガーフレーズ、否定的トリガー、厳格な制約
• ワークフローパターン：references/workflows.md — 順次処理、複数サービス、反復処理、コンテキスト対応、ドメイン知識
• 出力パターン：references/output-patterns.md — テンプレートと、例に基づく出力ガイダンス
• テストと反復：references/testing-iteration.md — トリガーテスト、機能テスト、パフォーマンス指標、診断
• 検証チェックリスト：references/validation-checklist.md — すべてのスキルが満たすべき構造要件
• トラブルシューティング：references/troubleshooting.md — よくある失敗と解決方法

例

肯定的なトリガー

ユーザー：「PDF を再利用可能なスクリプトで Markdown に変換する新しいスキルを作成してください。」

期待される動作：このスキルのワークフローに従い、ユースケースを把握し、リソースを計画して、スキルを構築します。

トリガーしない例

ユーザー：「src/api/client.ts の TypeScript の型エラーを見つけて修正してください。」

期待される動作：このスキルは使用しません。より適切なスキルを選ぶか、そのまま作業を進めます。

トラブルシューティング

作成したスキルが起動しない

• エラー：期待される場面でスキルが選択されません。
• 原因：説明に具体的なトリガーフレーズがないか、曖昧すぎます。
• 解決策：references/description-authoring.md に従って説明を書き直します。

作成したスキルが冗長すぎる

• エラー：SKILL.md が 5,000 語を超える、またはコンテキストを過剰に占有します。
• 原因：詳細な内容を本文ではなく、リファレンスに記載すべきです。
• 解決策：詳細な内容を references/ 内のファイルに移します。SKILL.md は簡潔なワークフローガイドとして保ちます。

出力がセッションごとに一貫しません

• エラー：スキルの出力品質が毎回異なります。
• 原因：指示が曖昧、または明示的な検証手順が不足しています。
• 解決策：具体例、正確なコマンド、検証手順を追加してください。references/troubleshooting.mdを参照してください。