rate-skill

Rate Skill

概要

1 つの SKILL.md を採点し、文字評価、カテゴリ別の加重スコア、名前付きの強み、貼り付けてすぐ使える修正案付きの優先度順の指摘事項、修正後の予測評価を返します。記憶ではなく、以下のルーブリックの文面に基づいて採点します。参照元は references/SOURCES.md です。

ナビゲーション

読み込むもの	場合
references/EXAMPLES.md	説明、フロントマター、検証用の補助情報の ✅/❌ ペア、完全なレポート例、廃止されたルール
references/SOURCES.md	ユーザーがルールに異議を唱え、仕様を引用する必要がある場合

ワークフロー

1. パスを解決します。ディレクトリが指定された場合は、その中の SKILL.md を対象にします。何も指定されていない場合は、「どの SKILL.md を採点しますか？」と一度だけ尋ねます。
2. ファイル全体を読みます。フロントマターと本文を分けて解析します。本文の行は、閉じる --- の後のすべて（空行を含みます。直後の空行も数えます）です。これは generate-skill/scripts/measure.py が報告する数値で、本文のトークン数は chars / 4 です。
3. 種類を判定します。generate-skill が使用する同じ 5 種類から選ぶため、生成されたスキルは、その生成元となったプロファイルに照らして採点します。2 つのプロファイルが当てはまる場合（reference と technical、methodology と auditing、automation と technical）、本文で既に指定されている必須セクションに合致する方を選びます。見出し名を理由に減点するプロファイルは決して選ばないでください。フェーズのないターンごとの行動スキルは、ターンの順序を示すセクションがあれば「Workflow (phased)」を満たします。レポートには種類と、同点時にどちらを選んだかを記載します。
4. Eval set check に照らして、評価セットを確認します（references/ または旧式の reference/ にある EVAL.md、または evals/evals.json）。ない場合は恒常的な P1 です。
5. 各カテゴリを 0～100 点で採点し、python3 <generate-skill>/scripts/measure.py score <7 scores in rubric order> を実行して加重表と文字評価を取得します。P0 と P1 を同じ方法で適用し、修正後の評価を予測します。
6. Output Format の形式でレポートを出力します。

ルーブリック（重みの合計は 100）

#	カテゴリ	重み
1	説明の品質	25
2	フロントマターの妥当性	20
3	長さと段階的な情報開示	15
4	種類に適した構成	15
5	例	10
6	簡潔さ／コンテキストの効率	10
7	アンチパターンと調整	5

90～100 は A、80～89 は B、70～79 は C、60～69 は D、60 未満は F です。B は本番環境で使用できる品質であり、失敗寸前という意味ではありません。

減点幅は、1 件の違反なら挽回でき、繰り返される違反は挽回できないように設定されています。−15 は 4 件でカテゴリの最低点、−20 は 3 件で最低点に達し、−10 はスキルが複数許容できる軽微な問題に適用されます。上限（40／50／70／80）は、その不備だけで到達可能な最高点を定めます。

1. 説明の品質（25）

満点には、次の 5 項目すべてが必要です。

• エージェントに向けた三人称の命令形 — 公式の表現は「Use this skill when…」です。標準表現の「Use this skill whenever the user wants to…」も同等です。一人称（「I'll help you…」）の場合は 40 点が上限です。
• 受動的ではなく、指示的であること。 「Use when X」のような単独の表現は 70 点が上限です。ALL-CAPS による強調を、より強い指示だと解釈してはいけません。§7 で減点されます。また、指示形そのものが既に効果をもたらします。
• 最初の約 50 文字以内に特徴的なトリガー語があること。 スキルが 15～25 個以上インストールされると、一覧表示ではその先が省略されるためです。
• ユーザーが使う具体的なトリガーが 3 つ以上あること。 引用したフレーズ、または列挙した動詞を使います。間接的な依頼に対する対象範囲の説明（「X を明示的に言及していない場合でも」など）は評価対象に含めます。これは公式にも推奨されています。
• 隣接するスキルがある場合は、対象外の範囲を明示すること（「このスキルを次の用途には使用しないでください」）。衝突しやすい領域でのみ必須です。

上限：1024 文字超 → 50 点（仕様上の上限）。曖昧なトリガー（「文書を支援する」「タスクに使用する」）→ 50 点。評価セットで検証の見落としが記録されている場合（ファイル自体に記録された実行で、トリガーすべきクエリのスコアが 0.5 以下）、この項目を −5 点し、クエリ名を含む P2 を付けます。文章がすべての基準を満たしていても、トリガーが不十分な場合があるためです。公式の分量の目安は「数文から短い段落」です。簡潔さについて指摘はしますが、上限を超えない限り文字数による減点はしません。YAML のスカラー形式は採点対象外です（「Retired rules」を参照）。

