skill-creator

スキル作成

スキルは、専門知識、ワークフロー、ツールを提供して Claude の機能を拡張する、モジュール式の自己完結型パッケージです。特定の分野やタスクに関する「オンボーディングガイド」と考えてください。手順に関する知識を備えた専門エージェントへと Claude を変身させます。その知識は、どのモデルもすべてを完全に備えることはできません。スキルは、複雑で反復的なタスクに向けた専門的なワークフロー、ツール連携、分野の専門知識、同梱リソース（スクリプト、リファレンス、アセット）を提供します。

まず以下の手順を確認してください。設計の詳細は references/ にあります（リファレンスファイルを参照）。

スキル作成のプロセス

スキル作成では、次の手順を実施します。

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

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

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

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

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

たとえば、画像エディターのスキルを作成する場合、次のような質問が役立ちます。

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

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

スキルがサポートすべき機能が明確になったら、このステップを終えてください。

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

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

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

例：

• pdf-editor スキル（「この PDF を回転して」）：PDF の回転では毎回同じコードを書き直すため、scripts/rotate_pdf.py を保存します。
• frontend-webapp-builder スキル（「ToDo アプリを作って」）：どの Web アプリにも同じボイラープレートが必要なため、assets/hello-world/ テンプレートプロジェクトを保存します。
• big-query スキル（「今日ログインしたユーザー数は？」）：クエリのたびにテーブルスキーマを再確認するため、references/schema.md を保存します。

スキルに含める再利用可能なリソースの一覧（スクリプト、リファレンス、アセット）を作成するには、具体例をそれぞれ分析してください。各種類の用途と、含めないものについては、references/skill-anatomy.mdを参照してください。

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

スキルがすでに存在し、反復またはパッケージ化だけが必要な場合は、このステップをスキップしてください。

この skill-creator にはスクリプトが含まれていません（Anthropic の上流版 skill-creator では、その後 init_skill.py が削除されています）。スケルトンを手動で作成してください。

mkdir -p <skill-name>/scripts <skill-name>/references <skill-name>/assets

続いて <skill-name>/SKILL.md を作成します。フロントマターには name（ディレクトリ名と一致させる。小文字、数字、ハイフンのみで、最大 64 文字）と description を指定し、その後に本文を記述してください。ホストリポジトリが 3 つすべてを必須としている場合（.gitkeep を置いているものもあります）を除き、スキルが使うリソースディレクトリだけを残してください。

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

新規作成したスキルでも既存のスキルでも、編集する際は、そのスキルが別の Claude インスタンスに使われることを念頭に置いてください。Claude にとって有益で、すぐには気づきにくい情報を含めてください。別の Claude インスタンスがこれらのタスクをより効果的に実行するのに役立つ、手順に関する知識、ドメイン固有の詳細、再利用可能な素材を検討してください。

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

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

• SKILL.md が大きくなっている、または複数のバリエーション／フレームワーク／ドメインがある場合：サイズ制限と分割パターンについては、references/progressive-disclosure.md を参照してください
• 複数の手順からなるプロセスの場合：順次ワークフロー、条件分岐、サブエージェントへの委任パターンについては、references/workflows.md を参照してください
• 特定の出力形式や品質基準がある場合：テンプレートと例のパターンについては、references/output-patterns.md を参照してください
• 公式の例：本番環境で使える例については、Anthropic's skills repository を参照してください

複雑なタスクに役立つヒント：

• サブエージェントを活用する - 大量の計算や並列調査が必要なリクエストには、「use subagents」を追加してください
• コンテキストを整理する - 個々のサブタスクをサブエージェントに任せ、コンテキストウィンドウの汚染を防いでください
• 複雑さを可視化する - 新しいプロトコルやコードベースをより深く理解するため、Claude に ASCII 図の作成を依頼してください

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

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

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

SKILL.md を更新する

記述ガイドライン： 常に命令形／不定詞形を使ってください。

フロントマター

name と description を含む YAML フロントマターを記述してください。

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

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

本文

スキルと同梱リソースの使い方を指示してください。本文は500 行未満、約 5,000 トークン未満にしてください。自動圧縮後、Claude Code が呼び出されたスキルの最初の 5,000 トークンのみを保持するため、手順と厳守すべきルールを先に記載し、詳細は参照資料に移してください。

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

