grill-skill

Grill Skill

スキルの評価を設計するためにユーザーにインタビューし、リリースできる状態になるまで「実行 → 診断 → 改善」のループを回します。caliper が必要です（見つからない場合は pipx install caliper-eval）。コマンド、仕様のひな形、タスク作成ルールについては REFERENCE.md を参照してください。

評価では次の4つの問いに答え、インタビューでもそれぞれを取り上げます。

• 発動するか：エージェントは必要なときに限ってスキルを使うか？ activates: と発動プローブでテストします。修正箇所は description です。
• 機能するか：発動後、エージェントは作業を適切に遂行するか？ expect: / assert: でテストします。修正箇所は本文です。
• 効果があるか：スキルなしの場合と比べて、エージェントの性能は向上するか？ このスキルを取り除いた状態で宣言された近接スキル群を使う対照条件と比較してテストします。対照条件でもパスするタスクは修正が必要です。
• 維持できるか：編集後も良い状態を保てるか？ 新しいフル実行を毎回、ひとつ前の実行と比較してテストします。

入口

/grill-skill [path]：SKILL.md のパスは任意です。

• パスが指定されている場合：そのパスを使用します。
• パスが指定されていない場合：現在の作業ディレクトリで SKILL.md を探します。見つかった場合は続行前に確認し、見つからない場合は場所を尋ねます。

フェーズ 1 — 理解する

SKILL.md を読みます。その機能、発動する条件、実行が成功したと判断できる状態を要約します。読み取り内容をユーザーに確認してもらいます。確認されるまで続行しないでください。

フェーズ 2 — 評価モードを検出する

SKILL.md と同じ場所にある *.eval.yaml を探します（まず <dir-name>.eval.yaml を試します）。

• なし → 新規評価。あり → ギャップの補完。

質問は一度に1つずつ行い、回答を待ちます。すべてのタスクはユーザーの回答に基づいて作成し、インタビューが終わってから仕様を作成します。

新規評価

次の項目について、一度に1つずつ確認します。

1. 一般的な成功例：最もよくある成功例は何ですか？ エージェントは何を行い、何をもって成功と判断できますか？
2. エッジケース：そのままのエージェントではつまずく可能性のある、扱いが難しいものの有効な入力は何ですか？
3. 敵対的なケース：このスキルは何を拒否、または回避すべきですか？
4. 近接スキル：エージェントがこのスキルと取り違える可能性がある他のスキルは何ですか？ ユーザーがパスまたは Git リポジトリを指定できるものは、それぞれ skills: に宣言し、近接プローブを追加します。これは近接スキルに該当するプロンプトで、activates: [<neighbour>] を指定します。

無関係な作業を行うサイレンスプローブも必ず提案します。activates: [] を指定します。

それぞれの回答をタスクにします。タスクには、スキル名を出さない現実的な prompt、観察可能な expect、結果を確認できる場合は assert、そして実行タスクでは activates: を含めます。activates: には、このタスクで委譲するスキルがあればそのスキルも含め、スキル名を指定します。これにより、実行時に description の失敗と本文の失敗を見分けられます。ハーネスは単発実行です。エージェントの質問に答える人はいません。スキルが実行前に質問する場合、タスクでは最初のターンを評価し、expect: に質問を、assert: にまだ何も実行されていないことを指定します。提案する YAML を提示し、作成前に確認を取ります。

SKILL.md と同じ場所に、skills: [./SKILL.md] を記載した <dir-name>.eval.yaml という名前で仕様を書きます。engine: は指定しません。バックエンドとモデルは実行時に --model / --judge-model で選択するため、SKILL.md がデフォルト以外のエージェントを対象としている場合は、ユーザーに渡すフラグを伝えます。その後、仕様を SKILL.md と同じ場所に置いたまま、今すぐコミットするようユーザーに伝えます。

ギャップの補完

既存の仕様を読み、各タスクがどの問いに答えるかごとに分類して報告します。タスクがない問いを明示します。たとえば、activates: のない実行タスク、トリガープローブがない場合、決定的な assert: がない場合です。**何かを提案したり書いたりする前に、どの動作が不足しているか、または十分にテストされていないかを尋ねてください。**ユーザーから確認だけを依頼された場合も同様です。それぞれのギャップをタスクとして具体化し、提示したうえで、仕様に加える前に確認を取ります。

どのセットアップを測定するか

実行では、デフォルトでユーザー自身のカスタマイズ（ユーザースキル、プラグイン、ルール、設定、コネクター。バックエンドごとの例外については REFERENCE.md を参照）が読み込まれます。これは、「自分のエージェントで自分のスキルが機能するか」という問いに答えるものです。バックエンドやモデルを比較するとき、数値をこのマシンの外で共有・公開したり、他の人の実行結果と比較したりするとき、またはカスタマイズなしのエージェントを測定するときは、分離してください（--no-user-customizations、または仕様内の user_customizations: false）。セットアップはそれぞれ異なるため、そうしないと差分の一部はセットアップの違いによるものになります。ユーザー自身のスキルに対して --ablate を行う場合は、両方の実行で同じセットアップが読み込まれるため、分離は不要です。

