skillify

Skillify — メタスキル

/cross-modal-review との関係： このスキルは手動で行う作業途中の 「セカンドオピニオン」ゲートです（1つのモデルがコミット前に成果物をレビューします）。一方、 以下のフェーズ 3 では gbrain eval cross-modal を使用します。3つの異なるプロバイダーの最先端モデルが、 テストによって動作が確定される前に、文書化された評価項目リストに基づいて採点と反復を行います。 アドホックなセカンドオピニオンには /cross-modal-review を使用し、機能をスキル化する際は ここでフェーズ 3 を使用してください。

契約

15個のチェックリスト項目（0 + 1–14。3b は項目 3 に含まれます）すべてに合格すると、機能は「適切にスキル化」されたことになります。gbrain skillify check は機械的な項目（1–11）を監査します。項目 0、3b、12、13、14 は手順上のゲートであり、エージェントが直接確認します。項目 3（クロスモーダル評価）は監査では情報提供のみを目的とし、gbrain skillify check の合否を左右しません。ただし、レシートがない、または古い場合はその旨が示され、ユーザーがゲートの状況を把握できます。

冪等性の保証： 同じスキルに対して、何度でも skillify を実行できます。実行のたびに、以下を行います。

1. 既存の成果物（SKILL.md、テスト、評価、コード、リゾルバーのエントリ）を検出します
2. 新しい要素（バグ報告、ユーザーフィードバック、新しい入力、品質上の不足）を特定します
3. ゼロから書き直すのではなく、既存のファイルを改善します
4. 正常に動作するものは維持し、壊れているものは修正します
5. チェックリストを再実行し、不合格の項目のみを変更します

デグレード禁止の原則： スキルを編集する場合、同じタスクと評価項目で、前回の反復におけるクロスモーダル評価以上のスコアを獲得する必要があります。後戻りはせず、前進のみです（フェーズ 3.5）。

チェックリスト

ほかのスキルやワークフローからこのチェックリストを参照する際は、skills/skillify/SKILL.md に照らし、項目番号（例：「skillify の項目 4–6 を実行」）を指定してください。 番号は固定されており、変更は追加のみです。

□ 0.  Eval contract      — skill declares goal + skill-specific dimensions + hard-fails (Phase 2.5)
□ 1.  SKILL.md           — skill file with frontmatter + contract + phases
□ 2.  Code               — deterministic script if applicable
□ 3.  Cross-modal eval   — 3 frontier models from 3 providers critique output vs the contract; informational in the audit
□ 3b. No-regression gate — new eval scores ≥ the previous iteration (forward only; Phase 3.5)
□ 4.  Unit tests         — cover every branch of deterministic logic
□ 5.  Integration tests  — exercise live endpoints
□ 6.  LLM evals          — quality/correctness cases for LLM-involving steps
□ 7.  Resolver trigger   — entry in skills/RESOLVER.md with real user trigger phrases
□ 8.  Resolver eval      — test that triggers route to this skill
□ 9.  Check-resolvable   — DRY + MECE audit, no orphans
□ 10. E2E test           — smoke test: trigger → side effect
□ 11. Brain filing       — if it writes pages, entry in brain/RESOLVER.md
□ 12. Scheduled-run observability — if the skill backs a cron/recurring job, runs route through minions so they are logged and inspectable (Phase 6)
□ 13. Scheduled-task re-run — if the skill backs a cron, an edit re-runs a representative task + evals it (Phase 3.5)
□ 14. Plugin membership   — record the skill in openclaw.plugin.json OR skills/plugin-exclusions.json (the membership test requires exactly one)

フェーズ 0：モードを判断する（新規作成か改善か）

最初に、モードを判断してください。

モード A：新規スキル（SKILL.md が存在しない）

確認事項：

• 2回以上呼び出されるものですか？（一度きりの作業はスキルではありません）
• ロジックが20行を超えていますか？（単純なヘルパーに完全なインフラストラクチャは不要です）
• ユーザーが実際に使いそうな、明確なトリガーフレーズがありますか？

いずれか1つでも「いいえ」なら、それはスキルではなくスクリプトです。ここで中止してください。スキャフォールドを作成したり、SKILL.md を書いたり、評価を実行したり、テストを書いたりしないでください。その理由をユーザーに伝え、次に進んでください。

