skill-creator-primer

スキル作成の概要

注：skill-creator スキルが見つからない場合は、作業を中止し、skill-creator@claude-plugins-official をインストールするようユーザーに依頼してください。必要に応じて、まず /plugin marketplace add anthropics/claude-plugins-official でマーケットプレイスを登録するか、https://github.com/anthropics/skills をクローンし、その skills ディレクトリをローカルのスキルディレクトリにリンクするよう依頼してください。

目の前のタスクに応じて、適切なエントリーポイントに進みます（コンテンツ一覧ではなく、「分岐が増えたときのルーティング」に沿って選択してください）。

• 新しいスキルを作成する → 「会話から意図を把握する」から始め、順に進めます。
• 既存のスキルを編集する → 変更内容に該当するセクションを参照し、その後「セルフレビューの手順」に進みます。
• スキル、またはその差分をレビューする → 「スキルのレビュー」を参照します。
• 説明文やトリガーの調整 → 「効果的な説明文の作成」を参照します。
• スキルの調査結果をレポート、ページ、またはビジュアルとして作成する → references/html-report.md を参照します。

予測可能なプロセスであり、同一の出力ではない

スキルは、可能な範囲で確率的なシステムから決定性を引き出します。予測可能にするのは 出力 ではなく、エージェントが毎回同じ手順を踏むという プロセス です。ブレインストーミングのスキルは、予測可能な形で異なる結果を生み出すべきです。トークンは変化しても、振る舞いは変わりません。この入門ガイドの残りの内容を考える際は、この視点を用いてください。トリガー、構造、誘導、刈り込みは、すべてプロセスの一貫性を高めるための手段であり、コストと保守性はその結果として向上します。変更を評価するときは、そのスキルの目的に照らして、エージェントの振る舞いがより一貫するかどうかを基準にしてください。

各ステップをタスクとして管理する

スキルの作成、更新、レビューに着手する前に、作業の各ステップ（適用する入門ガイドのセクションとセルフレビューを含む）について、完了条件を明記したタスク（TODO）を作成し、そのすべてを完了させてください。

• これは、早まって作業を終えてしまうことを防ぐための、この入門ガイド自体の対策です。ゴールが見えていると、エージェントは目に見える編集だけを済ませ、レビューを省略しがちです。タスクを管理すれば、プロセス全体を常に把握できます。
• 手順の細かさは変更の規模に合わせてください。スキルに大幅な変更を加える場合はステップごとにタスクを作成します。些細な編集でも、説明文の更新、トリガーの競合確認、セルフレビューが必要です。これらはタスクとして管理する場合もしない場合もあります。

スキルの実際の仕組み

スキルはプロンプトベースのコンテキスト修飾子です。 スキルが呼び出されると、次の処理を行います。

1. SKILL.md の指示を会話のコンテキストに注入します
2. ツールの権限を変更し、必要に応じてモデルを切り替えて、実行コンテキストを変更します
3. 簡潔な指示を通じて、エージェントの動作を導きます

スキルの選択は、純粋な LLM の推論によって行われます。 アルゴリズムによるマッチング、キーワード検索、意図の分類はありません（唯一の例外は、任意の paths フロントマターによるファイルグロブのゲートです）。エージェントは Skill ツールのプロンプト内にある説明を読み、どれが適切かを推論します。そのため、description フィールドが最も重要な要素となります。

分岐によって、何を開示するかを決めます。 スキルのすべての分岐で必要になる内容はインラインに記述し、単一の分岐でのみ参照される内容は、コンテキストポインター（バンドルファイル）の背後に置きます。エージェントがポインターをたどるかどうかを決めるのは、参照先ではなくポインターの 文言 です。必須の参照先に弱いポインターが付いているのは、ばらつきの原因となるバグです。インライン化で妥協する前に、文言を明確にしてください。この入門ガイドでは、迷ったら、ほぼ確実に必要な内容はインラインにして、エージェントが読むかどうかを判断する必要がないようにしてください。

分岐が増えた場合のルーティング。 スキルが多数の参照先へ分岐する場合は、読み込みの判断を決定木として記述します。各分岐には1行の条件を、各葉には参照ポインターを置きます。

• 条件は参照先の名前ではなく、タスクで必要となる内容として表現してください。エージェントはタスクと条件を照合してルーティングします。「キーと値（設定、セッション、キャッシュ） -> references/kv.md」のように記述します。
• 決定木は相互排他的な分岐で1階層に保ちます。ルーティングの各段階は、エージェントが誤る可能性のある判断です。
• 参照先が少数であれば、決定木は省略してください。明確な文言のポインターを使うほうが、ルーティング層を設けるよりもコストがかかりません。
• 決定木で扱うのは、どれを選ぶかという判断だけです。参照資料には表を、手順には番号付きリストを使います。

呼び出しモードにはトレードオフがあります ― 意図を持って選びましょう。

• モデル呼び出し：説明はあらゆるリクエストでエージェントのコンテキストに含まれて注意を奪い合い、適切にマッチするスキルであってもエージェントが呼び出しを見送る可能性があります。そのため、スキルが実際に呼び出されることを確認するトリガー評価を作成してください（「スキルのトリガーのテスト」を参照）。
• ユーザー呼び出し（disable-model-invocation: true）：説明はエージェントのすべてのセッションから除外されますが、ユーザーがスキルの存在を覚えておき、スラッシュコマンドで呼び出す必要があります。

タスクの途中でスキルを見つける用途では、モデル呼び出しをデフォルトにします。スキルがたまにしか使われず、ユーザーが確実に呼び出す場合は、ユーザー呼び出しに切り替えます。適切なモードが明らかでない場合は、それぞれの長所と短所を1行ずつ添えて、両方の選択肢をユーザーに提示してください。

---

スキルとカスタムエージェントの違い