どのモードで実行したか、何が読み込まれたかを必ずユーザーに伝えてください。レポートヘッダーの user customizations: 行を確認してください（この行がなければ分離されています）。また、caliper compare が提案する修正があれば、それも伝えてください。

フェーズ 3 — 初回実行

仕様を検証してから、k=1 で実行します（コマンドは REFERENCE.md を参照）。結果を提示してください。先に進む前に、タスクの失敗ではなく、ハーネスまたは設定のエラーを修正してください。実行が Not logged in で停止した場合は、エラーに表示されたログインコマンドを実行するか、ユーザーに確認してください。同意を得たら実行します（ブラウザーが開くので、ユーザーがログインを完了できます）。同意なしに実行してはいけません。hermes model は対話式の選択ツールなので、ユーザー自身のターミナルで実行するよう依頼してください。

フェーズ 4 — タスクでスキルの違いを測れるか確認する

誰かがスキルを編集する前に、タスクでスキルの有無を見分けられるか確認してください。比較対象は、そのスキルを取り除いた状態で宣言された近傍、つまりコントロールです。コントロール（--ablate <skill-name>、または mcp: サーバーの名前が同じ場合は skill:<skill-name>）と、完全な実行をどちらも k=3 で実行し、両者を caliper compare で比較してください。まず、スキルが有効化されたか確認します。完全な実行でスキルが一度も発動しなかった場合、両方の実行で同じエージェントを測定しているため、修正すべきなのはタスクではなく description です（フェーズ 5）。

• スキルは発動したが、コントロールのスコアが完全な実行とほぼ同じ：タスクにスキルは必要ありません。そのタスクを使ってスキルを反復改善しても、何も測定できません。ユーザーと一緒にタスクをより明確にしてください（より難しい入力や、スキルが追加する具体的なルールなど）。その後、両方を再実行します。
• 完全な実行が明らかに上回る：タスクはスキルを測定できています。このまま続けてください。

コントロールの結果パスを保持してください（caliper list <spec-name> で、どの実行がアブレーションされたか確認できます）。その実行にはスキルがインストールされていないため、SKILL.md を編集しても数値は変わりません。再実行するのではなく、その結果との差分を取り直してください。タスクまたは宣言されたスキルを変更した場合に限り、再実行してください。

フェーズ 5 — 診断して反復する

修正を提案する前に、失敗した各タスクを読み、修正すべき場所を伝えます。

シグナル	修正すべき場所
実行が 2 で終了する（バックエンドの設定ミス、モデルが利用不可、フックまたは MCP サーバーの失敗、あるいはすべての試行が使用不能）	環境またはタスクのフックであり、スキルではありません。修正して再実行します
⊘ の使用不能な試行（infra_error、timeout、judge_error）	スキルではありません。レート制限、認証、またはジャッジが原因です。修正して再実行します
cheat の結果	タスクです。回答が漏れています。タスクまたは sandbox: を強化します
アクティベーションに失敗：期待したスキルが発動しなかった	そのスキルの description
アクティベーションに失敗：予期しないスキルも発動した	追加のスキルの description、または 2 つのスキル間の重複
ユーザー自身のスキルが発動したためアクティベーションに失敗した（レポートヘッダーの skill:）	description だけが原因ではありません。そのスキルはユーザーの環境で実際に競合しています。description を明確化するか、実行を分離するか、ユーザーと決めます
アクティベーションは成功したが、スコアが低い	スキルの本文
ジャッジの推論から、expect: が曖昧だったことが分かる	タスクの採点です。基準を観察可能にするか、assert: を追加します
フル実行 ≈ コントロールで、フル実行ではスキルが発動した	タスクです（フェーズ 4 を参照）。一度も発動しなかった場合は、description です

次に、反復するか終了するかを尋ねます。

• 反復する：ユーザーが SKILL.md を編集した後、k=3 で再実行し、caliper compare で 2 回比較します。1 回目は前回のフル実行との比較（編集の効果が維持されたか）、2 回目は保持しているコントロールとの比較（引き続き価値があるか）です。スキルの性能が下がっても、コントロールを上回ることはあります。再度診断します。k=3 では 1 回の試行で 33 ポイント変動するため、予想外の勝敗は実際に判断する前に k≥5 で確認します。これを繰り返します。
• 完了：フル実行が実行タスクでコントロールを上回り、前回のフル実行に対しても効果を維持していることを確認します。その後、SKILL.md と .eval.yaml を一緒にコミットするようユーザーに伝えます。