skill-evaluation

スキルの評価

軸1、3、4の語彙やテスト（先頭の語、完了基準、コンテキストポインター、削除テスト、失敗モードの定義）が必要な場合は、これらの軸を採点する前に references/mechanics.md を読んでください。

出典

• Claude Code の構築から学んだこと：スキルの活用方法 — Anthropic、2026年6月
• 「The Missing Manual: How to Write Great Skills」— Matt Pocock、AI Engineer World's Fair 2026（動画）、および彼の writing-great-skills スキル

パラメーター

パラメーター	説明	デフォルト
target	評価するスキルディレクトリまたは SKILL.md のパス	ユーザーに確認
output	スコアカードの出力先パス	<target>/EVALUATION.md
compare	横並びで比較する任意の2つ目のスキル	なし

非対話モードでも実行できます。CI では、PR で変更されたスキルを target に指定し、scripts/score.py --fail-below 60 ... でゲートします。しきい値を下回ると、終了コードが 0 以外となり、チェックは失敗します。

評価基準

評価基準は18項目です。すべてのスキルを採点する基本基準が14項目、スキルのカテゴリに該当する場合のみ採点する条件付き基準が4項目です。該当しない場合は N/A とし、加重平均の分子と分母の両方からその基準を除外します。各評価は0～100点で、ファイル、セクション、または行を引用した根拠を示します。

軸1 — トリガー（呼び出し）

#	基準	重み	主な質問
1	呼び出し方法の設計	2x	モデルによる呼び出しか、ユーザーによる呼び出しかは、意図的に選ばれ、目的に合っていますか？ モデルによる呼び出しでは コンテキスト負荷 が発生します（説明文は毎ターン読み込まれます）。ユーザーによる呼び出しでは 認知負荷 が発生します（人間がインデックスの役割を担います）。手動でしか実行されないスキルは、ユーザーによる呼び出しにすべきです。
2	説明文の品質	2x	モデルによる呼び出しの場合：先頭の語が明確で、分岐ごとにトリガーが1つあり（同じ分岐の言い換えは重複です）、本文と重複する説明がありません。ユーザーによる呼び出し（disable-model-invocation: true）の場合：人間向けの一文で、トリガーの一覧がありません。実際に使用する呼び出し方式に照らして採点してください。トリガー句がないことを理由に、ユーザーによる呼び出しのスキルを減点してはいけません。

軸2 — 構成

#	基準	重み	主な質問
3	手順と参照情報の明確な区別	1x	スキルは、順序に従う手順と必要に応じて参照する情報を区別していますか？ 参照情報のみのスキルも、手順のみのスキルも、どちらも有効です。両者の配分ではなく、明確さを評価してください。関連情報（定義、ルール、注意事項など）は、1つの見出しの下にまとめられていますか？
4	分岐に応じた情報開示とポインター	2x	すべての分岐で必要な情報は本文中にあり、一部の分岐でのみ必要な情報はコンテキストポインターの先にありますか？ 各ポインターの文言には、「X が必要な場合は Y を読む」のように、参照するタイミングが示されていますか？ 必須情報へのポインターの文言が曖昧だと、ばらつきの問題が生じます。
5	簡潔さ（冗長さがないこと）	2x	SKILL.md は簡潔ですか。上限は500行未満で、短いほど望ましく、各行がコンテキストコストに見合う価値を持っていますか？
6	一貫性のある対象範囲	1x	対象範囲を広げすぎず、1つのことに集中し、ほかのスキルと連携できていますか？

Axis 3 — 誘導

