skill-conductor

Skill Conductor

エージェントスキルのライフサイクル全体を管理します：作成 → テスト → レビュー → 改善 → 繰り返し。

あらゆるスキルを統括します。設計からパッケージ化まで対応します。基本となるループは常に同じです。何かを書き、テストし、失敗した箇所を確認し、修正して、もう一度テストします。

ランタイム要件（事前確認）

スクリプトを扱うモード（CREATE、IMPROVE、VALIDATE、OPTIMIZE、PACKAGE）を実行する前に、事前確認ブロック → references/runtime-setup.md を実行します（uv を確認し、UV_BIN／SKILL_CONDUCTOR_DIR を設定して、LLM へのアクセスを検証します）。uv がない場合は中止し、ユーザーに伝えてください。

コミュニケーション方法

文脈の手がかりを読み取ってください。ユーザーが自作スキルを反復改善している作者なら、率直かつ技術的に対応します。スキルに不慣れなユーザーなら、各ステップで何をするかだけでなく、なぜそれが重要なのかも説明します。ロボットのような応答ではなく、会話調を基本とします。

• 実際に選択肢がある場合は、トレードオフを説明します
• 抽象的なルールより、具体例を使います
• 何かが失敗したら、修正方法だけでなく根本原因も説明します
• 指示には命令形を使います：「データを抽出する」とし、「データを抽出してください」とはしません

モード

文脈からモードを判断します。曖昧な場合は質問してください。

モード	該当する場合	実行内容
1. CREATE	「スキルを作る」「新しいスキルがほしい…」	ライフサイクル全体：意図 → 設計 → ひな形作成 → 作成 → テスト
2. IMPROVE	「このスキルを修正して」「起動しない」	診断 → 評価ループ → ゲート付きセルフアップデート → 反復
3. VALIDATE	「このスキルをテストして」「評価を実行して」	構造チェック + 起動テスト + BinEval によるスコアリング
4. REVIEW	「このスキルをレビューして」、第三者による評価	11 項目の品質ゲート。迅速かつ重点的に実施
5. OPTIMIZE	「起動を改善して」「説明を最適化して」	学習用／テスト用に分割して、説明を自動最適化
6. PACKAGE	「配布用にパッケージ化して」	検証 + .skill ファイルへのバンドル

---

モード 1：CREATE

ステップ 1：意図を把握する

何かを書く前に、具体的なシナリオを 2～3 個抽出します。

次のように質問します。

• 「このスキルには、どのような具体的なタスクを処理させますか？」
• 「このスキルを起動するために、ユーザーは何と言いますか？」
• 「どのような場合には起動しないようにしますか？」

スキルが何を、誰のために、いつ行うのかが明確になるまで先に進まないでください。これにより、最もよくある失敗を防げます。つまり、何かはするものの、適切でない場面で起動してしまうスキルです。

ステップ 2：ベースライン（TDD の RED）

スキルを書く前に、スキルなしではエージェントが失敗することを確認します。

1. ステップ 1 のシナリオを 1 つ選びます
2. スキルを使わずに、クリーンなセッションで実行します
3. 何が問題だったかを記録します。エージェントが何を推測し、何を見落としたかを記録します

エージェントがすでに完璧に対応できているなら、そのスキルは不要です。これは当たり前に聞こえますが、最も省略されがちで、最も価値のあるステップです。

Step 3: アーキテクチャ

references/patterns.md から主要なパターンを選びます（組み合わせてもかまいません）。

パターン	使用する場面
順次ワークフロー	明確なステップに沿って処理する場合
反復的な改善	サイクルを重ねるごとに出力が改善する場合
コンテキスト対応の選択	同じ目標でも状況に応じてツールを変える場合
ドメインインテリジェンス	ツールへのアクセスに加えて専門知識が必要な場合
複数の MCP の連携	ワークフローが複数のサービスにまたがる場合

自由度を選択します。これによって、スキルがエージェントに与える制御と柔軟性の度合いが決まります。