スキルを書く前に、スキルが適切な手段かどうかを確認してください。

• スキル ― エージェントが現在のコンテキスト内で必要に応じて読み込む、知識、詳細なワークフロー、または補助ツールです。
• カスタムエージェント ― 独自のコンテキストウィンドウと視点を持ち、軽量なワークフローを備えたペルソナです。レビュー、レッドチーム、前提の検証といった、対抗的な視点や新鮮な視点が必要な作業には、呼び出し元の思い込みを引き継がない独立したコンテキストがあるため、こちらが適しています。
• 併用できます ― エージェントはスキルを読み込めるため、ペルソナに独自のコンテキストが必要な場合でも、共通の知識はスキルに置けます。

関連性の高いスキルは、複数に分けず1つにまとめる

リクエストが複数の関連機能にまたがる場合は、機能ごとに別々のスキルを作るのではなく、段階的な開示を使う1つのスキルにまとめることを基本とします。

• 1つにまとめる理由 ― スキルを追加するたびに、常にエージェントのコンテキストに含まれる説明が増え、選択時に互いに注意を奪い合い、トリガーが重複するリスクも高まります。これはスキルの肥大化につながります。
• まとめ方 ― 関連する動作を1つの SKILL.md にまとめ、それぞれの詳細は、エージェントが必要に応じて読み込むバンドル済みの references/ に移します。
• 分割する場合 ― スキルが実質的に異なる意図で呼び出される場合、または必要とするツールや権限が相反する場合に限ります。

会話から意図を捉える

ユーザーが「これをスキルにして」と言ったら、質問する前に、現在の会話からワークフローを抽出します。次の点を確認します。

• 使用したツールと実行した手順の順序
• 途中でユーザーが行った修正
• 確認できた入力／出力形式
• 会話全体で繰り返されたパターン

下書きを作成する前に、次の点を決めます。

• スコープ - スキルが依頼されたタスク自体を担うのか、それともその上位の成果を担うのかをユーザーに尋ねます（「このクラッシュを修正する」か「アプリがクラッシュしない状態を保つ」か）。成果を担うには、エージェントが人の助けなしに実行・検証するために必要なデータソース、環境、マッピングを列挙する必要があります。
• 方法 - そのスキルの領域について、次の点に答えます。ユーザーが依頼しなかったことのうち、一流の実践者なら何をするか。最初に扱う最も生の素材は何か。どのような方法やツールを使うか。エージェント以外に、結果が正しいことを示すものは何か。回答は手順として組み込みます（「失敗モード」の「方法よりペルソナ」と「自己評価」を参照）。

不足している情報をユーザーに確認してから、スキルの作成に進みます。

プライマーの assets/skill-template.md を使って下書きを作成します。新しいスキルディレクトリにコピーして SKILL.md とし、プレースホルダーを埋め、使わないセクションを削除します。

効果的な説明の書き方

説明は、スキルを適切に機能させるうえで最も重要な要素です。他のすべてのスキルの説明とトークン予算を共有し、エージェントのコンテキストで常に有効になります。

スキルの説明チェックリスト

以下の各項目をタスクとして確認し、合格／不合格を判定します。すべて合格したら完了です。編集を加えた後は、項目全体を再確認してください。1か所の修正が別の項目に影響することがあります（文言を追加したことで上限を超える場合があります）。

1. 簡潔にする。 スキルはエージェントが使うものです。エージェントに必要なのは、冗長な文章ではなく、明確で重要度の高いトリガーです。
2. 1～2文に収める。 バリデーターの語数上限は目標ではなく、超えてはならない上限です。説明は、スキルが起動するかどうかに関係なく、すべてのセッションのすべてのターンで消費されるため、本文の何よりも上限の超過を避けてください。
3. 説明は、エージェントがスキルを読み込むかどうかを判断するためだけに使います。 起動後の指示や、スキルの内容・内部動作の要約は含めません。ワークフローの要約があると、エージェントは分岐を飛ばし、要約だけに基づいて動くおそれがあります。
4. 説明を他のスキルと明確に区別します。近接するスキルと混同される可能性があってはなりません。似た名前、同じ動詞と目的語、重複する状況のトリガーに注意します。同時に有効になるスキルの組み合わせは導入環境によって異なるため、具体的で限定されたトリガーによって区別します。比較対象を列挙できる場合は、後述の「説明トリガーの競合を確認する」を実行します。
5. 命令形で記述します。説明は、エージェントにいつ動くべきかを指示する表現にします。「このスキルは～を実行します」ではなく、「～の場合はこのスキルを使用してください」とします。エージェントは行動するかを判断するため、行動すべき状況を伝えます。
6. 実装ではなく、ユーザーの意図に焦点を当てます。スキルの内部的な仕組みではなく、ユーザーが達成しようとしていることを記述します。エージェントはユーザーの依頼に照らして判断します。
7. 冒頭に重要な語を置きます。説明の冒頭にある語が呼び出しの手がかりになります。その語がユーザーのプロンプト、ドキュメント、コードにも含まれていれば、より強く呼び出されます。
8. 分岐ごとにトリガーは1つにします。スキルが扱う分岐ごとにトリガーを1つ設けます。1つの分岐を別の言葉で言い換えるだけの同義語は、対応範囲を広げずにコンテキストを消費するため削除します。スキル本文にすでに記載されている内容も重ねて書きません。
9. スキルが過剰に起動する場合は、除外する負のトリガー節を追加します。近接する意図と、代わりに使用するスキルを明記します。「X には使用せず、代わりに Y を使用してください」のように、スキルを適切に呼び出すだけでなく、別のスキルへ振り分けられるようにします。

説明文のトリガーの競合を確認する