#	評価基準	重み	主な問い
7	先導する言葉	2x	スキルでは、「垂直スライス」「厳密」「赤」のような、簡潔で優先度の高い用語を使って行動の基準を示し、一貫して繰り返していますか？冗長な説明を短い表現にまとめられる箇所はありますか？
8	完了基準と下調べ	2x	手順のあるスキルでは、各手順の最後に、確認可能で漏れのない完了基準が設けられていますか？曖昧な基準は、早すぎる完了を招きます。純粋なリファレンスのスキルでは、リファレンス自体に漏れのない基準（「すべてのルールが適用されている」など）がありますか？どちらにも該当しない場合は、N/A とします。
9	注意点のセクション	2x	失敗しやすい箇所、エッジケース、陥りやすい罠を明示的に取り上げていますか？
10	専門知識に基づく内容	2x	内容は、実際に観察された失敗やプロジェクトの事実に基づいていますか？それとも一般的な「ベストプラクティス」ですか？
11	過度な誘導を避けているか	1x	過剰に規定せず、適応の余地を残していますか？宣言より手順、選択肢の一覧よりデフォルトを優先していますか？

Axis 4 — 削減

#	評価基準	重み	主な問い
12	不要な記述（削除テスト）	2x	一文ずつ削除テストを行います。文を削除しても行動が変わらない場合、それは不要な記述です。モデルがデフォルトで行うことの言い換えも含みます。候補となる箇所の行番号を示してください。
13	信頼できる唯一の情報源	1x	それぞれの意味が、ちょうど一か所に記載されていますか？SKILL.md と references/ の間の重複も該当します。
14	関連性と蓄積	1x	古くなった行、積み重なった記述、スキルの動作に影響しなくなった内容はありませんか？

条件付き評価基準

スキルのカテゴリ（references/categories.md を参照）に基づいて、評価基準が該当する場合のみ採点してください。該当しない場合は N/A とし、加重平均から完全に除外します。

#	評価基準	重み	該当するカテゴリ
15	セットアップフロー	1x	library-and-api-reference、data-fetching-and-analysis、ci-cd-and-deployment、infrastructure-operations
16	メモリの仕組み	1x	business-process-automation、data-fetching-and-analysis、runbooks
17	スクリプトとライブラリ	1x	product-verification、code-scaffolding-and-templates、code-quality-and-review、data-fetching-and-analysis、infrastructure-operations
18	オンデマンドフック	1x	code-quality-and-review、ci-cd-and-deployment

いずれの方向にも、判断に基づいてこの表を適用してください。これらのカテゴリ以外のスキルでも、明らかに評価基準を適用するメリットがある場合（例：ヘルパースクリプトが明らかに必要な、product-verification 以外のスキル）は採点してください。また、該当するカテゴリ内でも、そのパターンがスキルの形式に合わない場合（例：code-quality-and-review に分類された純粋なリファレンス形式の用語スキルには、フックで適用すべきものがない）は N/A としてください。いずれの場合も、評価表で例外の理由を説明してください。

総合スコア

overall = sum(score × weight) / sum(weight)

N/A の評価基準は、どちらの合計からも除外します。0 点として採点したり、重みの計算に含めたりしてはいけません。

採点ガイド

スコア	意味
0	まったく含まれていない
1–25	最小限の取り組みで、評価基準にほとんど対応していない
26–50	一部対応しているが、重大な不足がある
51–75	十分に実装されているが、改善の余地がある
76–90	強力に実装されており、軽微な不足のみ
91–100	模範的。他の人の参考例として活用できる

評価スケール

評価	範囲	意味
A	80–100	本番品質のリファレンススキル
B	60–79	優れたスキル。軽微な改善が必要
C	40–59	機能するが、重大な不足がある
D	20–39	大幅な作り直しが必要
F	0–19	骨組みのみで、本番利用に適していない

ワークフロー

1. 対象のスキルを読む — SKILL.md、そのフロントマター（ disable-model-invocation の有無を確認）、およびスキルディレクトリ内のすべてのファイルを読みます。

2. references/mechanics.md を読む — 語彙と、Axes 1、3、 および 4 が依存するテストを確認します。効果的なコンテキストポインターの表現についても確認します。