自由度	使用する場面	例
低（スクリプト）	壊れやすい、エラーが発生しやすい、厳密さが必要な場合	PDF の回転、API 呼び出し
中（擬似コード）	推奨パターンがあり、ある程度の変化が許容される場合	データ処理
高（テキスト）	複数の有効な方法があり、判断が必要な場合	設計上の決定

自由度の判断基準：「エージェントがここで間違えた場合、どのような結果になるか？」と考えます。影響が大きい場合は自由度を低くします（変更してはいけない厳密なスクリプトなど）。影響が小さい場合は自由度を高くします（文章で記述し、判断を任せるなど）。スキル全体ではなく、ステップごとに調整してください。1 つのスキルに両方を含めてもかまいません。

鉄則：スキルの作成またはレビューを行う前に、必ず references/sop-practices.md を読んでください。 ここには、基本となる作成の 10 原則（普遍的な原則）が記載されています。事前確認、説明にプロセスを含めない、MOC（SKILL.md は文章ではなくマップ）、実務経験の浅い作成者、TWI の「理由」、ブラインドエージェントテスト、インラインチェックリスト、概念ごとに用語を統一、無駄を省く（SKILL.md から環境変数やキーを除外）、失敗に合わせた形式です。手順型スキル（分岐のあるビジネスプロセス：依頼、見積もり、オンボーディング、エスカレーション）については、同じファイルに詳細な SOP 手法（形式の選択、7 ステップのプロセス、手順チェックリスト）も記載されています。

Step 4: ひな形を作成する

uv run scripts/init_skill.py <skill-name> --path <output-dir> [--resources scripts,references,assets]

または、手動で作成します。

skill-name/
├── SKILL.md          # required — the brain
├── scripts/          # deterministic operations (executed, not loaded)
├── references/       # detailed docs (loaded on demand)
└── assets/           # templates, images for output (never loaded)

Step 5: SKILL.md を作成する

フロントマター

---
name: kebab-case-name
description: >
  [What it does]. Use when [4-5 phrasing variations users actually say] — even
  if they don't explicitly say "[canonical term]". Do NOT use for [negatives].
---

説明は最も重要な 1 行です。スキルが起動するかどうかは、この行で決まります。完全な形式、強く促す句、GOOD/BAD の実例は references/sop-practices.md の原則 #2 に記載されています。説明を書く前に読んでください。

• name：小文字、数字、ハイフンのみを使用します。ハイフンを連続させないでください。フォルダー名と一致させます。最大 64 文字です
• description：最大 1024 文字です。山括弧は使用しません。プロセスやワークフローの手順は含めません
• 説明にワークフローを書かないでください。 テストで確認されています。説明にプロセスの手順を列挙すると、エージェントはそれに従い、本文全体を読み飛ばします

本文の構成

# Skill Name

## Overview

What this enables. 1-2 sentences. Core principle.

## [Main sections]

Step-by-step with numbered sequences.
Concrete templates over prose.
Imperative voice throughout.

## Common Mistakes

What goes wrong + how to fix.

## Troubleshooting (if applicable)

Error: [message] → Cause: [why] → Fix: [how]

執筆ルール

• 概念ごとに用語を統一します。 「template」を選んだら、最後までその用語を使います。「template／boilerplate／scaffold」のように混在させないでください（原則 8）
• SKILL.md は文章ではなくマップです。 本文は参照先を示す目次として構成し、詳細は参照先に記載します（原則 3）
• SKILL.md にシークレットや環境変数を記載しないでください。 キー、パスワード、トークン、環境変数の値、ユーザー固有の絶対パス（/home/<user>、/Users/<user>）は記載せず、参照のみを記載します（原則 9a）
• 段階的な情報開示。 SKILL.md は脳にあたる部分です（500 行未満）。詳細は参照ファイルに記載します。階層は 1 段階にします
• トークンの予算。 頻繁に読み込まれる内容は 200 語未満、標準的な内容は 500 行未満にします。大きな内容は references/ に移します
• 不要なファイルを置かないでください。 スキル内に README や CHANGELOG を含めないでください
• スクリプト： 同じコードを繰り返し書き直す場合、または処理が壊れやすい場合は同梱します。失敗時には、説明的な内容を stdout/stderr に返す必要があります
• 命令形を使います。 「データを抽出する」と書き、「抽出するべき」や大文字の「MUST／NEVER」は使わないでください。ルールより説明を優先します（references/sop-practices.md の原則 5、TWI を参照）