エージェントが両方の説明文を読んでも、リクエストに対してどちらを読み込むべきか確実に判断できない場合、その2つのスキルは競合しています。このチェックで確認するのはそれだけです。関連する領域を扱うスキル同士は問題ありません。列挙できる範囲のスキル、つまり隣にインストールされているスキル、またはそのスキルが追加されるリポジトリを対象に確認してください。

新規または編集した説明文を複数のスキルと比較するには、各スキルのディレクトリ、名前、説明文を一覧にします。

python3 <skill-creator-primer>/scripts/list_descriptions.py <skills-root>

動詞や対象（作成／編集、図、レビュー、テストなど）が共通するスキルをグループ化し、単に共通の単語があるかではなく、区別する要素なしに意図が重なるかどうかをペアごとに比較します。

トリガーに明確な区別要素がある場合、そのペアは「許容可能」です。

• 対象となるツール、言語、ファイル形式が異なる場合、エージェントはそれに基づいて振り分けます。共通テンプレートを使う意図的なファミリー（go／rust／python：「<language> プロジェクトで作業するときに有効化する」など）は問題ありません。言語が振り分けの手がかりになるため、区別をなくさないでください。
• 同じ作業でも、段階や範囲が異なる場合（計画と実装、1つのファイルとリポジトリ全体など）。
• 一方が入門用またはサブスキルであり、もう一方がそれを明示的に指定している場合。

次の場合、そのペアは「競合」です。

• トリガーが互換的で、どちらも同じリクエストに同程度に当てはまる場合。
• 一方の説明文が、追加の区別要素なしに、もう一方の説明文の逐語的な部分集合になっている場合。
• 振り分けの手がかりがないまま、同じ対象に対して同じ作業を行うと説明している場合。

許容可能 — ほぼ同じ表現でも、ツール名によって明確に振り分けられる場合：

mermaid-diagrams: "...mermaid 図の作成または更新。mermaid のベストプラクティスに関するガイダンスを提供します。" excalidraw-diagrams: "...Excalidraw 図の作成または更新。Excalidraw のベストプラクティスに関するガイダンスを提供します。"

競合 — 区別する「次の場合に使用する」という記述がなく、一方のトリガーがもう一方の逐語的な部分集合になっている場合：

domain-model: "既存のドメインモデルに照らして計画を検証するグリルセッション。ユーザーがプロジェクトの用語に照らして計画をストレステストしたい場合に使用..." grill-with-docs: "既存のドメインモデルに照らして計画を検証するグリルセッション..."（同じ書き出しで、区別するトリガーがない）

実際に競合している場合は、最小限の修正を選びます。一方の説明文の「次の場合に使用する」を、異なる点が明確になるように調整する、いずれかのスキルの範囲を狭める、または実質的に同一のスキルを統合します。すでに明確に振り分けられる説明文は、どれほど似ていてもそのままにしてください。

スキルのトリガーをテストする

スキルが有効になるかどうかは、その description のみで決まります。エージェントは説明文を読んで、どのスキルを読み込むかを判断します。説明文が適切なリクエストで発動し、それ以外では発動しないか、特に過剰または過少に発動するおそれがある場合は、トリガー評価を作成します。現実的なクエリを用意し、スキルを有効化すべきかどうかをそれぞれにラベル付けし、実際の説明文に対して評価します。

スキルと同じ場所にある evals/<set>.json に評価セットを配置し、同梱の scripts/eval_triggering.py を実行します。スキル評価を作成または実行する前に、references/trigger-evals.md を読んでください。

自由度の度合い

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

自由度が高い（テキストによる指示）：複数の方法が有効で、判断は状況に左右され、ヒューリスティックが進め方の指針になります。

自由度が中程度（擬似コード／パラメーター化されたスクリプト）：推奨されるパターンはありますが、ある程度の変更は許容され、設定によって動作が変わります。

自由度が低い（具体的なスクリプト、少数のパラメーター）：操作が壊れやすく、エラーが発生しやすいため、一貫性が重要で、特定の手順が求められます。

エージェントが経路を進む様子を想像してください。崖に挟まれた細い橋ではガードレールが必要です（自由度が低い）。広い野原なら、さまざまな経路を進めます（自由度が高い）。

スキル作成のヒント

コンテンツの選定

• 当たり前のことは書かないでください。 エージェントはすでにコーディングについて多くのことを知っており、デフォルトの見解も持っています。エージェントを通常の思考パターンから外す情報に、スキルの内容を絞ってください。スキルがなくてもエージェントが確実に正しい行動を取るなら、その内容はトークンの無駄です。
• 知っていることと、実行することは別です。 削るかどうかの判断基準は「エージェントはこれを知っているか？」ではなく、「指示されなくても、エージェントは毎回この順序で確実に実行するか？」です。トレーニングデータに含まれる宣言的な知識（よく知られた API、デザインパターン、標準的な構文）は、確実に思い出せるため削ってください。必須のワークフローは残してください。エージェントは各ステップを知っていても、自分のやり方を選んだり、スキルで順序を定めない限り手順を飛ばしたりすることがあります。強制事項、順序の制約、ゲート、チェックリストは、新しい知識を教えるのではなく、エージェントの「行動」を変えることでトークンを使う価値があります。
• ツールの失敗をあらかじめ記載しないでください。 エージェントがエラーを回避できるようにバリデーターのエラーコードを列挙すると、バリデーターの変更履歴をスキルが追うことになります。中途半端な一覧を載せるくらいなら、何も載せないほうがよいでしょう。エージェントは、記載のない項目を「チェックされていない」と解釈します。実行して結果を読むループを用意してください。失敗のコストが高く、事前に防ぎたくなる場合は、ツールに「未対応の項目を報告する」モードを追加するのが解決策です。そうすれば、エージェントは説明を受けるのではなく、必要な情報を尋ねられます。
• Gotchas セクションを作成してください。 どのスキルでも、最も価値の高い情報は、スキルの使用時にエージェントがよくつまずくポイントを挙げた Gotchas セクションです。実際の失敗をもとに、時間をかけて内容を充実させてください。よくできた Gotchas セクションは、一般的な説明を何ページも載せるより役に立つことがあります。