3. 分類する — references/categories.md とその決定木を使って カテゴリを割り当てます。適用される条件付き基準はカテゴリによって決まります。

4. 該当するすべての基準を採点する — 根拠を引用するか、採点しない：根拠に特定の証拠（ファイル、セクション、行）が引用されている場合に限り、その基準を採点します。引用がなければ採点しません。条件付き基準表、または独自の判断で該当しないとした基準には N/A を付けます。該当するすべての基準にスコアと引用があり、すべての N/A に理由があれば完了です。

5. トリガー評価を実施する — スキルの説明によって実際に呼び出しが発生するかを検証します。詳しい手順については、以下の トリガー評価 セクションを参照してください。ユーザー呼び出し型スキル（disable-model-invocation: true）は、説明をテストできないため、この手順を省略します。

6. 失敗モードを診断する — 以下の表にあるすべてのモードをスキルと照らし合わせて確認し、引用（file:line）を付けるか、該当しないと判断すれば完了です。

7. ボーナスパターンを評価する — v1 から引き継いだ 4 項目に、5 つ目を加えます。

   ボーナス項目	該当する場合	確認する内容
   検証ループ	スキルが出力を生成する、または状態を変更する	最終化の前にエージェントが自己確認するよう指示している
   出力テンプレート	スキルが構造化された出力を生成する	想定される形式の具体的なテンプレートや例が含まれている
   宣言より手順	スキルが手法を教える	特定のケースで何を出力するかではなく、問題への取り組み方を教えている
   メニューよりデフォルト	スキルがツールやアプローチの選択肢を提示する	明確なデフォルトを選び、代替案には簡潔に触れている
   追跡可能な誘導	スキルが誘導的な語句を使う	その語句が明確に特徴的で、スキルが実際に使われたかを確認するため、ユーザーがエージェントの推論トレースを検索できる

   各項目を「あり」「なし」「該当なし」で報告します。

8. 加重スコアを計算する — scripts/score.py を実行し、各基準につき criterion:score:weight の組を 1 つ指定します（除外する場合はスコアを NA にします）。スクリプトが合計値、総合スコア、評価を出力します。この計算を手作業で行わないでください。

9. スコアカードを出力パスに書き込む — まず references/output-template.md を読みます（compare が設定されている場合に使う比較モードのテンプレートも含まれています）。その後、指定された構成だけを正確に出力します。

トリガー評価

スキルの説明によって、必要なときにモデルがそのスキルを呼び出し、不要なときには呼び出さないかを検証します。これは合否判定ではありません。スコアカードに反映し、失敗モードの診断に役立てるための観察データを生成します。

実施する場合

• モデル呼び出し型スキルのみ。ユーザー呼び出し型スキル（disable-model-invocation: true）にはテスト対象となる説明がないため、省略して該当なしとします。

プロンプトの生成

スキルの説明、対象範囲、注意点をもとに、10 個のプロンプトを生成します。

• 呼び出すべきプロンプト 5 個 — スキルが明示する対象範囲に明確に該当する、現実的なユーザーリクエストを作成します。表現に変化をつけます。スキルで使われる用語を使うものもあれば、同じニーズを素朴な表現や間接的な表現で述べるものも含めます。
• 呼び出すべきでないプロンプト 5 個 — 対象範囲に近いものの、明確に範囲外のリクエストを作成します（例：関連する別のスキルの領域、説明で明示的に除外されているタスク、スキルなしでもモデルが対応できる一般的な依頼）。

それぞれのプロンプトは、実際のユーザーが入力しそうな文章にします。スキルに関するメタ的な表現やヒントは含めないでください。

サブエージェントの実行

各プロンプトを、対象スキルを利用できる独立したサブエージェントセッションで実行します。サブエージェントには、システムコンテキストに追加の指示が1つだけ追加されます。

At the end of your response, output exactly one line in this format:
SKILLS_USED: <comma-separated list of skill names you loaded during this task, or "none">