ステップ 6：テストケースと評価ループ

ここが最も重要なステップです。ほとんどの失敗はここに潜んでいます。3つのサブフェーズに分けて取り組んでください。

ループ全体を始める前に、今書いた内容の文言をマイクロテストしてください（新しいコンテキストで5回以上実施し、必ずガイダンスなしの対照テストも行います）→ references/pressure-testing.md。規則を破りたくなるエージェントにその規則を守らせる規律スキルでは、このファイルにあるプレッシャーシナリオの実施は必須であり、省略できません。

6a. 事前確認（何かを起動する前に）

• evals/evals.json に3～5個のプロンプトがある（references/schemas.md を参照）
• ワークスペースディレクトリを作成済み：<skill-name>-workspace/iteration-1/
• 各評価に説明的な名前（単なる eval-0 ではない）と eval_metadata.json がある
• 実行サブエージェント用のAnthropicキーが設定されている
• 現在の作業ディレクトリから uv と eval-viewer/generate_review.py にアクセスできる

いずれかの項目を満たしていない場合は、先に修正してから進めてください。実行中にワークスペースディレクトリがないと、出力が失われます。

6b. 実行ループ（すべて同じターンで行う）

内容	主な作業	理由
スキルありの実行を起動する	評価ごとにサブエージェントを1つ起動し、スキルを有効にして、出力を iteration-N/<eval-name>/with_skill/ に保存する	並列実行なら、1回の実行と同じ所要時間で済みます
同じターンでベースラインの実行を起動する	同じプロンプトを使い、スキルなし（またはIMPROVEの場合は旧バージョンのスナップショット）で実行し、without_skill/ または old_skill/ に保存する	後から実行すると、ベースラインの条件が時間とともにずれ、比較できなくなります
実行中にアサーションの草案を作成する	評価プロンプトから検証可能な記述を抜き出す	サブエージェントの実行時間である5～15分を無駄にしないためです
通知のたびに所要時間を記録する	total_tokens と duration_ms をただちに timing.json に保存する	通知が唯一の情報源です。まとめて処理せず、到着ごとに記録してください

6c. 実行後のチェックリスト

• すべての timing.json ファイルを書き込み済み（実行ごとに1つ）
• 各実行に、フィールド text、passed、evidence（name／met ではありません）を含む grading.json がある
• benchmark.json を集約済み：uv run scripts/aggregate_benchmark.py <workspace>/iteration-N --skill-name <name>
• アナリストによる確認を実施済み。確認項目については agents/analyzer.md を参照してください（識別力のないアサーション、ばらつきの大きい評価、時間とトークンのトレードオフ）
• 評価ビューアーを起動済み：uv run eval-viewer/generate_review.py <workspace> --skill-name <name> --benchmark <path>
  • ヘッドレスモードの場合：--static <output.html> を指定し、ファイルをユーザーに送ります
  • 2回目以降のイテレーションでは、--previous-workspace <previous-iteration-path> を追加します
• スキルの編集を始める前に、ユーザーがビューアーを確認済み

最後の項目が落とし穴です。ユーザーのレビューを省略し、自分で出力を読んで「改善」すると、ユーザーの好みではなく自分の好みに合わせて最適化することになります。

ステップ 7：検証とリファクタリング

1. 適切なクエリでスキルが自動的に起動しますか？
2. エージェントは本文の指示に従いますか（説明だけに従うのではなく）？
3. 出力はユースケースの要件を満たしていますか？
4. 関連のないクエリでは起動しませんか？

いずれかを満たさない場合は、反復してください。エージェントがスキルをどう解釈して回避するのかを見つけ、抜け穴をふさいで再検証します。

---

モード 2：IMPROVE

ステップ 1：診断

既存のSKILL.mdを最初から最後まで読みます。問題の種類を特定してください。