スコープの確認（上限）：1つのスキルは1つの機能であり、1つのまとまったトリガーファミリーです。対象が、ユーザーが別々に呼び出す複数の異なる意図（「ビルドを実行する」／「デプロイをロールバックする」／「チームに通知する」は1つではなく3つの意図です）にまたがる場合、それらすべてをカバーする1つのスキルを作成しないでください。中止し、個別の skillify 対象に分割する案を提示したうえで、まずどれをスキル化するかユーザーに尋ねてください。

DRY/MECE の事前確認：スキャフォールドを作成する前に、skills/RESOLVER.md とスキルマニフェストを grep し、重複するトリガーフレーズや説明がほぼ同じものがないか確認してください。提案するトリガーが既存のスキルと競合する場合は、ほぼ同じスキルを新規作成するよりも、既存のスキルに統合することを優先してください。既存のスキルにトリガー、モード、またはフェーズを追加してマイナーバージョンを上げ、統合後の結果に対してこのチェックリストを実行してください。重複があるにもかかわらず別のスキルを作成する場合は、その違いを一文で新しい SKILL.md に記録してください。事前確認で見落とした点は、後段の gbrain check-resolvable（フェーズ 5）で検出します。

モード B：既存のスキルを改善する（SKILL.md が存在する場合）

これは冪等な処理です。すでに SKILL.md があるスキルに対して skillify を実行する場合、バグが見つかった場合、ユーザーからフィードバックや新しい入力があった場合、または品質チェックが求められた場合に実行します。

改善プロトコル：

1. 既存の成果物をすべて読みます：skills/<slug>/SKILL.md、スキルのスクリプト（SKILL.md が参照しているパス）、routing-eval.jsonl、test/<slug>.test.ts。
2. 差分を特定します。何が変わりましたか？
   • バグ修正：ユーザーから特定の不具合が報告されました。該当するバグを再現するテストを追加し、コードを修正して、再発防止のための厳格なルールを SKILL.md に追加します。
   • **新しい入力：**ユーザーから新しいコンテキストや要件が提示されました。SKILL.md を拡張し、コードを更新して、新しい動作を検証するテストを追加します。
   • **品質チェック：**特定のバグはなく、チェックリストを再実行するだけです。監査、クロスモーダル評価、ギャップの補完を行います。
3. 変更は必要最小限に適用します。既存のファイルを編集し、書き直さないでください。
4. リグレッションがないことを確認するため、既存のテストをすべて再実行します。
5. フロントマターのバージョンを更新します（バグ修正ではパッチ、新機能ではマイナー）。
6. リリース前に No-Regression Gate（Phase 3.5）を実行します。

バグ修正のテンプレート（スキルの SKILL.md に追加）：

## Bug: [Date] — [Short description]
- **What happened:** [Concrete failure]
- **Root cause:** [Why]
- **Fix:** [What changed]
- **Hard rule added:** [New constraint to prevent recurrence]
- **Tests added:** [List of new test cases]

Phase 1：監査

Feature: [name]
Code: [path]
Missing items: [check each of the 15]

Phase 2：SKILL.md とコードを作成する（項目 1〜2）

SKILL.md のフロントマターのテンプレート（コピー＆ペースト用）：

---
name: my-skill
version: 1.0.0
description: |
  One paragraph. What it does, when to use it.
triggers:
  - "trigger phrase users actually say"
  - "another real trigger"
tools:
  - exec
  - read
  - write
mutating: false  # true if it writes to brain/disk
---

本文には、Contract（保証する内容）、Phases（手順）、Output Format（生成する内容）を含める必要があります。