2. フロントマターの妥当性（20）

受け入れられるトップレベル項目：name、description、license、compatibility、when_to_use、argument-hint、arguments、disable-model-invocation、user-invocable、model、effort、agent、hooks、paths、shell、allowed-tools、metadata。

1つにつき−15：トップレベルのversion／author／tags（metadataに含める項目）；category（フィールドではありません）；metadata内にネストされたargument-hint（トップレベルに置く必要があります）；大文字、連続するハイフン、または予約語anthropic／claudeを含むname。−10：500文字の上限を超えるcompatibility。

3. 長さと段階的な開示（15）

• 本文が300行以下：満点。301～500行：300行を超える50行ごとに−10。500行では最低60点になります。
• 500行超：−30、さらにreferences/ディレクトリがない場合は追加で−20。上限を超え、開示もない場合が最悪のケースであり、そのケースのスコアは上限以下のどのケースよりも低くなければなりません。上限によってスコアが救済されることはありません。
• 本文が約5,000トークン（約20k文字）を超える場合、500行未満でも上限超過です。公式の制約は行数とトークン数の両方に適用されるため、コードが多く密度の高い本文は行数制限を満たしていても、トークン数制限を超えることがあります。
• 参照ファイルが2階層より深くネストされている場合：−15。Claudeはファイルの先頭100行を読み込むため、内容を見落とします。
• 単数形のreference/と複数形の使い分け：スタイル上の注意点であり、減点はありません。仕様書では複数形が明記されていますが、ディレクトリ名を検証するものはありません。新しいディレクトリでは複数形を推奨しますが、名前の変更を強制しないでください。

4. 種類に適した構成（15）

generate-skillが出力するものと同一の共通セクション仕様です。

種類	目的	必須セクション	任意
methodology	複数ステップのワークフローを徹底します	Overview、Workflow（フェーズ別）、Examples、Gotchas	Quality Signals / Anti-Patterns
technical	API、フォーマット、またはツールを扱います	Overview、Quick Start / Setup、Quick ReferenceまたはAPI surface、Examples、Gotchas	Troubleshooting
auditing	成果物を評価または検査します	Overview、Workflow、Rubric、Output Format、Examples、Gotchas	—
reference	スキーマ、規約、参照用テーブル	Overview、Navigation（読み込み条件のテーブル）、Gotchas	Core Concepts
automation	スクリプトまたは外部コマンドを扱います	Overview、Command Surface、Sample Invocation、Failure Modes、Gotchas	Troubleshooting

• 必須セクションが欠けている場合：セクションごとに−20。Gotchasはすべての種類で必須です。「多くのスキルで最も価値の高い内容は、落とし穴の一覧です。」
• 具体的な内容が何もない## Integrationセクション：−10。
• 指示パターンとの適合性。 公式パターンは、落とし穴、出力形式のテンプレート、チェックリスト、検証ループ、計画・検証・実行、同梱スクリプトの6つです。適合性を評価してください。スキルの目的から明らかに必要なパターンがない場合（破壊的なバッチ処理ワークフローに計画・検証・実行のステップがない場合など）は−10、適合しないパターンを無理に組み込んでいる場合も−10。
• 作成する成果物の長さ：−10。 スキルの出力がエージェントの作成するファイルであり、テンプレートで長さの範囲が定められていない場合です。作成する成果物は何も指定しないと長くなりがちです。テンプレートには「長さはタスクに合わせ、不要なセクションや冗長な要約は含めない」のような指示が必要です。チャットメッセージを引き継ぎ時にそのままディスクへ書き込む場合も対象です。エージェントが作成するスクリプト（テープ、設定ファイルなど）も、実行時の内容がその長さになるため対象です。必要に応じて読み込まれる参照ファイルに含まれるテンプレートの場合は−5であり、−10ではありません。
• ## Verification Checklistは、どの種類でも仕様上のセクションではありません。 欠落を減点せず、存在しても加点しないでください。内容は§7に従って評価してください。チェックリストは公式パターンのままですが、自己再確認の内容だけが減点対象です。

5. 例（10）