問題	兆候	対処
トリガー不足	スキルが読み込まれない	説明にキーワード、トリガーフレーズ、ファイルの種類を追加する
過剰なトリガー	関連のないクエリでも読み込まれる	除外トリガーを追加し、より具体的にする
本文を無視する	説明にしか従わない	説明からプロセス／ワークフローを削除する
出力に一貫性がない	セッションごとにばらつく	明示的なテンプレートを追加し、自由度を下げ、スクリプトを追加する
遅すぎる	コンテキストが大きい	詳細を references/ に移し、本文を500行未満にする

改善の考え方

1. フィードバックから一般化します。 少数の例を使って反復していますが、スキルは何千ものプロンプトで使われます。過剰適合しないようにしてください。1つのテストケースに合わせた細かなパッチや、厳しすぎる MUST の追加は避けましょう。代わりに、異なる比喩やパターンを試してください
2. プロンプトは簡潔に保ちます。 出力だけでなく、トランスクリプトも確認してください。スキルによってモデルが成果につながらない手順に時間を費やす場合は、その指示を削除して結果を確認しましょう
3. 理由を説明します。 LLM は他者の意図を理解する能力に優れています。大文字の ALWAYS／NEVER で指示するのではなく、理由を説明しましょう。そのほうが効果的で堅牢です。厳格なルールを書く場合は、説明として言い換えてください
4. 繰り返し行われる作業を探します。 すべてのテスト実行で同じヘルパースクリプトを個別に作成しているなら、scripts/ にまとめましょう。そうすれば、今後の実行で毎回作り直す必要がなくなります
5. 作成の基本原則を適用します。 references/sop-practices.md を読み、普遍的な10の基本原則を確認してください。これらは、スキルの失敗要因に直接対応しています。説明へのプロセスの混入、マップではなく肥大化した SKILL.md、環境変数やキーの直接記載、「なぜ」の説明不足による暗黙の即興、エッジケースの見落とし、エージェントが文末のチェックリストを飛ばすこと、失敗の形に合っていないルールなどです。プロセススキル（チケット、見積もり、エスカレーション）では、同じファイルにある詳細な SOP の方法論も適用してください

ステップ 2：評価の反復ループ

改善サイクルは CREATE のステップ 6 に沿っていますが、失敗した動作に焦点を当てます。候補となる文言は、ループに加える前に小規模なテストを行います。また、スキルでルールを適用する場合は、プレッシャーシナリオを再実行してください → references/pressure-testing.md。

1. 現在のスキルで失敗ケースを実行し、失敗を記録する
2. CREATE のステップ 5 の執筆ルールを使って修正する
3. 評価を再実行し、agents/grader.md で採点する
4. ビューアーを起動する：uv run eval-viewer/generate_review.py <workspace>
   • ヘッドレス／Cowork： ライブサーバーの代わりに --static <output.html> を使用する
5. 確認してフィードバックを提供し、反復する

ステップ 3：ゲート付き自己更新ループ

好みではなく、失敗した BinEval の質問を基準に反復を進めます。編集者が一度も見ていない証拠に基づく編集のみを受け入れてください。完全なルールは references/bineval-method.md § ゲート付き自己更新ループを参照してください。