この指示は汎用的なもので、テスト対象のスキル名を挙げたり、何を起動すべきか示唆したりしません。サブエージェントは通常どおり動作し、プロンプトだけに基づいてスキルを読み込むかどうかを判断します。

検出

各サブエージェントの応答から SKILLS_USED: の行を解析します。各プロンプトについて、次の内容を記録します。

フィールド	値
プロンプト	テストプロンプトのテキスト
期待値	should-trigger / should-not-trigger
起動	yes / no（対象スキル名がリストに含まれていたか）
その他のスキル	起動したその他のスキル

報告内容

合否の判断はせず、実測値を報告します。

• 起動すべき場合の起動率 — 起動した数 X/5
• 起動すべきでない場合の誤起動率 — 起動した数 X/5（低いほど望ましい）
• 確認されたその他のスキル — 同じプロンプトで起動した関連スキル

これらの数値は、基準 #1（呼び出し設計）と #2（説明の品質）を実証的な根拠で評価するために使われます。また、過剰な起動や説明の弱さなど、失敗の兆候が明らかになることもあります。

実施上の注意

• 評価環境でサブエージェントを起動できない場合（エージェントにアクセスできない CI など）は、起動テストを省略し、スコアカードに「起動テスト：省略（エージェントにアクセス不可）」と記載します。
• 観察目的であり合否判定には使わないため、プロンプトごとに1回の試行で構いません。結果が不明確な場合にのみ、複数回試行します。
• スキルの作成者が回帰テストに再利用できるよう、プロンプトをスコアカードの出力に含めます。

失敗モードの診断

失敗モードを挙げ、根拠を示し、防止策を提示します。各モードの防止策は references/mechanics.md §5 で一度だけ定義されています。一般的な「主な改善点」リストの代わりに、そこから防止策を提示してください。

モード	確認すべき根拠
早すぎる完了	今後の手順が残っているのに、完了条件が曖昧
誘導の弱さ	指示は存在するが、エージェントが確実には従わない
重複	SKILL.md と references/ の間など、同じ意味が2か所以上にある
堆積	古い層、古くなった参照、機能しなくなった指示
冗長化	重複や堆積がなくても長い
効果のない指示	モデルのデフォルトの動作を変えない行
手順の埋没	インライン参照が重く、手順が埋もれている

表の後に 優先度順のアクション セクションを作成します。検出した失敗モードから導き出される、最も影響の大きいアクションを3～5件挙げ、それぞれ根拠を示してください。

注：コンテキストの過負荷（1つの環境で、モデルが呼び出したスキルが多すぎて注意を奪い合う状態）は、ポートフォリオ全体の問題であり、単一スキルの評価対象外です。特に目立つ場合は、説明によるコンテキスト負荷を記録してください。ポートフォリオの評価には含めません。

注意点

• ごく小さなスキル（約50行未満）ではスコアカードに N/A が多くなります。該当する項目を評価してください。簡潔で的を射た小さなスキルなら、少ない評価項目でもグレード A に到達できます。
• 自己評価の偏り：評価対象のスキルをあなた（またはこのセッション）が作成した場合は、削除テストを特に厳しく適用してください。自分の記述を残したくなるものです。
• 新たに書き直したスキルでも、重複は残ります。堆積は時間がたたないと見えてきませんが、重複は初日から持ち込まれる可能性があります。新しいスキルにも、必ず整理の観点から評価してください。

品質チェックリスト

最終提出前の確認です。各項目では、新たな作業を加えるのではなく、記載された手順の完了を再確認します。

• cite-or-cut をすべての箇所で適用した（手順4）
• N/A の理由をすべて説明した（手順4）
• 起動テストを実施した、または理由を添えて省略した（手順5）
• すべての失敗モードについて根拠を示した、または該当しないと判断した（手順6）
• 5つのボーナスパターンを評価した（手順7）
• 手作業ではなく scripts/score.py でスコアを算出した（手順8）