• 具体的なペア（望ましい例とアンチパターン）を1つ以上示す：基準点は70点。望ましい例を先に示す：+10点。さらにファイルの最後も望ましい例で締める：+5点（直近性）。✅/❌の絵文字、または ## Anti-Pattern: ヘッダーの文章：+15点。
• references/EXAMPLES.md にある例は、ポインターで参照されていれば満点としてカウントします。 これは段階的開示であり、省略ではありません。このカテゴリを採点する前にファイルを読んでください。§6では、両方の場所に残すことを減点します。
• 状況が3つ未満、または3つ以上あってもすべて同じ状況を扱っている場合は、上限を80点とします。ブロックやペアではなく、状況の数を数えてください。1つのシナリオに対する✅/❌のペアが2つあっても、状況は1つです。公式ガイダンスでは、エージェントが意図しない規則性をパターンマッチしないよう、関連性があり、十分に多様な状況を3～5つ示すことを推奨しています。ペアになっている一連の例の中に、❌を伴わない✅が1つある場合：−5点。「望ましい例で締める」とは、ファイル内の最後の例が望ましい例であることを意味します。例以外のセクション（Retired rules、Notes）が後に続いても問題ありません。
• <Good>／<Bad> XML タグ：−10点 — 調査対象の主要スキル8件で使用例はありません。これはラベルを対象とした減点です。構造上の区切りとしての <example>／<examples> は公式に推奨されており、問題ありません。
• 具体的なコードがなく、すべて抽象的な説明の場合は、上限を40点とします。

6. 簡潔さ／コンテキストの効率（10）

すべての指示に公式の削減テストを適用してください：「これがなければ、エージェントはこの指示を誤るか？」 いいえなら、冗長です。

個別の該当箇所ごとに−10点、最低40点 — 同じルールをN回コピーしても、該当箇所は1つです。SKILL.md内の言い換えも、SKILL.mdからreferencesへの重複も同様に扱います。Gotchasを症状別に引けるトラブルシューティング索引は、異なる検索方法であり、重複ではありません。ある注意点が、手順にはない症状を補うためにワークフローの手順を意図的に言い換える場合も、重複ではありません。段落で一般的なプログラミング知識を言い換えること、先行するルールより長い「これが重要な理由」の説明、ワークフロー前の冗長な導入、同じものに対する用語の不統一、デフォルトを選ぶべき場面での選択肢の羅列、手順として一般化できる場面での個別事例の出力、SKILL.mdとreferences/ファイル間での内容の重複（generate-skillとrate-skillが宣言により共有するセクション仕様のような、2つのスキルが共有する表は、意図された共有であり重複ではありません）、Claude Codeハーネスが毎セッションすでに挿入するテキスト（モデルが同じルールの異なる表現を調整することになるため。挿入されるブロックの最新リストは references/EXAMPLES.md § Harness-injected text を参照）。

7. アンチパターンと調整（5）

該当箇所ごとに−20点。このカテゴリの配点は5点なので、スコアへの影響はわずかです — 指摘事項そのものが成果物です。 該当箇所ごとにP1以上で1件ずつ報告してください。

作成

• 理由を示さず、すべて大文字の「IRON LAW」として強調すること。どちらの情報源でも推奨されていません。agentskills.ioでは、硬直した指示よりも「XをするとYが起きやすいため、Xをしてください」が望ましいとされています。platform.claude.comでは「強い言葉遣いを控え、より自然なプロンプトを使う」ことが推奨されています。

• 無関係な作業をまとめた巨大なスキルの範囲 — 1つのスキルにつき1つの作業です。SkillsBenchでは、3モジュール以下のスキルが、より大規模なものを上回ることが示されています。

• スキルディレクトリ内の不要なドキュメント（README.md、INSTALLATION.md、QUICK_REFERENCE.md、CHANGELOG.md）。

• Windows形式のバックスラッシュ付きパス、根拠が文書化されていない謎の定数、「2025年8月より前の場合は…」のように古くなる期間限定の注記を「old patterns」セクション外に置くこと。同じく古くなるものでも減点せず、修正を推奨する例：生成されたテンプレートに出典時点を記す（エージェントがコピーするYAMLブロック内に # verified 2026-09-02 と記載する）。本文中で生成時点に依存する表現を繰り返す（「current models」を何度も使うのではなく、世代を一度だけ記し、以降は「the model」とする）。削除予定のスキルへの参照、モデルのティア間のコスト比較、ハーネスのプロンプトテキストの逐語的な引用。

• 調整を誤った制御。 変更に対する脆弱さに合わせて具体性を調整してください。複数の方法が有効な場合は自由度を持たせ、操作が壊れやすい場合や順序を守る必要がある場合は明確に指示します。さまざまな方法が許容される作業に硬直した指示を出すことも、壊れやすい作業を曖昧に指示することも減点対象です。指示を明確にすること自体は欠陥ではありません。セクションごとに調整してください。 エージェントへの過剰な指示 — モデルがすでに実行する動作を言い直すことで、品質向上につながらないまま指示が重複し、トークンを消費します。