1. セッションごとに一度、分割を固定します： uv run scripts/split_evals.py evals/evals.json --holdout 0.4 --write <workspace>/split.json — 決定論的に分割し、任意の eval ごとの category によって層化します。結果を見た後で再分割しないでください
2. 現在のバージョンですべての eval を実行して採点します（Mode 3 Stage 3 と references/bineval-method.md を参照）→ failing[] を収集します
3. TRAIN ケースのみを対象に失敗を分析します。トレーニング用のトランスクリプトと採点結果を使って agents/analyzer.md を起動し、一般化され重複のない教訓を作成します。ゲートに到達するまで、ホールドアウトの採点結果は開かないでください
4. 最大 3 件のアトミックな編集を適用します（ルール、段落、表の行を 1 つ追加、削除、または置換すること。編集 1 件につき教訓 1 件をラベル付けします）。全面的な書き換えはしないでください。差分を小さく保つことで、ゲートで原因と結果を特定しやすくなります
5. すべての eval を再実行します。ゲート — 次の条件をすべて満たす場合にのみ受け入れます： (a) 親バージョンと比較して、ホールドアウトのアサーションに pass から fail への変化がない（変化として数えるのは、2 回連続の実行で再現した場合のみです。1 回だけの実行にはノイズがあります）；(b) train の合格率が厳密に向上している；(c) 新たに失敗した重要な質問がない。ホールドアウトでの改善は歓迎しますが、必須ではありません。ホールドアウトのケースが 5～8 件の場合、改善を必須にすると運に左右されるためです
6. アサーションごとの遷移（改善／悪化／失敗継続／成功維持）を記録します → benchmark.json の transitions ブロック
7. train の failing[]（またはその重要なサブセット）が空になったとき、もしくは 3 回反復した時点で終了します。ホールドアウトの合格率、次に train の合格率の順で、最良の ACCEPTED バージョンを維持します

ステップ 3b：ブラインド比較（任意、大幅な変更向け）

意味のある違いがある2つのバージョンがある場合：

1. 同じ評価セットで両方のバージョンを実行します
2. agents/comparator.md を起動します。どちらのスキルが各出力を生成したかを知らない状態で、出力 A と B について同じ二択の質問に回答します
3. 比較担当者が各バージョンの次元別「はい」の割合を報告します。全体の「はい」の割合が高いほうを勝者とし、同点の場合は重要な次元の「はい」の割合で決めます
4. agents/analyzer.md を起動し、結果のブラインドを解除して、勝者が勝った理由を分析します
5. 得られた知見を、負けたバージョンの改善に活用します

これにより、バイアスを防ぎます。比較担当者が評価するのは出力の品質であり、スキルの設計ではありません。

---

モード 3：VALIDATE

3つのステージを順番に実行します。

ステージ 1：構造の検証

uv run scripts/eval_skill.py <skill-folder>

確認項目：フロントマター、命名、説明の品質、プロセス漏洩の検出、本文のサイズ、構造、スクリプト。目標：10/10、警告なし。

ステージ 2：ディスカバリー（トリガーテスト）

テスト用プロンプトを6つ作成します。

• スキルがトリガーされるべきものを3つ
• トリガーされるべきでないものを3つ（似ているが、対象分野が異なるもの）

それぞれをクリーンなセッションで実行します。目標：6/6 正解。

大規模な自動トリガーテストには、次を使用します。

uv run scripts/run_eval.py --eval-set <path> --skill-path <path> --runs-per-query 3

ステージ 3：BinEval スコアリング

5つの次元にわたる、原子的な二択の「はい／いいえ」質問で評価します。各質問は、根拠を挙げた記述式の批評の後に、1 または 0 で回答します。手法については references/bineval-method.md、質問バンクについては references/quality-questions.md、bineval.json を出力する評価担当者については agents/bineval.md を参照してください。

5つの次元：ディスカバリー、明確さ、構造、堅牢性、完全性。

スキル成果物に関する質問は、2つのソースから取得します（question_source: "hybrid"）。

• 決定論的 — 唯一の出力元である scripts/eval_skill.py --json が出力します。例：DET-STRUCT-SKILLMD-EXISTS、DET-DISCOVERY-DESC-PRESENT。重要としてフラグ付けされるものもあります。
• 固定バンク — references/quality-questions.md にバージョン管理されている LLM の質問です。評価担当者はこれに回答し、独自の質問を作成しません。（2段階のメタプロンプトでタスクごとに生成される質問は、agents/grader.md に記載のモード 1～2 における出力評価用であり、成果物のスコアリングには使用しません。）

評価担当者は質問に回答するだけです。集計はあなたが行います。次元ごとの dimension_scores S_d は、その次元の回答の平均値です。全体の S は、すべての回答の平均値です。評価担当者用プロンプトに合格基準や GATE を絶対に含めないでください。基準を知っている評価担当者は、それに合わせて判断するバイアスが生じます（references/bineval-method.md）。