ユーザーが配布可能な .skill ファイルを必要とする場合にのみパッケージ化します（たとえば、claude.ai にアップロードする場合）。スキルは、AI プラットフォーム間での移植性を高めるため、Agent Skills オープン標準に準拠しています。.skill ファイルは、スキルフォルダーを zip 圧縮し、スキル名を付けて拡張子を .skill にしたアーカイブです（例：my-skill.skill）。

zip 圧縮する前に、次の項目を検証します。

• YAML フロントマターが解析でき、name と description が存在する
• name がフォルダー名と一致し、description が空ではなく、1,024 文字以内である
• トップレベルに記述されているのが仕様で定められた 6 つのフィールド（name、description、license、compatibility、metadata、allowed-tools）のみである。claude.ai へのアップロードと Skills API は、それ以外のキーを拒否するため、パッケージ化するコピーから余分なキーを削除してください
• SKILL.md が参照するすべてのファイルが存在する

仕様のリファレンスバリデーターは、フロントマターを検証します：skills-ref validate <path/to/skill-folder>（skills-ref）。Anthropic の上流の skill-creator には、検証と zip 圧縮を一度に行う scripts/package_skill.py が含まれていますが、このコピーには含まれていません。

ステップ 6：反復

スキルをテストした後、ユーザーから改善を求められることがあります。スキルを使用した直後など、スキルの動作に関する新鮮なコンテキストがあるときに求められることがよくあります。

反復ワークフロー：

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

基本原則

簡潔さが重要です。 コンテキストウィンドウは共有の資源です。スキルは、システムプロンプト、会話履歴、他のスキルのメタデータ、実際のユーザーリクエストなど、Claude が必要とするすべてのものとコンテキストウィンドウを共有します。Claude はすでに非常に賢い、という前提を基本にしてください。 Claude がすでに持っている知識は加えず、それ以外のコンテキストだけを追加します。情報の一つひとつについて、「Claude は本当にこの説明を必要としているか」「この段落はトークンを消費するだけの価値があるか」と問い直してください。冗長な説明より、簡潔な例を優先します。

適切な自由度を設定します。 タスクの壊れやすさと変動性に合わせて、具体性の度合いを調整します。

• 高い自由度（テキストベースの指示）：複数の方法が有効である場合、判断が状況に左右される場合、またはヒューリスティックに基づいて進める場合
• 中程度の自由度（パラメーター付きの疑似コードやスクリプト）：推奨されるパターンが存在する場合、ある程度の変化が許容される場合、または設定が動作に影響する場合
• 低い自由度（特定のスクリプト、少数のパラメーター）：操作が壊れやすく、エラーが起きやすい場合、一貫性が重要な場合、または特定の順序に従う必要がある場合

Claude が道を探っていると考えてください。崖に挟まれた狭い橋では具体的なガードレールが必要ですが（自由度は低く）、開けた野原では多くの経路を選べます（自由度は高く）。

参考ファイル

ファイル	参照するタイミング
references/skill-anatomy.md	内容を計画するとき（ステップ 2）：構成、スクリプト・参考資料・アセットの用途、含めないもの
references/progressive-disclosure.md	SKILL.md が 500 行または約 5,000 トークンに近づいたとき、あるいはスキルが複数のバリエーションを扱うとき：読み込みレベル、サイズ制限、3 つの分割パターン
references/workflows.md	スキルが複数ステップのプロセスを定義するとき：順次、条件分岐、並列、サブエージェント、チェックリストのパターン
references/output-patterns.md	スキルが特定の形式や品質基準を満たす必要があるとき：テンプレート、例、段階的な詳細度

公式リソース： Agent Skills repository · Skill authoring best practices · Agent Skills specification · Claude Code skills · Creating custom skills · The Complete Guide to Building Skills for Claude (PDF)

Anthropic の skill-creator（github.com/anthropics/skills、Apache-2.0、LICENSE.txt を参照）を改変しています。 claude-mods 向けに、サイズ上限に収めるため、手順を先頭に移し、設計の詳細を参考資料に移しました。スクリプトが同梱されていないため、ステップ 3 と 5 を書き直し、長めの参考資料には目次を追加しました。