決定論的なコードは scripts/*.ts に抽出します。

Phase 2.5：評価コントラクト（項目 0）— 評価前に目標と評価基準を定義する

クロスモーダル評価の質は、何を評価するよう求めるかで決まります。一般的な評価軸では粗雑さを検出できますが、出力がこのスキル固有の目的を達成しているかどうかは見落とされます。すべてのスキルには、スキルの目的と、出力が優れているか失敗しているかを判断する方法を明示した評価コントラクトが必要です。

すべてのスキルで、フロントマターに評価コントラクトを宣言する

eval_contract:
  goal: |
    One or two sentences: what this skill is supposed to achieve, for whom, and what
    "excellent" looks like in the real world. Be concrete and skill-specific.
  dimensions:
    - "DIMENSION_NAME — the specific question this dimension answers for THIS skill"
    # 3-6 dimensions, tuned to the skill. Example for a per-subject news briefing skill:
    # - "FACTUAL_INTEGRITY — is every claim true and verifiable?"
    # - "SUBJECT_ANCHOR — is each item tied to something concretely THIS subject's?"
    # - "WHY_IT_MATTERS — is the relevance real and specific, not a templated lane label?"
    # - "CLICKWORTHY — would the reader actually want to open these links?"
  hard_fails:
    - "A failure mode that auto-zeroes the eval regardless of other scores."
    # e.g. "Any fabricated fact = automatic 1."

評価コントラクトの取得方法（優先順位順）

1. スキルから読み取ります。 フロントマターに eval_contract がすでに存在する場合（または本文に明確な Goal／Contract セクションがある場合）は、それを使います。冪等な実行では同じコントラクトを再利用し、各イテレーションのスコアを同じ条件で比較できるようにします。これにより、リグレッション防止ゲートが意味を持ちます。
2. コンテキストから推定します。 コントラクトが宣言されていない場合は、SKILL.md の本文（Contract／Output Format）、そのスキルを呼び出す定期タスクのプロンプト、最近のユーザーフィードバック（特に苦情。事実が誤っているという指摘があれば、FACTUAL_INTEGRITY をハードフェイルの評価軸として指定します）、代表的な出力の対象読者から、目標と評価軸を導きます。
3. 不明確な場合はユーザーに尋ねます。 目標や「優れている」と判断する基準が本当に曖昧で、自信を持って推定できない場合は、尋ねてから進めます。質問は簡潔に 1 つだけにします。リスクの高いスキル（出力が公開チャンネルに投稿されるもの、または他の人に読まれるもの）について、評価基準を推測してはいけません。誤った評価基準では、自信があるように見えても意味のないスコアになります。
4. 内容をスキルに書き戻します。 確定したら、スキルの eval_contract フロントマターにコントラクトを保存し、再利用およびバージョン管理できるようにします。コントラクトの編集もスキルの編集にあたるため、新しい評価基準で現在の出力が引き続き適切に評価されることを確認するため、再評価します。

評価にコントラクトを組み込む

コントラクトの目標を --task に、評価軸を --dimensions に渡して、gbrain eval cross-modal を実行します。これにより、汎用チェックリストではなく、スキルが明示する目的に照らして評価できます。タスク文にはハードフェイルの条件も記載してください。条件に該当した場合は評価者がスコアをゼロにします（「主張に捏造があれば、ほかの品質にかかわらず出力は失敗とする」など）。

Phase 3：クロスモーダル評価（項目 3）— 品質ゲート

テストより先にこれを行う理由

テストは動作を固定します。動作が平凡なら、テストによって平凡さまで固定されてしまいます。まずクロスモーダル評価で品質基準を満たしていることを確認してから、テストでその基準を確かなものにします。

ステップ 1：代表的な入力を選ぶ

スキルの文書化されたユースケースのうち、最も難しいものを試せる入力を選びます。 迷った場合は、SKILL.md の主なトリガー例、または直近 7 日間のメモリファイルにある、最も複雑な実際の入力を使用します。

ステップ 2：スキルを実行し、出力を記録する

代表的な入力に対してスキルを実行します。評価対象となるのは OUTPUT FILE です。

ステップ 3：評価ゲートを実行する

gbrain eval cross-modal \
  --task "The eval contract's goal, including its hard-fail conditions" \
  --dimensions "dim_one,dim_two,dim_three" \
  --output skills/<slug>/SKILL.md

このコマンドは、3 つの異なるプロバイダーのフロンティアモデルである 3 つのジャッジモデルを並列実行し、指定した評価軸（--dimensions を省略した場合の標準 5 項目）で OUTPUT を TASK と照らして採点し、~/.gbrain/.gbrain/eval-receipts/<slug>-<sha8>.json にレシートを書き込みます（sha-8 はレシートを現在の SKILL.md の内容に結び付けます。編集後に再実行すると新しいレシートが書き込まれるため、反復ごとにそれぞれのベースラインが残ります）。

ジャッジモデルは、各スロットについて次の順に解決されます。

スロット	1. フラグ	2. brain 設定キー	3. フォールバック
A	--slot-a-model <provider:model>	models.eval.cross_modal.slot_a	gbrain に同梱されているスロット A のデフォルト
B	--slot-b-model <provider:model>	models.eval.cross_modal.slot_b	gbrain に同梱されているスロット B のデフォルト
C	--slot-c-model <provider:model>	models.eval.cross_modal.slot_c	gbrain に同梱されているスロット C のデフォルト

brain の設定キーは、夜間品質プローブが読み取るものと同じです。一度固定すれば（gbrain config set models.eval.cross_modal.slot_a <provider:model>）、CLI とプローブのどちらで実行しても、同じパネルで評価できます。gbrain models には、プローブが解決するパネルが表示されます。同梱されているデフォルトは、3 つのプロバイダーの現行フロンティアモデル 3 つです。gbrain のリリースに応じて変更されるため、スキルに具体的な ID をコピーしないでください。デフォルトのプロバイダーにキーがないスロットは、設定済みのチャットモデルに置き換えられ（#4636）、実際に評価したモデルがレシートに記録されます。

これらは、異なるプロバイダーのフロンティアモデルでなければなりません。 単一プロバイダーのモデル系列や低コストモデルを使うと目的が損なわれます。異なるモデル系列は、相関の低い盲点を持つためです。モデル名は変わるため、実行時に有効なエイリアスを固定してください。長期的に守るべきなのは、フロンティアモデルのみ、かつプロバイダーを分けるというルールです。

合格基準（両方を満たす必要があります）：

1. 成功したモデルの各評価軸の平均が 7 以上。
2. いずれのモデルも、いずれかの評価軸で 5 未満を付けていないこと（下限）。

判定不能： 3 モデルのうち 2 モデル未満しか解析可能なスコアを返さなかった場合です。レシートは書き込まれます（フォレンジック用）が、ゲートの判定には使えません。終了コードは 2 です。CI ラッパーでは、これを「品質ゲート不合格」ではなく「正常に実行できなかった」として扱ってください。

ステップ 4：合格するまで繰り返す（最大 3 サイクル）

CYCLE 1:
  Eval → scores + top 10 improvements
  IF pass: → done, write tests
  ELSE:
    Apply top 10 improvements to the actual file
    Log: which improvements applied, what changed

CYCLE 2:
  Re-eval the FIXED output (same 3 models, same dimensions)
  Compare: before/after scores per dimension (track delta)
  IF pass: → done, write tests
  ELSE: apply remaining improvements + new ones

CYCLE 3 (final):
  Re-eval
  IF pass: → ship
  ELSE: → ship with KNOWN_GAPS section listing:
    - Which dimensions are still below 7
    - Which improvements couldn't be resolved
    - Why (e.g., "would require architectural change")

サイクルとコストのガードレール

• TTY ではデフォルトの --cycles 3、非 TTY では --cycles 1 です（CI ループでスクリプトを使った一括実行のコストが膨らむのを防ぎます）。
• コマンドは各実行の前に、小さな料金定数に基づく 1 サイクルあたりの推定最大コストを表示します。実際のコストはプロンプトのサイズによって異なります。デフォルトの --max-tokens 4000 に対する上限として、この推定値を扱ってください。
• --budget-usd N による厳密な上限設定は、v0.27.x での後続対応 TODO です。

プロバイダーの設定

モデルは gbrain AI ゲートウェイを通じて解決されます。次の手順で一度設定してください。

gbrain providers test    # see what's configured
gbrain config            # set keys

各スロットでは、プロバイダーのキーが必要です。gbrain providers test --model <provider:model> を実行すると、スロットのモデルに接続できるか確認できます。また、gbrain providers env <provider> では、その設定レシピが参照する環境変数または <vendor>_api_key 設定キーが示されます（~/.gbrain/config.json と process.env）。デフォルト用のキーを取得するのではなく、キーを持っているプロバイダーにスロットを固定してください。

コストの目安

1 回の実行で最大 3 サイクル × 3 モデル、つまりフロンティアモデルへの呼び出しが最大 9 回あります。デフォルトの --max-tokens 4000 とフロンティアクラスのモデルを使う場合、1 回の完全な実行あたり 1～3 ドルが目安です。レシートには呼び出しごとのモデル識別子が含まれるため、後から監査できます。

クロスモーダル評価を省略する場合：

• 出力が 200 トークン未満の場合（単純な出力で、API 呼び出しを 9 回行う価値がありません）。
• スキルが単一の API 呼び出しを薄くラップするだけの場合（1 サイクルで十分です）。

フェーズ 3.5：リグレッション防止ゲート＋スケジュールタスクの再実行（項目 3b、13）— 前進のみの原則

スケジュールされたスキルは、品質を再確認する人が誰もいないうちに、気づかれないままリグレッションを起こし、不適切な出力を本番チャンネルに送信してしまうことがあります。原則は、前進のみです。前回のイテレーションよりスコアが低い編集はリグレッションであり、リリースしてはなりません。元に戻すか、修正し直してください。

3b. リグレッション防止ゲート（スキルを編集するたびに必須）

絶対合格基準（すべての評価次元の平均が 7 以上で、5 未満のスコアがないこと）を満たす必要がありますが、それだけでは不十分です。編集後の出力は、同じタスクと評価次元における前回のイテレーションの評価結果も上回る必要があります。

1. 直近の評価記録を見つけます。評価記録は SKILL.md のコンテンツの sha に紐づいているため、イテレーションごとに個別のファイルが作成されます。

   ls -t ~/.gbrain/.gbrain/eval-receipts/<slug>-*.json | head -5
   

2. 前回の評価記録からベースラインの数値を読み取ります。

   jq '{overall: .aggregate.overall, dims: (.aggregate.dimensions | map_values(.mean))}' <prior-receipt>
   

3. 前回の実行と同じ --task と --dimensions を指定して、編集後の出力を新たに評価します。同じ条件で比較します。評価契約（フェーズ 2.5）を再利用すると、自動的に同じ条件が適用されます。
4. 比較します。
   • 前進（リリース可）： 新しい総合スコアが前回以上であり、かつ、どの評価次元の平均も 0.5 を超えて低下していないこと。
   • リグレッション（ブロック）： 新しい総合スコアが前回を下回る、または、いずれかの評価次元が 0.5 を超えて低下した場合。リリースしてはなりません。主な改善を適用して再評価するか、編集を元に戻してください。リグレッションを記録してください。
5. 前回の評価記録がない場合（初回の評価）は、絶対合格基準（7 以上）を基準とし、今回の実行結果をベースラインにします。
6. 前進のみの履歴を監査できるよう、前後の比較（前回の総合スコア → 新しい総合スコア、判定）をコミットメッセージまたは PR メッセージに記録します。

例外：新しいテストによって動作が完全に固定されている純粋な決定論的バグ修正は、再評価を省略してもかまいません。ただし、フェーズ 7 の再検証は実行します。文章、プロンプト、または出力形式を変更する編集は、再評価が必要です。

13. スケジュールタスクの再実行（スケジュール実行を支えるスキルの編集時に必須）

多くのスキルは、スケジュールされたジョブ（ブリーフィング、日次ダイジェスト、モニター、定期レポート）から呼び出されます。このようなスキルの編集は、編集後のスキルを通して代表的な実タスクを再実行し、実際に生成される出力を評価するまで完了しません。

1. スケジュールによる実行を確認する： スキルを呼び出す cron エントリまたは定期的なミニオンジョブがあるか確認します（gbrain jobs list と、skills/conventions/cron-via-minions.md にあるスケジューラーの設定を確認します）。スキルを参照するジョブが 1 件以上ある場合、このゲートが適用されます。
2. 最も厳しい基準となる代表タスクを選ぶ — 品質が最も明確に表れ、リグレッションの影響が最も大きい入力（ユーザーが最も厳しく読むレポート、文書化された中で最も難しい手順）を選びます。原則は変わりませんが、具体的な入力はデプロイ環境に応じて選びます。スキル本体にハードコードしてはなりません。
3. 実際に実行し、生成されるはずの出力を取得します。 ファイルに書き込みます。スキル化テスト中にライブチャンネルへ投稿してはなりません。送信先を一時ファイルにリダイレクトするか、ドライランフラグを使用します。
4. その出力をクロスモーダル評価し（フェーズ 3）、このタスクに関する前回のイテレーションの評価記録に対してリグレッション防止ゲート（3b）を実行します。 --slug <skill>-<task> を指定してタスクごとのベースラインを分け、評価記録がスキル自体の SKILL.md の評価記録と衝突しないようにします。
5. 前進している場合にのみリリースします。 このタスクの新しいスコアが前回以上であること。スコアが下がった場合、スケジュール出力にリグレッションが生じています。ブロックして修正し直してください。
6. 冪等性を再検証する（「スキルを気づかれないまま壊さない」）： 編集後、フェーズ 1 の監査とフェーズ 7 の検証を再実行し、変更した項目だけでなく、すべてのチェックリスト項目を再確認します。以下を確認してください。
   • 参照されているすべてのスクリプトが引き続き存在し、実行できる（無効なパスがない）。
   • スケジュールジョブが引き続き正しいスキルのパスを呼び出す。
   • テストが引き続き合格する（リグレッションがない）。
   • リゾルバーのエントリが引き続きルーティングする。 以前は合格していた項目が 1 つでも不合格になった場合、編集によって何かが壊れています。リリース前に修正してください。

絶対ルール（スケジュール実行を支えるスキルの SKILL.md に追加）

⛔ NO-REGRESSION + RE-RUN GATE: Any edit to this skill must (1) re-run a
representative scheduled task, (2) cross-modal eval the real output,
(3) score ≥ the previous iteration's receipt. A worse score does NOT ship.
We only go forward.

フェーズ 4：テスト（項目 4～6）

評価で品質が確認できたので、品質を維持するテストを作成します。

単体テスト — 決定的なロジックのすべての分岐をテストします。外部呼び出しはモックします。 統合テスト — 実際のエンドポイントにアクセスします。モックでは見つからないバグを検出します。 LLM 評価 — LLM のステップの品質と正確性を評価します。クロスモーダル評価より軽量で、特定の動作をテストします。

フェーズ 5：リゾルバー＋解決可能性チェック（項目 7～9）

1. 実際にユーザーが入力するトリガーフレーズを使って、skills/RESOLVER.md に追加します
2. リゾルバー評価：トリガーを入力し、正しくルーティングされることを確認します
3. 解決可能性チェック：
   • skills/RESOLVER.md からスキルに到達できること（孤立していないこと）
   • 他のスキルと MECE の重複がないこと
   • DRY 違反がないこと（共有ロジックはコピー＆ペーストせず、lib/ に置きます）
   • トリガーのルーティングに曖昧さがないこと

スキルの作成または更新後は、gbrain check-resolvable --json を再実行し、すべての指摘を解消します。同じトリガーによって混同される 2 つのスキルには、区別できるトリガー語を追加するか、統合します。あるスキルのトリガーが別のスキルのトリガーのサブセットである場合は、統合するか、より具体的にします。

フェーズ 6：E2E＋Brain への登録＋定期実行の可観測性（項目 10～12）

• E2E スモークテスト：トリガーから副作用までのパイプライン全体
• Brain への登録：スキルが Brain ページを書き込む場合は、brain/RESOLVER.md に追加します
• 定期実行の可観測性：以下を参照してください

定期実行の可観測性（項目 12）— スケジュールに基づいて実行されるすべてのスキルが対象

cron または定期ジョブを実行するスキルでは、ジョブは必ず minions（cron の行から gbrain jobs submit を実行）を通じて実行しなければなりません。シェルパイプラインを直接実行してはいけません。そうすることで、実行のたびにステータス、進捗、ログを含むジョブレコードが残ります。無言で実行される幽霊 cron は、可観測性に関するバグの最大の原因です。

検証：

gbrain jobs list             # the scheduled job appears with a status
gbrain jobs get <id>         # per-run progress + result is inspectable

スケジュールのパターンは skills/conventions/cron-via-minions.md と skills/cron-scheduler/SKILL.md にあります。ジョブレーンの仕組みは skills/minion-orchestrator/SKILL.md にあります。

フェーズ 7：検証

bun test test/<skill>.test.ts                    # unit tests
gbrain skillify check skills/<slug>/scripts/<slug>.mjs --json | \
  jq '.[] | .items[] | select(.name | contains("Cross-modal"))'
ls -t ~/.gbrain/.gbrain/eval-receipts/<slug>-*.json | head -2   # receipt landed; prior baseline visible
gbrain check-resolvable --json | jq .ok          # resolver clean

実例：「summarize-pr」機能をスキル化する

Phase 0: Mode A — invoked weekly, 50+ lines, clear trigger "summarize this PR"
Phase 1: Audit → SKILL.md missing, no tests, no resolver entry. Score: 1/15
Phase 2: Write SKILL.md + extract script to scripts/summarize-pr.ts
Phase 2.5: Declare eval_contract — goal: reviewer-ready PR summary;
  dimensions: file_coverage, test_plan, specificity;
  hard-fail: any fabricated claim about the diff
Phase 3: Cross-modal eval cycle 1 (dimensions from the contract; slots from
  models.eval.cross_modal.slot_*) →
  slot A (<provider-1 model>): file_coverage=6, test_plan=4, specificity=5 → "misses file-level diffs"
  slot B (<provider-2 model>): file_coverage=7, test_plan=5, specificity=5 → "no test plan in summary"
  slot C (<provider-3 model>): file_coverage=6, test_plan=5, specificity=5 → "template feels generic"
  Aggregate: file_coverage=6.3 FAIL, test_plan=4.7 FAIL
  Top improvements: add file-level changes, include test plan, use PR context
  → Apply fixes → Cycle 2: file_coverage=8, test_plan=7.5, specificity=7 → PASS
Phase 3.5: First-ever eval → the cycle-2 receipt becomes the baseline
Phase 4: Write 12 unit tests locking in the improved behavior
Phase 5: Add "summarize this PR" trigger to skills/RESOLVER.md
Phase 6: E2E test: feed a real PR URL → verify brain page created.
  Not schedule-backed → items 12–13 N/A
Phase 7: All green. Score: every applicable item passing

実例：既存スキルを改善する（バグ修正）

Input: the user reports the skill labeled a date with the wrong weekday
Skill: travel-brief (already has SKILL.md, code, an eval receipt)

Phase 0: Mode B (Improve) — SKILL.md exists, this is a bug fix
  Delta: the LLM composed day-of-week from reasoning instead of code

Phase 1: Audit existing artifacts
  SKILL.md ✓, code ✓, eval receipt ✓ (but weak — no day-of-week tests)
  Unit tests: ✗ (none existed)
  Integration tests: ✗ (none existed)
  → Missing: items 4, 5, 6. Plus the actual bug.

Phase 2: Fix the code
  - Added a getDayOfWeek(isoDate, tz) helper to the skill's script
  - Updated the formatter to use programmatic day names, never model output
  - Added HARD RULE to SKILL.md: "NEVER derive day-of-week from LLM reasoning"
  - Added a bug entry (template above): date, root cause, fix, tests
  - Bumped version 1.0.0 → 1.1.0

Phase 3: Cross-modal eval — skip (pure deterministic bug fix, behavior
  locked by new tests; prose unchanged)
Phase 3.5: Re-eval skipped per the 3b exception; Phase 7 re-verify still runs

Phase 4: Write tests
  - Unit tests covering every day of the week, timezone edges, formatting
  - Integration tests: state I/O, full pipeline, timezone crossing

Phase 5: Resolver — already routed ✓
Phase 6: E2E — existing pipeline still works ✓
Phase 7: All tests green. Bug fixed. Regression locked in.

品質ゲート

以下を満たすまでは、適切にスキル化されたとはいえません。

• 必須項目がすべて合格している（1～2、4～10。該当する場合のみ 11、スケジュールに基づいて実行される場合のみ 12～13）。
• 評価コントラクト（項目 0）が存在する — フロントマターで宣言されているか、推定または確認した後に書き戻されている（フェーズ 2.5）。
• クロスモーダル評価（項目 3）の最新のレシートがある、または根拠を示して明示的に免除されている（項目 3 は参考情報であり、ブロッキングではありません。ただし、レシートがない場合は監査で確認できます）。
• リグレッション防止ゲートに合格している（項目 3b）：全体スコアが前回のイテレーション以上で、どの評価軸も 0.5 を超えて低下していないこと。
• スケジュールに基づいて実行される場合： 代表的なタスクを再実行して評価し、スコアが改善していること（項目 13）。
• すべてのテスト（単体テスト＋統合テスト＋LLM 評価）に合格している。
• 実際のトリガーフレーズを使ったリゾルバーのエントリーが存在する。
• 解決可能性チェックで、孤立、重複、DRY 違反が検出されない。
• 該当する場合は、Brain に登録されている。

出力形式

Skillify はスキルごとに、永続的な成果物を3つ生成します。

1. ディスク上のスキルツリー。 eval_contract を含む skills/<slug>/SKILL.md、scripts/<slug>.mjs、routing-eval.jsonl、および test/<slug>.test.ts のひな形です。gbrain skillify scaffold <name> で生成し、エージェントが実際に動作する実装へと仕上げます。
2. クロスモーダル評価のレシート系譜（~/.gbrain/.gbrain/eval-receipts/<slug>-<sha8>.json）。sha-8 によって各レシートが、それを生成した SKILL.md の内容に紐付けられるため、以前のレシートはリグレッションなしのベースライン（フェーズ3.5）として保持されます。gbrain skillify check は現在のレシートのステータス（found／stale／missing）を参考情報として表示します。
3. 監査判定（gbrain skillify check によるもの）：properly skilled | close — create: <missing items> | needs skillify — run /skillify on <target>。スコアは <passed>/<total> です。必須項目が判定を左右します。クロスモーダル項目は参考情報であり、PASS を妨げることはありません。

JSON 出力（gbrain skillify check --json）には同じフィールドに加え、項目ごとの詳細文字列も含まれます。そのため、エージェントは文章を解析せず、構造化された出力をもとに処理を振り分けられます。

失敗した場合

gbrain のエラー code、終了コード、[AGENT] ブロック、または通知ブロックについては、エージェント運用者プロトコルに従ってください。このスキルに固有の対応は次のとおりです。

• gbrain skillify check でチェックリスト項目が不合格と表示された場合は、その項目だけを修正して再実行します。編集する場合は、既存のテストが引き続き成功するようにしてください（リグレッションなしの原則）。
• gbrain eval cross-modal が失敗するか、プロバイダーキーがない場合は、評価を未実施として報告します。スキルが実証済みであるとは判断しないでください。
• gbrain check-resolvable で新しいスキルに到達できない、または他のスキルと重複していると報告された場合は、その RESOLVER 行を修正して再実行します。スキャフォールディングでは、プレースホルダーの ## Uncategorized 見出しの下に行が追加されます。適切なカテゴリへ移動してください。

アンチパターン

• ❌ クロスモーダル評価の前にテストを書く（平凡な結果を固定してしまいます）
• ❌ 評価に低予算モデルを使う（A の生徒を C の生徒に採点させるようなものです）
• ❌ 3つの枠すべてに同じプロバイダー系列のモデルを使う（相関した見落としが生じます）
• ❌ 「出力に問題がなさそうだから」と評価を省略する（あなたの判断は3つのモデルではありません）
• ❌ 修正サイクルなしで評価する（見せかけの指標です）
• ❌ 重大な影響を伴うスキルを、その評価契約ではなく汎用的な基準で評価する
• ❌ SKILL.md のないコードを書く（リゾルバーから見えません）
• ❌ 本番コードを再実装するテストを書く（実際のバグが隠れます）
• ❌ 内部用語をリゾルバー項目に使う（実際のユーザーの言葉に合わせる必要があります）
• ❌ 同じことをするスキルを2つ作る（統合するか、どちらかを削除します）
• ❌ 単純な出力（< 200 tokens）に対してクロスモーダル評価を実行する（API 呼び出しを9回使う価値がありません）
• ❌ スキルを改善する際に一から書き直す（Mode B を利用してください）
• ❌ 特定のバグに対するリグレッションテストを追加せずにバグを修正する
• ❌ 再発を防ぐ HARD RULE を SKILL.md に追加せずにバグを修正する
• ❌ 前回の反復よりスコアが下がるスキル編集をリリースする（リグレッションです。前進のみを目指します）
• ❌ スケジュールに基づくスキルを編集した後、代表的なタスクを再実行して実際の出力を評価しない
• ❌ 特定のデプロイメントに属する人物やチャネルをスキル本文にハードコードする（原則を宣言し、具体的な内容は各デプロイメントで補います）
• ❌ チェックリスト項目を1つ編集して、フェーズ7の再検証を省略する（以前合格していた項目が気付かれないまま壊れます）