スキルの構成

• 文章より構成を重視してください。 指示は番号付きの手順か箇条書きにし、各項目には短い一文で一つのアクションを記載してください。段落は概念の説明に使います。文章が長いと、エージェントが実行すべきロジックが埋もれてしまいます。これはフロントマター、argument-hint、JSON スキーマの説明フィールドにも当てはまります。段落ではなく、正確な言葉を少しだけ使ってください。Gotchas、チェックリスト、事実の一覧では、電文調の断片（冠詞の省略、「エラー → 修正」の組み合わせなど）でも構いません。概念、手順、誘導の微妙な違いが曖昧になる場合は、断片的な表現を避けてください。「Examples」の2つ目の組み合わせを参照してください。
• 一つの概念に関する要素はまとめてください。 定義、ルール、注意事項は、あちこちに散らさず、一つの見出しの下にまとめてください。一つ読めば、関連する情報も把握できるようにします。スキルはエージェント向けのドキュメントとして読める必要があります。これは重複とは異なります。同じ意味を2か所で繰り返すのではなく、一つの意味を複数の場所に分散させないということです。
• サブエージェントの利用を考慮して作成してください。 サブエージェントを使うと、独立した作業を並列化でき、大量の中間出力をメインの会話に持ち込まずに済みます。作業を分担できる箇所（項目ごとの確認、独立した調査項目、読み取り専用の一括確認など）では、受け渡す情報を明示してください。各サブエージェントに必要な情報と、返してもらう内容（生の出力ではなく、要約、判定、ファイルパスなど）を示します。オーケストレーションの方法を規定するのではなく、分担できる箇所を提案してください。スキルを実行するモデルが、作成したモデルより適切に調整できる場合があります。
• セットアップを検討してください。 スキルによっては、ユーザーごとの設定（使用する Slack チャンネル、データベース、API キーなど）が必要です。パターンとして、初回実行時に設定ファイルを確認し、存在しない場合はユーザーに尋ねて回答を保存します。ユーザーや環境によって異なる値をハードコードせずに済みます。
• Markdown 内にインラインスクリプトを追加しないでください。 単一のコマンドや簡単なワンライナーは問題ありませんが、スクリプトは別ファイルにしてください。バリデーターは10行を超えるフェンス付きコードブロックに警告を出します。スキルにスクリプトを含める場合は、適切に記述してください（下記の「Writing Scripts」を参照）。
• 深くネストした参照は避けてください。
• 100行を超える参照ファイル（references/*.md）には、エージェントが部分的に読んだ場合でも全体像を把握できるよう、冒頭に簡潔な目次を記載してください。

エージェントの誘導

• エージェントを型にはめすぎないでください。 スキルはさまざまなプロンプトやコンテキストで再利用されるため、厳格すぎる指示（「必ず」の多用や、手順を厳密に指定すること）は、コンテキストが変わると機能しなくなります。エージェントに必要な情報を与え、状況に合わせて柔軟に対応できる余地を残してください。上記の「自由度」を参考に、指示の厳密さを調整してください。
• ピンクの象を連想させる指示は避けてください。 望ましくない行動を具体的に挙げると、それをかえって促してしまいます（「delve という単語を使わないで」と書くと、delve が頭に浮かびます）。望ましい行動を肯定的に伝えてください。禁止事項を設ける必要がある場合は、エージェントが代わりに何をすればよいか分かるよう、具体的な代替案も示してください。避けるべき語句の一覧（例：使用を避ける特定のフレーズ）は、代替表現と併せて示すのであれば問題ありません。
• 誘導語を使ってください。 概念ごとに、事前学習済みで平易かつ意味の密度が高い用語を1つ選び、一貫して使ってください（常に「field」を使い、「field」「box」「element」を混在させないでください）。エージェントは推論中にその用語を反復し、既存の連想が振る舞いを導きます。新たに作った用語には、そうした連想がありません。スキルが指示に従わない（指示を無視する、手順を飛ばす、早々に終える）場合、誘導語を選定または強化する場合、あるいは複数ステップの手順に完了条件が必要な場合は、references/steering.md を読んでください。誘導語、完了条件、早期終了への対処について説明しています。
• 記述されたワークフローでは、タスクの追跡を最初のステップにしてください。 ワークフローの最初のステップとして、各ステップの完了条件を明記したタスク（todo）を作成し、それらを完了するまで作業するようエージェントに指示してください。これは、この入門書自体にも適用される早期終了への同じ対策です（「各ステップをタスクとして追跡する」を参照）。

スクリプトの作成

スキルにスクリプトを含める場合：

• 問題を解決し、丸投げしないでください。 エラー条件はスクリプト内で処理し、失敗したままエージェントに対応を委ねないでください。不足しているファイルを作成したり、妥当なデフォルト値にフォールバックしたりするスクリプトのほうが、例外を投げるスクリプトより信頼できます。
• 根拠のない定数は使わないでください。 設定値の根拠をコメントで説明してください。タイムアウトを30sにする理由を説明できなければ、エージェントも説明できません。
• 冒頭のコメントは1行にしてください。 スクリプト名、--help、コードを見れば何をするか分かります。それらを冒頭のコメントブロックで繰り返すのは、読者全員に余計な負担をかけるだけです。冒頭には目的を1行で書き、分かりにくい制約や定数を選んだ理由は、該当する行のそばに記してください。
• 使い方はスキルではなく --help に記してください。 スクリプトには名前付き引数と、それぞれを説明する --help を用意してください。スキルにはスクリプト名と実行するタイミングを記し、それ以外はエージェントが --help で確認できるようにしてください。引数の説明を SKILL.md に書くと、常に読み込まれるうえ、スクリプトを変更した時点で古くなります。
• 実行するのか、参照するのかを明示してください。 スクリプトを実行するのか（「フォームのフィールドを取得するには extract_fields.py を実行してください」）、参考資料として読むのか（「抽出アルゴリズムについては extract_fields.py を参照してください」）を明確にしてください。通常は実行を推奨します。
• 標準ライブラリを活用し、必要な依存関係はその場で宣言してください。 標準ライブラリだけで動くスクリプトはセットアップ不要でどこでも実行できるため、優先してください。サードパーティーパッケージが本当に必要な場合は、uv で実行し、スクリプト冒頭のインラインメタデータに PEP-723 形式で依存関係を宣言してください。そうすれば、依存関係もファイルと一緒に扱えます。

トークン予算の指針

各項目に対して、「エージェントにこれが必要か、そしてトークンコストに見合うか」を問いかけます。

• メインの SKILL.md は 4k トークン未満を目指し、詳細な内容はリファレンスに移します。
• リファレンスは、該当する分岐が実行されると全体が読み込まれます。分岐ごとにゲートされた小さなリファレンスが多数ある場合はコストを抑えられますが、巨大なリファレンスが 1 つあると、その分岐で全量が読み込まれます。大きすぎる SKILL.md と同様に、分割するか内容を絞ってください。
• 品質基準（塊、削除テスト、失敗モード）は、参照されるすべてのファイルに等しく適用されます。
• 4k という目安は、分岐のある内容を前提としています。ほとんどすべての有効化でほとんどすべてのセクションが必要になる場合は、より大きな SKILL.md を選ぶのが適切です。サイズではなく削除テストで判断してください（この入門書はその条件に当てはまります。「Branches decide what to disclose」を参照してください）。
• 同梱のバリデーターで測定してください（「Validating a Skill」を参照）。

例

良い例（簡潔で、すぐに実行できる内容）：

## Extract PDF text

Use pdfplumber for text extraction:

`python scripts/extract_pdf_text.py <pdf-file>`

悪い例（冗長で、文章に埋め込まれた内容）：

## Extract PDF text

PDF (Portable Document Format) files are a common file format that contains
text, images, and other content. To extract text from a PDF, you'll need to
use a library. There are many libraries available for PDF processing, but
pdfplumber is recommended because it's easy to use and handles most cases well.
First, you'll need to install it using pip. Then you can use the code below...

良い例（指示が構造として示されている）：

1. Run the skill's evals if present.
2. On failure, tune the description and re-run.

悪い例（同じ指示が文章に埋もれている）：

When you begin the review you should first check whether the skill has evals,
and if it does, run them before anything else, keeping in mind that failures
may mean the description needs tuning, in which case you should revisit it
and run them again.

同梱ファイルの構成

ツールキット全体でスキルの構成を予測しやすくするため、同梱ファイルの保存場所を標準化します。

• references/ - エージェントがリファレンスとして読む Markdown ファイル（段階的開示で、必要に応じて読み込むレイヤー）。
• scripts/ - エージェントが実行するスクリプト。
• assets/ - エージェントがコピーまたは入力するテンプレートと、SVG やアイコンなどのテキスト以外の素材。コミットするより、外部ソースから参照する方法を優先してください。同梱バイナリは、エージェントにとってメリットがない一方で、容量とコンテキストの負荷を増やします。
• CHANGELOG.md - スキルは非コードのプロジェクトなので、日付見出し（## YYYY-MM-DD、新しいものから順）を使い、バージョン番号は付けません。これにより、スキルの履歴を本文から切り離せます（「Fossilised diff」を参照）。更新ルールは、ファイルの `` コメントとスキル自身の CLAUDE.md の両方に記載します。読者から見える変更のみを記録し、各変更は 1 行で記載し、同日の編集はまとめます。変更履歴を設定するスキルが利用できる場合は、それを使用してください。
• references/ に複数の兄弟領域がある場合は、各領域で同じファイル構成にします（例：<domain>/patterns.md、<domain>/gotchas.md。空になるファイルは省略します）。こうすることで、エージェントは目次を読まなくても、次の階層に何があるか把握できます。

スキルに含めないもの

スキルには、機能を直接支えるファイルだけを含めてください。

作成しないでください：

• README.md や、ユーザーから依頼されていない人間向けのドキュメント、セットアップ手順
• 作成プロセス自体に関する情報
• スキルの機能の実行に役立たない、冗長な内容や埋め草、重要でない内容
• メインの SKILL.md の目次や索引
• 「使用するタイミング」セクション - 説明が該当した後に本文が読まれるため、使用するかどうかはすでに決まっています。適用条件は説明に移してください。「使用しないタイミング」と「Y の代わりに X を使用するタイミング」は、動作を変えるため残してください。
• エージェントが簡単に推測できる内容や、スキルがなくても参照先が分かる内容
• リッチなファイル形式（例：zip、pptx、png、pdf など）。テンプレートである場合を除きます。AI はテキストとツールを使うのが最も効率的で、同梱ファイル形式は負荷と複雑さを増やします。

複数のエージェントで動作するスキルを作成する

スキルは、標準の Agent Skills をサポートするあらゆるツールで動作する必要があります。Claude Code が主な対象ですが、GitHub Copilot なども同じ形式を読み込むため、表現やツールは特定のツールに暗黙のうちに依存させず、移植性を保ってください。

• スキルを実行するものを指す場合は、「Claude Code」や「Copilot」ではなく「エージェント」と呼んでください。
• 仕様で標準化されているフロントマターや移植可能なコマンドを優先し、以下の Claude Code 固有の拡張フィールドは、スキルで本当に必要な場合にのみ使用してください。
• デフォルトでは compatibility: を省略してください。スキルが特定のツールに本当に依存する場合に限り、文章に前提を埋め込むのではなく、フロントマターに指定します（例：compatibility: claude-code、github-copilot、microsoft-cowork）。ツールに依存しないスキルでは指定しません。

Claude Code のフロントマターと拡張機能

Agent Skills の仕様でカバーされていない、Claude Code 固有のフィールドです。特に必要な場合にのみ含めてください。

• argument-hint：オートコンプリート中に、想定される引数のヒントとして表示されます。例：[issue-number] や [filename] [format]。スキルが引数を受け取る場合にのみ含めてください
• arguments：スキル本文で $name による置換に使う、名前付きの位置引数です。スペース区切りの文字列または YAML リストを指定できます。名前は順番に位置へ対応します。スキルで名前付き置換を使う場合にのみ含めてください
• model：モデルを上書きします。"inherit"（デフォルト）または "claude-sonnet-5" のような特定のモデル ID を指定します。ユーザーがリクエストした場合にのみ含めてください
• effort：スキルがアクティブな間の努力レベルを上書きします。選択肢：low、medium、high、xhigh、max。ユーザーがリクエストした場合にのみ含めてください
• context："fork" を設定すると、フォークされたサブエージェントのコンテキストで実行されます。広範な調査や大規模な出力を伴うスキルに便利です。ユーザーがリクエストした場合にのみ含めてください
• disable-model-invocation：true に設定すると、Claude がスキルを自動読み込みしないようにできます。ユーザーが手動で起動する副作用のあるワークフローに使用します。このモードは、ユーザーからのリクエストがあった場合に限らず、上記の「Invocation mode is a trade-off」とセルフレビューの手順 6 に従って慎重に選択してください
• user-invocable：デフォルトではスキルはスラッシュコマンドとして表示されます。false に設定すると、メニューに表示されなくなります。ユーザーがリクエストした場合にのみ含めてください
• agent：context: "fork" が設定されている場合に使用されるサブエージェントの種類です（デフォルトは general-purpose）。それ以外の場合は効果がありません。ユーザーがリクエストした場合にのみ含めてください
• paths：スキルが有効になる条件を、特定のファイルやディレクトリに限定する Glob パターンです。スキルの対象範囲が特定のファイルやディレクトリに限定される場合にのみ含めてください
• hooks：このスキルのライフサイクルに適用されるフックです。スキルのアクティブ中にフックが必要な場合にのみ含めてください
• shell：インラインの bang-backtick コマンドブロックに使用するシェルです（bash または powershell）。スキルでそれらを使う場合にのみ含めてください
• allowed-tools：事前承認されたツールをスペース区切りで指定します。可能な場合は範囲を限定してください。例："Read Write Bash(uv run scripts/*.py *) Grep WebFetch(domain:code.claude.com)"（非推奨の : 構文、たとえば Bash(command:*) は使わず、Bash(command *) を使用してください）
• disallowed-tools：スキルがアクティブな間、利用可能なツール群から除外するツールです（次のユーザーメッセージで解除されます）。バックグラウンドループで AskUserQuestion を呼び出してはならない場合など、自律型スキルに使用します。ユーザーがリクエストした場合にのみ含めてください
• when_to_use：使用しないでください。

---

スキルの検証

同梱の validate_skill.py を使って、公式の Agent Skills 仕様に照らして検証します。仕様チェックは実行時にのみ行われます。プライマーが有効な間は、PostToolUse フックがスキルの SKILL.md または参照ファイルを編集するたびに、トークンレポート（--report-only）を再実行します。

uv run <skill-creator-primer>/scripts/validate_skill.py <skill-dir> [<skill-dir> ...]

複数のスキルを一度に渡せます。各レポートの先頭にはそのパスが示され、末尾には合格数が表示されます。いずれかのスキルが不合格の場合、終了コードは失敗を示します。

有効なスキルの場合、仕様チェックとともにトークン予算の推定値と評価も表示されます。カウント対象は、SKILL.md が実際に参照する Markdown のみ（推移的な参照も含む）なので、参照されていないファイルがあっても数値は増えません。カウントには tiktoken に対して調整された文字数÷4.12 のヒューリスティックを使用します。実際のトークナイザーでカウントするには、--tiktoken（uv run --with tiktoken で実行）を追加します。

• 優秀：1k～5k トークン

• 良好：5k～9k トークン

• 可：9k～12k トークン

• 不良：12k 以上のトークン

• 評価は、全ファイルの合計ではなく、最悪ケースの負荷（SKILL.md ＋最大の参照ファイル。これは分岐が 1 つ実行される場合の下限であり、複数の参照ファイルを連鎖させる分岐ではさらに負荷が高くなります）を判定するため、段階的開示によるペナルティはありません。終了コードで強制され、不良は失敗、可は警告となり、負荷の原因となるファイル名がメッセージに示されます。

• 分岐テストでほぼすべての内容をインラインに保つ必要があるスキルは、フロントマターに metadata.skill-lint.max-load-tokens: <int> を宣言し、上限の根拠を末尾の # コメントで説明できます。これは最悪ケースの負荷（SKILL.md と最大の参照ファイルの合計）に上限を設けるもので、SKILL.md のみを対象とするものではありません。上限内であれば、上限を明記して合格となり、改善の助言は表示されません。上限を超えた場合は、通常の評価基準が適用されます。宣言のないコメントでは上限は無効です。根拠を説明することが重要なため、この設定を使うのは削除テストをすでに実施した後にしてください。

• 検出事項は FACTS（説明が長すぎる、負荷が予算超過している、SKILL.md 内のブロブ：常時読み込まれるコスト。修正が必要です）と SIGNALS（大きな参照ファイル、その中のブロブや 10 行以上のコードフェンス：分岐時に読み込まれるため、不要な記述なのか、必要な詳細なのかを判断してください）に分類されます。参照ファイルにブロブが 3 つ以上あると警告が表示されます。負荷の評価では、参照ファイルは簡潔であることを前提とします。

• ブロブとは、形式を問わず（段落、リスト項目、引用、表の行）、100 語以上のテキスト単位です。指示が埋もれるほど長い文章を指します（Failure Modes の「埋もれた指示」を参照）。ブロブの一覧は、Self-Review Protocol の圧縮工程に使用されます。

• 密集した並びとは、90 語以上の単位が 3 つ以上連続するもの（70 語以上のリスト項目が 2 つ以上）を指します。すべての単位がブロブというわけではなく、途中で区切りがない長い文章を指します。? の注記付きで報告されますが、これはアメリカ式の綴りによる場合があるためです。各単位には個別の指示が含まれている可能性があるので、変更する前に内容を確認してください。

• 不可視文字（ノーブレークスペースやゼロ幅スペース、プライベートユース文字。多くはウェブページからのコピー時に混入します）は、どこにあっても FACTS です。コマンドや説明に 1 つ含まれているだけで動作が壊れる可能性があり、どのエディターでも表示されません。

ユーザーからスキルレポート、ページ、または検出結果のビジュアルを求められた場合は、references/html-report.md を読み、記載されているレンダラーを実行してください。それ以外の場合は、上記のテキストレポートで対応できます。

上流のバリデーターでは、フロントマターの許可リストが不完全な場合があります

skills-ref（および python -m scripts.package_skill によるパッケージ化のゲートとなる skill-creator の quick_validate.py。失敗すると「Validation failed」と表示されます）は、仕様のコアプロパティを6つ（name、description、license、allowed-tools、metadata、compatibility）しか認識せず、有効な Claude Code 拡張フィールド（when_to_use、argument-hint、arguments、disable-model-invocation、user-invocable、disallowed-tools、model、effort、context、agent）をすべてエラーにする場合があります。これらのフィールドだけが原因でスキルが失敗している場合でも、そのスキルは有効です。

同梱の validate_skill.py は、実際に仕様に違反している場合のみエラーにし、不明なフィールドは警告に格下げするため、文書化された拡張フィールドやリンターより新しいフィールドも通過します。また、skills-ref の StrictYAML ではなく PyYAML でフロントマターを解析するため、フロー形式の配列（allowed-tools: [Read, Write]）も通過します。

公式ドキュメント（https://code.claude.com/docs/en/skills#frontmatter-reference）が、バージョンに応じた最新の正規リストです。

失敗モード

これらのモードを使って、サイズが大きすぎるスキルや信頼性の低いスキルを診断し、対処してください。

• 早すぎる完了 - ステップが終わる前に完了することです。対処法：完了条件を明確にし、その後のステップは必要になるまで隠しておきます（references/steering.md を参照）。
• 重複 - 同じ意味が複数の場所にあることです。SKILL.md 内、SKILL.md と参照資料の間、テキストとスクリプトの --help またはヘッダーの間、さらにテキストが正規の情報源として引用している情報源を言い換えている場合も含みます。対処法：各ステップおよび各参照項目につき、情報源を1つにします。
• 堆積 - 追加するほうが削除するより安全に感じられるために、古い情報が積み重なることです。対処法：整理の規律を設けます。分岐に再構成し、どの分岐でも必要とされない内容を削除します。
• 肥大化 - すべての行が有効で重複していなくても、単に長すぎることです。対処法：段階的に開示します。「スキルの実際の仕組み」の分岐テストに沿って分割するか、別途、順序立てて使うスキルに分けます。
• ツールによる補完 - ツールに必要なモードがないために、その役割を散文が担っている状態です。スキルが肥大化する主な原因です。完成した成果物しか評価できないツールでは、スキルが成果物全体をあらかじめ説明する必要があります。一方、部分的な成果物に対する進捗を報告できるツールなら、スキルではエージェントが与える判断基準だけを説明すれば済みます。対処法：ツールに進捗報告モードを追加し、それによって不要になる散文を削除します。長いスキルを圧縮する前に、これを確認してください。
• 無効な指示 - モデルがすでにデフォルトで従っている行です。関連性のある行でも無効な場合があります。モデルに依存するため、スキルを実行してテストしてください。対処法：冒頭の言葉をより強いものにするか、削除します（削除テストを実施してください）。
• 手法よりペルソナを重視 - 「X の専門家として行動する」という枠組みです。エージェントは専門用語を採用しても、デフォルトの手法を使い続けます。対処法：実践者が使う道具、生の入力、手順をステップとして明示します（「データサイエンティストとして行動する」ではなく、「データベースを照会してモデルを当てはめる」とします）。
• 自己採点 - 検証可能な出力に対する唯一の確認がエージェント自身の判断であり、自分の成果を通しがちです。対処法：エージェントが実行する外部の判定手段（テスト、バリデーター、レンダリングしての確認、新しいコンテキストのサブエージェント）を指定し、合格するまで繰り返します。
• 指示の埋没 - 本文や description／フロントマター／スキーマのフィールド内で、指示やロジックが段落の散文や大きすぎるリスト項目に埋もれていることです。対処法：「散文より構造的に」の方針に従って変換します（スキル作成のヒント）。バリデーターの塊リストで該当箇所を特定できます。
• 化石化した差分 - 本文に自身の履歴が書かれている状態です。チケット ID、変更メモ、置き換えられた仕組み、レビュー担当者向けの理由説明などが該当します。対処法：以前のバージョンを見たことのないエージェントにも読めるよう、現在の動作だけを記述します。出典情報は変更履歴と git に記録します。

セルフレビュー手順

スキルが3つ以上の参照ファイルにまたがる場合は、ファイルごとの読み取り専用レビューを並行するサブエージェントに割り振り、各エージェントが担当ファイルの価値の低い説明やファイル内の重複を確認して、要約を返すようにします。読み取りは競合しません。SKILL.mdと参照ファイル間の重複など、ファイルをまたぐ確認は分割できません。メインエージェントが要約をもとに調整します。編集は1つのエージェントに任せるか、各サブエージェントに重複しないファイルを割り当てます。

スキルの作成後または更新後は、必ずプライマーを使って批判的なセルフレビューを実施しなければなりません。以下の各項目について、タスク／TODOを作成して完了してください。

1. SKILL.md内、SKILL.mdと参照ファイル間、テキストとスクリプト間の重複情報を確認します（スクリプトの--help、docstring、ヘッダーコメントも確認対象です）。情報は1か所に残し、最も後に読み込まれる場所に置いて、そこへの参照を示します。
2. 価値の低い説明や埋め草を削除します。削除テストを適用します。ある文章を削ってもエージェントの動作が変わらないなら、それは不要です。削除したままにします（「失敗パターン」を参照）。対比表現（「XではなくY」）には置き換えテストを適用します。順序を逆にしても意味が通るなら、その対比には情報がありません。主張を直接述べます。
3. 表現を簡潔にし、重要な情報を目立たせながら語数を減らします。
4. バリデーターを実行します（「スキルの検証」を参照）。評価がOKまたはPoorの場合は、まず「ツールによる補完」（「失敗パターン」）に該当しないことを確認してから、圧縮を行います。
   • 現在のドラフトに含まれるすべてのルール、手順、注意点をチェックリストにします。
   • 新しいコンテキストのサブエージェント（自身の文章に引きずられるため、ドラフト作成時と同じコンテキストは使わないでください）に、語数を約75％（OKの場合）または約60％（Poorの場合）に減らすよう依頼します。指示を含む段落は手順や箇条書きに変え、由来や正当化を添える説明は削除し、書き換えた内容のみを返すように指示します。環境にcompression-editorエージェントがある場合は、そちらを優先します。
   • チェックリストの全項目が残っていることを確認してから、書き換えを採用します。通常は1回行います。変更概要にトークン数の増減を記載します。
5. 説明が簡潔でありながら、起動条件を満たすだけの内容があることを確認します（「効果的な説明を書くためのチェックリスト」を参照）。
6. 呼び出しモードを決定します。タスク中の発見に使う場合はモデル呼び出し、たまに使う機能でユーザーが覚えて呼び出す場合はユーザー呼び出し（disable-model-invocation: true）にします。判断に迷う場合は、両方をユーザーに提示します（「呼び出しモードはトレードオフ」を参照）。
7. 余計なファイルが作成されていないことを確認します。
8. ピンクの象効果を避けるため、指針は肯定形で示します。「Xをするな」を「Yをする」に書き換えるか、禁止事項と具体的な代替案を併記します（「スキル作成のヒント」を参照）。
9. 決定的な結果が求められる作業には、決定的なツールを使います。スクリプトで実行できる作業は、解釈に基づく指示に頼らず、エージェントにそのスクリプトを実行させます。
10. スキルに評価テストがある場合は、最新の状態で、問題なく実行できることを確認します。
11. 新しく作成したスキルの場合は、上記の手順に合格した後、新しいコンテキストのサブエージェント（フォークではありません。「スキルとカスタムエージェント」を参照）を起動し、skill-creator-primerとskill-creatorを有効にして、「スキルのレビュー」に従い、新しいスキルを読み取り専用でレビューさせ、評価付きの所見を返させます。仕様とプライマーに対する違反を修正し、判断が必要な項目をそれぞれ検討した後、再検証します。通常は1回行います。サブエージェントを使えない場合は、新しいセッションでユーザーにレビューを依頼します。
12. 4の後にスキルを変更した場合は、バリデーターを再実行します。レビューは、検証ゲートに合格した時点で完了です。

評価されるのは冗長さではなく、知識の質です。

スキルのレビュー

スキルが自分のものでも他の人のものでも、レビュー基準は同じです。差分を評価する前に、スキル全体（SKILL.md と参照されているすべてのファイル）を読んでください。見た目がきれいな編集でも、まだ確認していない参照先と内容が重複したり、矛盾したりすることがあります。そのうえで、次の手順に従います。

1. まず機械的に検証します。「スキルの検証」を参照してください（仕様とトークン予算）。
2. 「失敗パターン」に照らして問題を診断し、各指摘を該当するパターンと修正方法とともに報告します。
3. 説明が変更されている場合は、「スキルの説明チェックリスト」と「説明のトリガー競合の確認」に照らして評価します。トリガーの過剰または不足が問題になっている場合に限り、スキルのトリガー評価を実行してください。これは調整のための補助であり、合否を決める基準ではありません。
4. 差分がある場合は、変更後も説明と参照先がスキルの分岐と一致していることを確認します（「スキルの実際の仕組み」を参照）。
5. すべての指摘を評価します。仕様違反、プライマー違反（該当するセクションを引用）、または判断による指摘のいずれかです。最初の2つだけが修正必須です。

原則として、見つけた問題は修正してください。レビューのみの場合（書き込みツールがない批判的レビューのサブエージェントである場合、または修正を投稿者が行う場合）は、評価した指摘を報告します。自己レビューには投稿者の思い込みが引き継がれます。新鮮な視点で確認するか、新しいコンテキストでエージェントを使ってください（「スキルとカスタムエージェント」を参照）。

忘れないでください。少ないほど効果的です。スキルは簡潔でなければなりません！迷ったら、スキルの内容を TLDR 形式で記述してください。