• 検証用の足場 — 外部の参照先がない一般的な再確認を減点します。「回答を再確認する」「応答前に再検証する」「重要なタスクでは最終検証ステップを追加する」などが該当します。修正方法は言い換えではなく削除です。次の3つは該当せず、問題ありません。 外部の状態に照らした確認（「テストスイートを実行する」「ファイルを解析できることを確認する」「スキーマに照らして検証する」など）、新しいコンテキストを持つエージェントが別のエージェントの出力を評価するライター・ベリファイアのパターン、進捗報告の前に行う証拠監査（「ツールの結果で示せる作業だけを報告する」）。後者2つは単に許容されるだけではなく、長時間実行される作業で推奨されています（プラットフォーム 5.1 のガイダンスでは暫定的なものとして記載）。問題なのは、エージェントが自分の出力を読み直すだけで、照合する外部の対象が何もないことです。

• 推論の反響（「考えを示す」「回答で推論を説明する」）。reasoning_extraction の拒否を引き起こす可能性があるため、必ず P0 も出力してください。 文体上の問題ではなく、重大な障害モードです。

• 「考えるな」／「推論するな」 — 内部 XML タグが目に見える出力に漏れる可能性を高めます。削除してください。タグを名指しするルールより、何も言わないほうが効果的です。

• ナレーション抑制の指示（「すべての所見を最終回答まで保留する」「ナレーションしない」「途中経過を更新しない」）。長いツールチェーンの実行中、モデルはすでに状況説明が不足しがちです。こうした指示があると、ユーザーは何も知らされないまま待つことになります。まず削除してください。スキルが特定の更新を求めるなら、そのタイミングを明記します（「ディスパッチの前に対象範囲を報告する」など）。最終メッセージの形式を定めるルール（チャットは1行で、ファイルが成果物など）はこれに該当しません。

• 書式設定の禁止ルール（「箇条書きを使わない」「見出しを付けない」「太字を使わない」）。書式設定を過剰に行うモデルを想定したルールですが、モデルは書式設定が不足しがちなため、読者が求める構造まで取り除いてしまいます。書式設定が適切な場合のルールに置き換えてください。

• 範囲が明確でない、または進行を妨げる委任 — どのような状況でサブエージェントを使うべきか、何人まで使うかを示していない指示や、オーケストレーターに各エージェントの作業を順番に待たせる指示です。範囲を定めない委任はコストを増大させ、進行を妨げる委任は所要時間を増大させます。独立して作業できるエージェントは1つのメッセージでディスパッチし、リードは作業を続けます。

• 範囲の狭い作業に対する範囲の拡大 — モデルは依頼されていない手順を追加するため、単一の作業を行うスキルでは、作業をどこで終えるかを示す必要があります。コードを生成するスキルでは、同じルールがコードにも適用されます。依頼されていない周辺動作の修正はフォローアップとして報告し、一時的なチェックをコミット対象のテストファイルにしないでください。

評価セットの確認

評価対象の各スキルには、評価セットを必ず用意します。未用意 → 常にP1（パッチにスターターセットを含めます。減点にも加点にもなりません）。用意されているが、提供されるdescriptionに検証結果の行がない → これもP1です。最新のResults行をdescriptionの最終編集と比較します（フロントマターにはgit log -Lを使うか、CHANGELOGを確認します）。検証スコアのないバリアントは、ループ自体のルールにより選択されません。用意されているが、一度も実行されていない、またはプロトコルを逆にして実行されている（trainを一度も測定していない、iterationやselectionをvalidationクエリに基づいて行っている）場合もP1です。用意され、検証済みのセットにおけるその他の不足（クエリ数、分割比率、機能していない近傍スキル）はP2です。disable-model-invocation: trueのスキルは、トリガー率の測定対象外です。そのセットでは、自然言語での言い回しでスキルが呼び出されないことと、呼び出し後にそのモードが維持されることを確認します。セットがある場合は、公式のループに照らして検証します。

• 約20件のクエリを用意し、各方向に8～10件ずつ割り当てます。近傍スキルは、should-notのテストケースとして最適です。
• trainとvalidationを約60/40に分割し、両方の半分で構成比を揃え、iteration間で固定します。
• プロトコルを明記します。各クエリを新しいセッションで約3回実行します。トリガー率は、スキルが呼び出された実行の割合です。should-triggerはしきい値を上回れば合格、should-notは下回れば合格です（デフォルトは0.5）。
• 選択ルールを明記します。最も高いvalidationスコアを獲得したものを選びます。最後のiterationより前のiterationが勝つこともあります。