表示バンド： S≥0.90 本番運用可能 · 0.70–0.89 良好 · 0.50–0.69 要改善 · <0.50 書き直し

GATE = すべての重要な質問（決定論的な質問と、固定バンクの重要な質問）に 1 と回答していること。合格基準は GATE であり、スカラー値 S ではありません。

---

モード 4：REVIEW

サードパーティ製スキル向けの簡易品質ゲートです。

チェックリスト（合格／不合格）

[ ] SKILL.md exists, exact case
[ ] Valid YAML frontmatter (name + description)
[ ] name: kebab-case, matches folder, ≤64 chars
[ ] description: ≤1024 chars, no angle brackets
[ ] description has triggers ("Use when...")
[ ] description has NO workflow/process steps
[ ] No README.md inside skill folder
[ ] SKILL.md < 500 lines
[ ] References max 1 level deep
[ ] Scripts tested and executable
[ ] No hardcoded paths/tokens/secrets

次に、説明に対して VALIDATE のステージ 2（ディスカバリー）を実行します。スコアとチェックリストを報告します。

このチェックリストの決定論的なサブセットは、唯一の出力元である scripts/eval_skill.py --json によって、二値の BinEval 質問レコードとして出力されます（例：DET-STRUCT-SKILLMD-EXISTS、DET-DISCOVERY-DESC-PRESENT、DET-ROBUST-NO-SECRETS）。

このチェックリストがあるのは、ここに挙げた項目が実際に起きる失敗要因だからです。特に説明内のプロセス記述は、エージェントが本文を完全に読み飛ばす原因になります。

---

モード 5：OPTIMIZE

説明を自動で最適化します。説明は Claude の注意を引くために他のスキルと競合します。最適化では、最も正確にトリガーされる表現を見つけます。同じ訓練データとホールドアウトデータの原則が、本文の編集にも適用されるようになりました。モード 2 のステップ 3 を参照してください。

仕組み

1. 評価セットを作成します：クエリ20件（トリガーされるべきもの10件、トリガーされるべきでないもの10件）

優れた評価クエリの作成

クエリは現実的なものにしてください。ファイルパス、文脈、略語、タイプミスを含む、具体的で詳細な内容にします。"Format this data" ではなく、"my boss sent Q4 sales final FINAL v2.xlsx, add profit margin % column, revenue is col C costs col D" のようにします。

トリガーすべきクエリ（10件）： 同じ意図を異なる表現で示します。フォーマル、カジュアル、暗示的な表現を含めてください。ユーザーがスキル名を挙げていなくても、明らかにそのスキルを必要としているケースも含めます。競合するスキルとの境界事例も追加してください。

トリガーすべきでないクエリ（10件）： キーワードは共通していても、別の対応が必要な、わずかに異なるケースです。隣接する領域や、曖昧な表現を含めます。PDF スキルの否定例として「Write fibonacci」を使うのは役に立ちません。簡単すぎるためです。否定例は本当に判断の難しいものにしてください。

トリガーの仕組み： Claude は直接対応できないタスクに対してのみスキルを参照します。単純なクエリ（「この PDF を読んで」など）では、説明の内容にかかわらずスキルはトリガーされません。Claude が基本ツールで対応できるためです。評価クエリは、スキルを参照することで有用な支援が得られるほど、十分に実質的な内容にしてください。

2. ブラウザーでクエリを確認します：assets/eval_review.html
3. 最適化ループを実行します：

uv run scripts/run_loop.py \
  --eval-set evals/eval_set.json \
  --skill-path <skill-dir> \
  --model <model-id> \
  --max-iterations 5 \
  --holdout 0.4 \
  --verbose

ループの内容：

• クエリをトレーニング用（60%）と保留用（40%）に分割し、過学習を防ぎます
• 各イテレーションで、現在の説明を評価 → Claude が改善案を提示 → 再評価します
• 改善モデルに見せるのはトレーニング結果のみです（保留データは見せません）
• 保留スコアに基づいて最適な説明を選択します
• ライブ HTML レポートを自動的に開きます

補助スクリプト