注意（公式）：エージェントは、単独では対応しきれないタスクでもスキルを参照するため、単純なクエリ（「このPDFを読んで」など）でトリガー率が低くても、descriptionの欠陥とは限りません。

出力形式

レポートの長さは、スキルに必要な分だけにします。価値があるのは指摘事項なので、埋め草のセクションや、レポートの内容を繰り返す締めくくりの要約は不要です。

# Skill Rating: <skill-name>

**Detected type:** <methodology | technical | auditing | reference | automation>
**Overall grade:** <letter> (<weighted score>/100)
**Eval set:** <present + conforms | present, gaps: … | missing (P1)>

## Category scores

| Category | Score | Weight | Weighted |
|---|---|---|---|
| Description quality | nn | 25 | nn.n |
| Frontmatter validity | nn | 20 | nn.n |
| Length & disclosure  | nn | 15 | nn.n |
| Structure            | nn | 15 | nn.n |
| Examples             | nn | 10 | nn.n |
| Conciseness          | nn | 10 | nn.n |
| Anti-patterns/calib. | nn |  5 | nn.n |

## Strengths
- <concrete bullet — what the skill does well>

## Findings (prioritized)

### P0 — <title>
**Why:** <one-line rationale, cite category>
**Fix:**
\`\`\`<lang>
<concrete replacement text, not a description of one>
\`\`\`

### P1 — <title>
### P2 — <title>

## Estimated grade after P0+P1: <letter> (<projected score>/100)

<one-line commit-ready summary>

すべてのレポートに、少なくとも1つの長所を記載します。F評価のスキルであっても同様です。否定的な内容だけのレポートはユーザーに読まれなくなります。すべての指摘には、ユーザーがそのまま貼り付けられるパッチを添えます。「descriptionを改善してください」とだけ書いてはいけません。

例

descriptionの品質、フロントマターの整理、ドメイン検証と自己再チェック用の足場づくりを比較する✅/❌のペア、完全なレポートのサンプル、廃止されたルールについては、**references/EXAMPLES.md**を参照してください。

注意点

• 2つの情報源では、descriptionの強さに対する見解が異なります。 agentskills.ioは「強めにする側に倒す」としています。一方、platform.claude.comは、モデルがスキルを「過剰にトリガーするようになった可能性がある」ため、「攻めた表現は控える」よう述べています。両者は、網羅性と強さを区別すれば両立します。トリガーを増やし、対象範囲を明示する文言を加えると再現率が上がりますが、すべて大文字で書いても何も向上しません。網羅性は高く評価し、強い表現は低く評価してください。
• 一覧表示の上限は、仕様上の上限とは別です。 Claude Codeは、一覧表示のdescriptionとwhen_to_useの合計文字数を1,536文字に制限しています（skillListingMaxDescChars）。また、skillListingBudgetFractionのデフォルトはコンテキストの約1%です。どちらも§1の仕様上の1024文字制限とは異なります。
• トップレベルのtagsは何もしません。これを使うディスカバリーシステムはありません。削除せずにmetadata.tagsへ移動し、ユーザーの意図を保ってください。
• 拡張キーは有効ですが、移植性はありません。 argument-hint、hooks、paths、when_to_useはClaude Codeでは問題なく動作しますが、Anthropicのパッケージ検証ツール（quick_validate.py）では拒否され、ユニバーサル仕様にも含まれていません。これを減点対象にしないでください。スキルがanthropics/skillsを対象としている場合に限り、注意点として指摘してください。
• 構造検証ツールにはskills-ref validate <path>を推奨してください。 npx skills lintやnpx skills validateは決して推奨しないでください。vercel-labs/skillsには検証コマンドがありません。
• 否定表現の処理は不得意です。 公式ガイドでは「Claudeには、してはいけないことではなく、代わりに何をすべきかを伝えてください」とされています。これはarXiv 2503.22395でも裏付けられています。評価対象の本文に単独の「DO NOT X」がある場合は、「代わりにYをしてください」と組み合わせるよう推奨してください。
• 検証ルールはモデルごとに異なります。 §7に記載された3つの例外に照らして評価し、基準を厳しくしたり緩めたりする前に、現在のモデルのプロンプティングガイドを再確認してください。これまで、どのガイドもこの基準を変更しています。