スクリプト	目的
scripts/run_eval.py	説明に対するトリガー評価を実行します
scripts/improve_description.py	Claude が説明の改善案を提示します
scripts/generate_report.py	最適化履歴を HTML で可視化します
scripts/aggregate_benchmark.py	ベンチマーク実行結果を統計的に集計します

---

モード 6：パッケージ化

1. REVIEW チェックリストを実行します（モード 4）
2. 検証します：

uv run scripts/quick_validate.py <skill-folder>

3. パッケージ化します：

uv run scripts/package_skill.py <skill-folder> [output-dir]

skill-name.skill（拡張子が .skill の zip ファイル）が作成されます。一時ディレクトリで解凍し、構成が損なわれていないことを確認してください。

---

クイックリファレンス

スキルのカテゴリ

1. ドキュメント／アセットの作成 — 一貫性のある出力（ドキュメント、デザイン、コード）
2. ワークフローの自動化 — 方法論に基づく複数ステップのプロセス
3. MCP の拡張 — ツールへのアクセスに加えて、ワークフローのガイダンスを提供します
4. 手順／プロセス — 判断ポイントや例外を含む業務手順（依頼への対応、見積もりの作成、請求書の処理、オンボーディング、エスカレーション）。このカテゴリでは references/sop-practices.md を読みます

ファイルの用途

ディレクトリ	読み込みのタイミング	用途
SKILL.md	トリガー時	中核 — 指示
references/	必要に応じて	詳細なドキュメント、スキーマ
scripts/	実行される（読み込みなし）	決定論的な処理
assets/	読み込まれない	テンプレート、画像

段階的開示の予算

レベル	読み込みのタイミング	予算
Frontmatter	常時（システムプロンプト）	約 100 語
SKILL.md 本文	トリガー時	500 行未満
同梱リソース	必要に応じて	無制限

説明の数式

[What it does] + Use when [4-5 phrasings users actually say] + even if they don't explicitly say "<canonical term>" + Do NOT use for [negatives] — 完全なルールと例については、references/sop-practices.md の原則 #2 を参照してください。

参照ファイル

各モードで指定された使用時に、その都度読み込みます。一括で読み込まないでください。agents/* ファイルは、そのエージェントを起動する手順でのみ読み込みます。references/schemas.md は、JSON アーティファクトを読み書きするときにのみ読み込みます。それ以外は読み込まずにおきます。

パス	内容
agents/grader.md	根拠に基づくアサーションの評価
agents/comparator.md	ブラインド形式の A/B 出力比較
agents/analyzer.md	事後分析 + ベンチマークのメモ
agents/bineval.md	BinEval 評価器 — bineval.json を出力
references/patterns.md	5 つのアーキテクチャパターン + アンチパターン
references/schemas.md	評価、採点、ベンチマーク用の JSON スキーマ
references/bineval-method.md	BinEval の手法：次元、スコアリング、GATE
references/quality-questions.md	BinEval の質問集（決定論的 + バンク）
references/pressure-testing.md	表現を検証するマイクロテスト + 規律スキル向けのプレッシャーシナリオ
references/sop-practices.md	基準：10 の普遍的な執筆原則 + 手順スキル向けの詳細な SOP 方法論
references/runtime-setup.md	実行前チェック：uv/env/path の確認、LLM アクセス方法
eval-viewer/	評価結果を表示するインタラクティブな HTML ビューアー
assets/eval_review.html	トリガー評価セットのエディター
scripts/eval_skill.py	構造検証（10 点満点のスコアリング）
scripts/init_skill.py	スキルのひな形生成
scripts/run_eval.py	トリガー評価ランナー
scripts/run_loop.py	評価 + 改善の最適化ループ
scripts/improve_description.py	Claude を使用した説明文の改善
scripts/aggregate_benchmark.py	ベンチマーク統計の集計
scripts/generate_report.py	HTML レポートの生成
scripts/quick_validate.py	パッケージャー用の簡易検証
scripts/test_smoke.py	すべてのスクリプトのスモークテスト（12 件）
scripts/package_skill.py	スキル → .skill パッケージャー
scripts/utils.py	共通ユーティリティ（parse_skill_md）