@einja/dev-cli 0.1.40 → 0.1.44

package/presets/default/.claude/skills/einja-skill-creator/SKILL.md

@@ -1,421 +1,469 @@
 ---
 name: einja-skill-creator
-description: 効果的なSkillを作成するためのガイド。ユーザーが新しいSkillを作成したい（または既存のSkillを更新したい）場合に使用。Skillの構造、段階的開示、適切な自由度設定、バンドルリソース（scripts/references/assets）の使い方、einja固有の規約（einja-プレフィックス、references/ディレクトリ、マネージドセクション）を含む。スクリプトツール（init_skill.py、package_skill.py、quick_validate.py）を提供。
+description: >
+  新しいSkillの作成、既存Skillの改善・更新、Skillパフォーマンスの評価に使用。Skillをゼロから作成したい場合、既存Skillを更新・最適化したい場合、評価テストでSkillをテストしたい場合、ベンチマークでパフォーマンスを分析したい場合、Skillのdescriptionのトリガー精度を最適化したい場合に使用。Create new skills, modify and improve existing skills, measure skill performance, run evals, benchmark, optimize description triggering.
 ---
 
 # Skill作成ガイド
 
-## 概要
+Skillを作成し、反復的に改善するためのSkill。
 
-このSkillは、効果的なSkillを作成するためのガイドを提供します。ユーザーが新しいSkillを作成したい（または既存のSkillを更新したい）場合に使用してください。
+大まかなプロセスは以下の通り：
 
-## Skillとは
+- Skillに何をさせたいか、どのように動作すべきかを決める
+- Skillのドラフトを書く
+- いくつかのテストプロンプトを作成し、Skill付きのClaudeで実行する
+- ユーザーと共に結果を定性的・定量的に評価する
+  - バックグラウンドで実行中に、定量的な評価項目がなければドラフトする。すでにある場合はそのまま使用するか、必要に応じて修正する。ユーザーに説明する
+  - `eval-viewer/generate_review.py`スクリプトで結果をユーザーに表示し、定量的メトリクスも確認してもらう
+- ユーザーの評価フィードバック（および定量的ベンチマークから明らかになった問題）に基づいてSkillを書き直す
+- 満足するまで繰り返す
+- テストセットを拡大し、より大規模に再試行する
 
-Skillは、Claudeの能力を専門知識、ワークフロー、ツール統合によって拡張する、モジュール化された自己完結型パッケージです。Skillを「特定のドメインやタスクのためのオンボーディングガイド」として考えてください。汎用エージェントであるClaudeを、どのモデルも完全には持ち得ない手続き的知識を備えた専門エージェントに変換します。
+このSkillを使う際の役割は、ユーザーがこのプロセスのどこにいるかを把握し、次のステージに進む手助けをすること。例えば「Xのスキルを作りたい」と言われたら、意図を明確化し、ドラフトを書き、テストケースを作成し、評価方法を決め、全プロンプトを実行し、繰り返す。
 
-### Skillが提供するもの
+一方、すでにドラフトがある場合は、直接eval/反復パートに入れる。
 
-1. **専門化されたワークフロー** - 特定ドメインのための複数ステップの手順
-2. **ツール統合** - 特定のファイル形式やAPIを扱うための指示
-3. **ドメイン専門知識** - 会社固有の知識、スキーマ、ビジネスロジック
-4. **バンドルリソース** - 複雑で反復的なタスクのためのスクリプト、参照資料、アセット
+もちろん柔軟に。ユーザーが「大量の評価は不要、一緒に感覚で作ろう」と言えばそうする。
 
-## 基本原則
+Skillが完成した後（順序は柔軟）、Skillのdescription最適化も実行できる。これには専用のスクリプトがある。
 
-### 簡潔さが鍵
+## ユーザーとのコミュニケーション
 
-コンテキストウィンドウは公共財です。Skillは、Claudeが必要とする他のすべてのもの（システムプロンプト、会話履歴、他のSkillのメタデータ、実際のユーザーリクエスト）とコンテキストウィンドウを共有します。
+スキルクリエイターは、コーディング用語への馴染み度が大きく異なるユーザーに使われる可能性がある。コンテキストの手がかりに注意して、コミュニケーションの言い回しを調整すること。デフォルトの目安：
 
-**デフォルトの前提: Claudeはすでに非常に賢い。** Claudeがまだ持っていないコンテキストのみを追加してください。各情報について「Claudeは本当にこの説明が必要か？」「この段落はトークンコストに見合うか？」と問いかけてください。
+- 「評価」「ベンチマーク」はボーダーラインだがOK
+- 「JSON」「アサーション」はユーザーがそれらを知っている確実な手がかりを見てから、説明なしで使用する
 
-冗長な説明よりも簡潔な例を優先してください。
+疑わしい場合は用語を簡潔に説明してOK。不明な場合は短い定義を添えて明確にする。
 
-### 適切な自由度の設定
+---
 
-タスクの脆弱性と可変性に応じて、具体性のレベルを合わせます：
+## Skillの作成
 
-**高自由度（テキストベースの指示）**: 複数のアプローチが有効な場合、決定がコンテキストに依存する場合、またはヒューリスティックがアプローチを導く場合に使用します。
+### 意図の把握
 
-**中自由度（疑似コードまたはパラメータ付きスクリプト）**: 推奨パターンが存在する場合、ある程度のバリエーションが許容される場合、または設定が動作に影響する場合に使用します。
+ユーザーの意図を理解することから始める。現在の会話にすでにワークフローが含まれている場合（例：「これをスキルにして」）、会話履歴から回答を抽出する — 使用されたツール、ステップの順序、ユーザーの修正、観察されたI/O形式。ユーザーにギャップを埋めてもらい、次に進む前に確認する。
 
-**低自由度（特定のスクリプト、少数のパラメータ）**: 操作が脆弱でエラーが起きやすい場合、一貫性が重要な場合、または特定のシーケンスに従う必要がある場合に使用します。
+1. このSkillでClaudeに何をできるようにしたいか？
+2. このSkillはいつトリガーすべきか？（どのようなユーザーフレーズ/コンテキスト）
+3. 期待される出力フォーマットは？
+4. Skillの動作を検証するためのテストケースを設定すべきか？客観的に検証可能な出力（ファイル変換、データ抽出、コード生成、固定ワークフロー）を持つSkillはテストケースの恩恵を受ける。主観的な出力（文体、アート）は通常不要。Skillの種類に基づいて適切なデフォルトを提案するが、最終判断はユーザーに委ねる。
 
-Claudeがパスを探索していると考えてください：崖のある狭い橋には特定のガードレールが必要（低自由度）ですが、開けた野原では多くのルートが許されます（高自由度）。
+### インタビューとリサーチ
 
-### Skillの構造
+エッジケース、I/Oフォーマット、サンプルファイル、成功基準、依存関係について積極的に質問する。テストプロンプトの作成はこの部分が固まってから。
 
-すべてのSkillは、必須のSKILL.mdファイルとオプションのバンドルリソースで構成されます：
+利用可能なMCPを確認 — リサーチに有用なら（ドキュメント検索、類似スキル発見、ベストプラクティス参照）、サブエージェントで並行リサーチ。
 
-```
-skill-name/
-├── SKILL.md (必須)
-│   ├── YAMLフロントマターメタデータ (必須)
-│   │   ├── name: (必須)
-│   │   ├── description: (必須)
-│   │   └── compatibility: (オプション、めったに不要)
-│   └── Markdown指示 (必須)
-└── バンドルリソース (オプション)
-    ├── scripts/          - 実行可能コード（Python/Bash等）
-    ├── references/       - 必要に応じてコンテキストに読み込むドキュメント
-    └── assets/           - 出力で使用されるファイル（テンプレート、アイコン、フォント等）
-```
+### SKILL.mdの作成
 
-#### SKILL.md（必須）
+ユーザーインタビューに基づいて以下を記入：
 
-すべてのSKILL.mdは以下で構成されます：
+- **name**: Skill識別子。ディレクトリ名と一致させること
+  - インナーSkill（他Skillから内部的に参照される、プロトコル定義、出力テンプレート等）
+    は `_` プレフィックスをつける（例: `_einja-output-format`）
+  - プロジェクト固有のSkillには名前空間プレフィックスをつけない
+  - プロジェクトの名前空間プレフィックスはCLAUDE.mdに定義される
+- **description**: いつトリガーするか、何をするか。主要なトリガーメカニズム。Skillが何をするかと使用する具体的なコンテキストの両方を含める。「いつ使用するか」情報はすべてここに。本文はトリガー後に読み込まれるため、本文の「使用すべき場合」セクションはClaudeに役立たない。注意：現在Claudeはスキルを「アンダートリガー」する傾向がある。対策としてdescriptionを少し「積極的」にする
+- **compatibility**: 必要なツール、依存関係（オプション、まれに必要）
+- **Skillの残りの部分 :)**
 
-- **フロントマター**（YAML）: `name`と`description`フィールド（必須）を含み、`license`、`metadata`、`compatibility`などのオプションフィールドもあります。Claudeがいつスキルをトリガーするかを判断するため、何のスキルか、いつ使用すべきかについて明確かつ包括的に記述してください。`compatibility`フィールドは環境要件（対象プロダクト、システムパッケージ等）を記載しますが、ほとんどのスキルには不要です。
-- **本文**（Markdown）: スキル使用のための指示とガイダンス。スキルがトリガーされた後（もしあれば）のみ読み込まれます。
+### Skill記述ガイド
 
-#### バンドルリソース（オプション）
+#### ディレクトリ命名規則
 
-##### scripts/
+ディレクトリ名はSkillの配布範囲を決定する:
+- `{namespace}-{name}/` — 配布対象のユーザー向けSkill（例: `einja-task-commit/`）
+- `_{namespace}-{name}/` — 配布対象のインナーSkill（例: `_einja-output-format/`）
+- `{name}/` — プロジェクト固有Skill、配布されない（例: `cli-package-specs/`）
 
-決定論的な信頼性が必要なタスクや繰り返し書き直されるタスクのための実行可能コード（Python/Bash等）。
+`name` フィールドはディレクトリ名と一致させること。
 
-- **含めるべき場合**: 同じコードが繰り返し書き直される場合、または決定論的な信頼性が必要な場合
-- **例**: PDF回転タスクのための `scripts/rotate_pdf.py`
-- **利点**: トークン効率的、決定論的、コンテキストに読み込まずに実行可能
-- **注意**: スクリプトはパッチや環境固有の調整のためにClaudeによって読まれる場合があります
+#### Skillの構造
 
-##### references/
+```
+skill-name/
+├── SKILL.md（必須）
+│   ├── YAMLフロントマター（name、description必須）
+│   └── Markdown指示
+└── バンドルリソース（オプション）
+    ├── scripts/    - 決定論的/反復タスク用の実行可能コード
+    ├── references/ - 必要に応じてコンテキストに読み込むドキュメント
+    └── assets/     - 出力で使用されるファイル（テンプレート、アイコン、フォント等）
+```
 
-Claudeの処理と思考を導くために必要に応じて読み込まれることを意図したドキュメントと参照資料。
+#### 段階的開示
 
-- **含めるべき場合**: Claudeが作業中に参照すべきドキュメント
-- **例**: 財務スキーマのための `references/finance.md`、会社のNDAテンプレートのための `references/mnda.md`、会社ポリシーのための `references/policies.md`、API仕様のための `references/api_docs.md`
-- **使用例**: データベーススキーマ、APIドキュメント、ドメイン知識、会社ポリシー、詳細ワークフローガイド
-- **利点**: SKILL.mdをスリムに保ち、Claudeが必要と判断した場合のみ読み込み
-- **ベストプラクティス**: ファイルが大きい場合（>10k語）、SKILL.mdにgrep検索パターンを含める
-- **重複を避ける**: 情報はSKILL.mdまたはreferencesファイルのどちらか一方に存在すべきで、両方には存在すべきではありません。詳細情報にはreferencesファイルを優先してください。SKILL.mdには必須の手続き的指示とワークフローガイダンスのみを保持し、詳細な参照資料、スキーマ、例はreferencesファイルに移動してください。
+Skillは3レベルの読み込みシステムを使用：
+1. **メタデータ**（name + description）- 常にコンテキスト内（~100語）
+2. **SKILL.md本文** - Skillトリガー時（500行以内が理想）
+3. **バンドルリソース** - 必要に応じて（無制限、スクリプトは読み込まずに実行可能）
 
-##### assets/
+語数は目安であり、必要に応じて長くしてよい。
 
-コンテキストに読み込まれることを意図せず、Claudeが生成する出力で使用されるファイル。
+**主要パターン:**
+- SKILL.mdは500行以内に抑える。この制限に近づいたら追加の階層を設け、モデルが次にどこを参照すべきか明確に示す
+- referenceファイルをSKILL.mdから明確に参照し、いつ読むべきか記載
+- 大きなreferenceファイル（300行超）には目次を含める
 
-- **含めるべき場合**: 最終出力で使用されるファイルが必要な場合
-- **例**: ブランドアセットのための `assets/logo.png`、PowerPointテンプレートのための `assets/slides.pptx`、HTML/Reactボイラープレートのための `assets/frontend-template/`、タイポグラフィのための `assets/font.ttf`
-- **使用例**: テンプレート、画像、アイコン、ボイラープレートコード、フォント、コピーまたは修正されるサンプルドキュメント
-- **利点**: 出力リソースとドキュメントを分離し、Claudeがコンテキストに読み込まずにファイルを使用可能
+**ドメイン別整理**: Skillが複数ドメイン/フレームワークをサポートする場合、バリエーションごとに整理：
 
-#### Skillに含めるべきでないもの
+```
+cloud-deploy/
+├── SKILL.md（ワークフロー + 選択）
+└── references/
+    ├── aws.md
+    ├── gcp.md
+    └── azure.md
+```
 
-Skillには、その機能を直接サポートする必須ファイルのみを含めるべきです。以下のような余分なドキュメントや補助ファイルは作成しないでください：
+Claudeは関連するreferenceファイルのみ読む。
 
-- README.md
-- INSTALLATION_GUIDE.md
-- QUICK_REFERENCE.md
-- CHANGELOG.md
-- その他
+#### 驚きのない原則
 
-Skillには、AIエージェントが手元のジョブを実行するために必要な情報のみを含めるべきです。作成プロセス、セットアップおよびテスト手順、ユーザー向けドキュメントなどの補助的なコンテキストを含めるべきではありません。追加のドキュメントファイルを作成すると、混乱を招きます。
+Skillにマルウェア、エクスプロイトコード、システムセキュリティを侵害する可能性のあるコンテンツを含めてはならない。誤解を招くSkillや、不正アクセス、データ窃取、その他の悪意のある活動を助長するSkillの作成に協力しないこと。「XYZとしてロールプレイ」のようなものはOK。
 
-### 段階的開示設計原則
+#### 参考ドキュメントの記録
 
-Skillは、コンテキストを効率的に管理するために3レベルの読み込みシステムを使用します：
+Skill作成時に参考にした公式ドキュメント、ベースとなるSkill、設計判断の根拠となった情報源をSKILL.md内にHTMLコメントで記載する。
 
-1. **メタデータ（name + description）** - 常にコンテキスト内（~100語）
-2. **SKILL.md本文** - スキルトリガー時（<5k語）
-3. **バンドルリソース** - Claudeが必要に応じて（無制限。スクリプトはコンテキストウィンドウに読み込まずに実行可能）
+**記載箇所**: フロントマター（`---`）直後
 
-#### 段階的開示パターン
+**フォーマット**:
+```
+<!-- 参考: https://example.com/docs/feature -->
+<!-- ベース: .claude/skills/existing-skill/SKILL.md -->
+```
 
-SKILL.md本文は要点に絞り、500行以内に抑えてコンテキストの肥大化を最小限に抑えます。この制限に近づいたらコンテンツを別ファイルに分割します。コンテンツを他のファイルに分割する際は、SKILL.mdから参照し、いつ読むべきかを明確に記述することが非常に重要です。これにより、スキルの読者がそれらが存在し、いつ使用すべきかを知ることができます。
+これにより、Skillの設計根拠を後から追跡でき、公式仕様の変更時に影響範囲を特定しやすくなる。
 
-**重要な原則**: Skillが複数のバリエーション、フレームワーク、オプションをサポートする場合、SKILL.mdにはコアワークフローと選択ガイダンスのみを保持します。バリエーション固有の詳細（パターン、例、設定）は別のreferenceファイルに移動します。
+#### 記述パターン
 
-**パターン1: リファレンス付きの高レベルガイド**
+指示には命令形を使用する。
 
+**出力フォーマットの定義** - 例：
 ```markdown
-# PDF Processing
-
-## クイックスタート
-
-pdfplumberでテキスト抽出:
-[コード例]
-
-## 高度な機能
-
-- **フォーム入力**: 完全ガイドは [FORMS.md](FORMS.md) を参照
-- **APIリファレンス**: すべてのメソッドは [REFERENCE.md](REFERENCE.md) を参照
-- **例**: 一般的なパターンは [EXAMPLES.md](EXAMPLES.md) を参照
+## レポート構造
+常にこのテンプレートを使用：
+# [タイトル]
+## エグゼクティブサマリー
+## 主要な発見
+## 推奨事項
 ```
 
-ClaudeはFORMS.md、REFERENCE.md、またはEXAMPLES.mdを必要な場合のみ読み込みます。
+**例のパターン** - 例を含めると有用：
+```markdown
+## コミットメッセージフォーマット
+**例1:**
+入力: Added user authentication with JWT tokens
+出力: feat(auth): implement JWT-based authentication
+```
 
-**パターン2: ドメイン固有の構成**
+### 記述スタイル
 
-複数のドメインを持つSkillの場合、無関係なコンテキストの読み込みを避けるためにドメインごとにコンテンツを整理します：
+重苦しい必須語句（MUST）の代わりに、物事がなぜ重要かをモデルに説明する。心の理論を使い、Skillを一般的で、特定の例に狭くなりすぎないようにする。ドラフトを書き、新鮮な目で見直して改善する。
 
-```
-bigquery-skill/
-├── SKILL.md (概要とナビゲーション)
-└── references/
-    ├── finance.md (収益、請求メトリクス)
-    ├── sales.md (商談、パイプライン)
-    ├── product.md (API使用、機能)
-    └── marketing.md (キャンペーン、アトリビューション)
-```
+### テストケース
 
-ユーザーが販売メトリクスについて質問すると、Claudeはsales.mdのみを読みます。
+Skillドラフト作成後、2-3のリアルなテストプロンプトを作成 — 実際のユーザーが言いそうなもの。ユーザーに共有：「テストケースをいくつか考えました。これで良いですか？追加したいものはありますか？」そして実行する。
 
-同様に、複数のフレームワークやバリエーションをサポートするスキルの場合、バリエーションごとに整理します：
+テストケースを`evals/evals.json`に保存。アサーションはまだ書かない — プロンプトのみ。アサーションは実行中に次のステップで作成する。
 
+```json
+{
+  "skill_name": "example-skill",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "ユーザーのタスクプロンプト",
+      "expected_output": "期待される結果の説明",
+      "files": []
+    }
+  ]
+}
 ```
-cloud-deploy/
-├── SKILL.md (ワークフロー + プロバイダー選択)
-└── references/
-    ├── aws.md (AWSデプロイパターン)
-    ├── gcp.md (GCPデプロイパターン)
-    └── azure.md (Azureデプロイパターン)
-```
-
-ユーザーがAWSを選択すると、Claudeはaws.mdのみを読みます。
 
-**パターン3: 条件付き詳細**
+全スキーマは`references/schemas.md`を参照（アサーションフィールドを含む）。
 
-基本コンテンツを表示し、高度なコンテンツにリンク：
-
-```markdown
-# DOCX Processing
+## テストケースの実行と評価
 
-## ドキュメント作成
+このセクションは一連の連続したシーケンス — 途中で止めないこと。`/skill-test`やその他のテスティングスキルは使用しないこと。
 
-新しいドキュメントにはdocx-jsを使用。[DOCX-JS.md](DOCX-JS.md) を参照。
+結果は`<skill-name>-workspace/`にスキルディレクトリの兄弟として配置。ワークスペース内はイテレーションごとに整理（`iteration-1/`、`iteration-2/`等）、その中に各テストケースのディレクトリ（`eval-0/`、`eval-1/`等）。事前にすべて作成する必要はない — 進行に応じて作成。
 
-## ドキュメント編集
+### ステップ1: 全実行（with-skill AND ベースライン）を同じターンで起動
 
-簡単な編集には、XMLを直接修正。
+各テストケースに対して、同じターンで2つのサブエージェントを起動 — 1つはSkill付き、1つはSkillなし。重要：with-skill実行を先にすべて起動してからベースラインに戻るのではなく、すべてを一度に起動してほぼ同時に完了するようにする。
 
-**変更履歴の場合**: [REDLINING.md](REDLINING.md) を参照
-**OOXMLの詳細**: [OOXML.md](OOXML.md) を参照
+**With-skill実行:**
 ```
+このタスクを実行:
+- Skillパス: <path-to-skill>
+- タスク: <evalプロンプト>
+- 入力ファイル: <evalファイル、またはなし>
+- 出力保存先: <workspace>/iteration-<N>/eval-<ID>/with_skill/outputs/
+- 保存する出力: <ユーザーが気にするもの>
+```
+
+**ベースライン実行**（同じプロンプト、コンテキストに応じたベースライン）：
+- **新規Skill作成**: Skillなし。同じプロンプト、Skillパスなし、`without_skill/outputs/`に保存
+- **既存Skill改善**: 旧バージョン。編集前にスナップショット（`cp -r <skill-path> <workspace>/skill-snapshot/`）、ベースラインサブエージェントをスナップショットに向ける。`old_skill/outputs/`に保存
 
-Claudeは、ユーザーがそれらの機能を必要とする場合のみREDLINING.mdまたはOOXML.mdを読みます。
+各テストケースに`eval_metadata.json`を作成（アサーションは空でよい）。各evalにテスト内容を説明する名前を付ける。
 
-**重要なガイドライン**:
+### ステップ2: 実行中にアサーションをドラフト
 
-- **深くネストされた参照を避ける** - 参照はSKILL.mdから1レベル深く保つ。すべてのreferencesファイルはSKILL.mdから直接リンクする。
-- **長いreferencesファイルの構造化** - 100行を超えるファイルの場合、プレビュー時にClaudeが全体のスコープを見ることができるよう、冒頭に目次を含める。
+実行完了を待つだけでなく、この時間を有効活用。各テストケースの定量的アサーションをドラフトし、ユーザーに説明する。
 
-## Skill作成プロセス
+良いアサーションは客観的に検証可能で、説明的な名前を持つ — ベンチマークビューアで一目で何をチェックしているか分かるべき。主観的なSkill（文体、デザイン品質）は定性的評価が適切 — 人間の判断が必要なものにアサーションを強制しない。
 
-Skill作成には以下のステップが含まれます：
+### ステップ3: 実行完了時にタイミングデータをキャプチャ
 
-1. 具体例でスキルを理解する
-2. 再利用可能なスキルコンテンツを計画する（scripts、reference、assets）
-3. スキルを初期化する（init_skill.py実行）
-4. スキルを編集する（リソースを実装し、SKILL.mdを記述）
-5. スキルをパッケージ化する（package_skill.py実行）
-6. 実際の使用に基づいて反復改善する
+各サブエージェントタスク完了時、通知に`total_tokens`と`duration_ms`が含まれる。**このデータを即座に`timing.json`に保存**すること — タスク通知は1回限りで、後からバッチ処理できない：
 
-これらのステップに順番に従ってください。適用されない明確な理由がある場合のみスキップしてください。
+```json
+{
+  "total_tokens": 84852,
+  "duration_ms": 23332,
+  "total_duration_seconds": 23.3
+}
+```
 
-### ステップ1: 具体例でスキルを理解する
+### ステップ4: 採点、集計、ビューア起動
 
-スキルの使用パターンがすでに明確に理解されている場合のみ、このステップをスキップしてください。既存のスキルで作業している場合でも有益です。
+全実行完了後：
 
-効果的なスキルを作成するには、スキルがどのように使用されるかの具体例を明確に理解します。この理解は、直接のユーザー例またはユーザーフィードバックで検証された生成例のいずれかから得られます。
+1. **各実行を採点** — 採点サブエージェントを起動し`agents/grader.md`を読ませて各アサーションを出力に対して評価。`grading.json`に保存。grading.jsonの期待値配列は `text`、`passed`、`evidence` フィールドを使用すること（`name`/`met`/`details` やその他のバリアントは不可 — ビューアがこの正確なフィールド名に依存している）。プログラムでチェック可能なアサーションは、目視ではなくスクリプトを書いて実行。
 
-例えば、image-editorスキルを構築する場合、関連する質問には以下が含まれます：
+2. **ベンチマークに集計** — skill-creatorディレクトリから集計スクリプトを実行：
+   ```bash
+   python -m scripts.aggregate_benchmark <workspace>/iteration-N --skill-name <name>
+   ```
+   各with_skillバージョンをベースライン対応の前に配置。
 
-- 「image-editorスキルはどのような機能をサポートすべきですか？編集、回転、その他？」
-- 「このスキルがどのように使用されるかの例を教えてください」
-- 「『この画像から赤目を除去』や『この画像を回転』のようなユーザーのリクエストを想像できます。このスキルが使用される他の方法はありますか？」
-- 「このスキルをトリガーするためにユーザーは何と言うでしょうか？」
+3. **アナリストパスを実行** — ベンチマークデータを読み、集計統計が隠すパターンを表面化。`agents/analyzer.md`の「ベンチマーク結果の分析」セクションを参照。
 
-ユーザーを圧倒しないように、1つのメッセージで多くの質問をすることを避けてください。最も重要な質問から始め、効果を高めるために必要に応じてフォローアップします。
+4. **ビューアを起動** — 定性的出力と定量的データの両方で：
+   ```bash
+   nohup python <skill-creator-path>/eval-viewer/generate_review.py \
+     <workspace>/iteration-N \
+     --skill-name "my-skill" \
+     --benchmark <workspace>/iteration-N/benchmark.json \
+     > /dev/null 2>&1 &
+   VIEWER_PID=$!
+   ```
+   イテレーション2以降は`--previous-workspace <workspace>/iteration-<N-1>`も渡す。
 
-スキルがサポートすべき機能について明確な感覚が得られたら、このステップを終了します。
+   **Cowork / ヘッドレス環境:** `webbrowser.open()`が利用不可の場合、`--static <output_path>`でスタンドアロンHTMLファイルを書き出す。
 
-### ステップ2: 再利用可能なスキルコンテンツの計画
+注意: ビューア生成にはgenerate_review.pyを使用すること。カスタムHTMLを書く必要はない。
 
-具体例を効果的なスキルに変えるために、各例を以下のように分析します：
+5. **ユーザーに伝える** — 「ブラウザで結果を開きました。'Outputs'タブで各テストケースをクリックしてフィードバックを残せます。'Benchmark'タブで定量的比較が見られます。完了したらお知らせください。」
 
-1. ゼロから例を実行する方法を検討
-2. これらのワークフローを繰り返し実行する際に役立つscripts、reference、assetsを特定
+### ステップ5: フィードバックの読み込み
 
-例：「このPDFを回転してください」のようなクエリを処理するために`pdf-editor`スキルを構築する場合、分析は以下を示します：
+ユーザーが完了を告げたら、`feedback.json`を読む：
 
-1. PDFを回転するには毎回同じコードを書き直す必要がある
-2. スキルに保存する `scripts/rotate_pdf.py` スクリプトが役立つ
+```json
+{
+  "reviews": [
+    {"run_id": "eval-0-with_skill", "feedback": "チャートに軸ラベルがない", "timestamp": "..."},
+    {"run_id": "eval-1-with_skill", "feedback": "", "timestamp": "..."},
+    {"run_id": "eval-2-with_skill", "feedback": "完璧、気に入った", "timestamp": "..."}
+  ],
+  "status": "complete"
+}
+```
 
-例：「Todoアプリを作って」や「歩数を追跡するダッシュボードを作って」のようなクエリのために`frontend-webapp-builder`スキルを設計する場合、分析は以下を示します：
+空のフィードバックはユーザーがOKと判断したことを意味する。具体的な指摘があるテストケースに改善を集中する。
 
-1. フロントエンドWebアプリを書くには毎回同じボイラープレートHTML/Reactが必要
-2. ボイラープレートHTML/Reactプロジェクトファイルを含む `assets/hello-world/` テンプレートがスキルに保存すると役立つ
+ビューアサーバーが不要になったらkillする。
 
-例：「今日何人のユーザーがログインしましたか？」のようなクエリを処理するために`big-query`スキルを構築する場合、分析は以下を示します：
+---
 
-1. BigQueryをクエリするには毎回テーブルスキーマとリレーションシップを再発見する必要がある
-2. テーブルスキーマをドキュメント化する `references/schema.md` ファイルがスキルに保存すると役立つ
+## Skillの改善
 
-スキルのコンテンツを確立するために、各具体例を分析して、含めるべき再利用可能なリソースのリストを作成します：scripts、reference、assets。
+ループの核心。テストケースを実行し、ユーザーが結果をレビューし、フィードバックに基づいてSkillを改善する。
 
-### ステップ3: スキルの初期化
+### 改善の考え方
 
-この時点で、実際にスキルを作成します。
+1. **フィードバックから汎化する。** ここでの大きな絵は、何百万回も使われるSkillを作ろうとしていること。少数の例で反復するのは速く進むためだが、それらの例にのみ機能するSkillは無用。こまごまとした過学習的な変更や、圧倒的に制約の多いMUSTの代わりに、異なるメタファーや作業パターンを試みる。
 
-開発中のスキルがすでに存在し、反復またはパッケージ化が必要な場合のみ、このステップをスキップしてください。その場合は次のステップに進んでください。
+2. **プロンプトをスリムに保つ。** 効果のないものを削除。トランスクリプトを読み（最終出力だけでなく）、Skillがモデルに非生産的なことをさせていたら、該当部分を削除して結果を見る。
 
-新しいスキルをゼロから作成する場合は、常に `init_skill.py` スクリプトを実行してください。このスクリプトは、スキルが必要とするすべてを自動的に含む新しいテンプレートスキルディレクトリを便利に生成し、スキル作成プロセスをはるかに効率的かつ信頼性の高いものにします。
+3. **理由を説明する。** モデルに何かをさせる理由の「なぜ」を説明する。今日のLLMは賢い。良いハーネスがあれば機械的な指示を超えて本当に成果を出せる。ALWAYS/NEVERを全大文字で書いている場合、それは黄色信号。
 
-使用法：
+4. **テストケース間の重複作業を探す。** テスト実行のトランスクリプトを読み、サブエージェントが独立して同様のヘルパースクリプトを書いたか確認。3つのテストケースすべてでサブエージェントが`create_docx.py`を書いていたら、Skillにそのスクリプトをバンドルすべき強いシグナル。
 
-```bash
-scripts/init_skill.py <skill-name> --path <output-directory>
-```
+### 反復ループ
 
-スクリプトは：
+1. 改善をSkillに適用
+2. 全テストケースを新しい`iteration-<N+1>/`ディレクトリに再実行（ベースライン含む）
+3. `--previous-workspace`で前のイテレーションを指定してレビューアを起動
+4. ユーザーのレビュー完了を待つ
+5. 新しいフィードバックを読み、改善を繰り返す
 
-- 指定されたパスにスキルディレクトリを作成
-- 適切なフロントマターとTODOプレースホルダーを持つSKILL.mdテンプレートを生成
-- 例のリソースディレクトリを作成：`scripts/`、`references/`、`assets/`
-- カスタマイズまたは削除可能な各ディレクトリに例のファイルを追加
+以下で終了：
+- ユーザーが満足
+- フィードバックがすべて空（すべて良好）
+- 意味のある進歩がない
 
-初期化後、生成されたSKILL.mdと例のファイルを必要に応じてカスタマイズまたは削除します。
+---
 
-### ステップ4: スキルの編集
+## 高度: ブラインド比較
 
-（新しく生成された、または既存の）スキルを編集する際、スキルは別のClaudeインスタンスが使用するために作成されていることを忘れないでください。Claudeにとって有益で自明でない情報を含めてください。別のClaudeインスタンスがこれらのタスクをより効果的に実行するのに役立つ手続き的知識、ドメイン固有の詳細、または再利用可能なアセットを検討してください。
+2つのバージョンのより厳密な比較が必要な場合（例：「新バージョンは本当に良くなったか？」）、ブラインド比較システムがある。`agents/comparator.md`と`agents/analyzer.md`を参照。基本的な考え方：2つの出力をどちらが由来かを伝えずに独立エージェントに渡し、品質を判定させる。
 
-#### 実証済みデザインパターンを学ぶ
+オプション、サブエージェントが必要、ほとんどのユーザーには不要。人間のレビューループで通常は十分。
 
-スキルのニーズに基づいて、これらの有用なガイドを参照してください：
+---
 
-- **複数ステップのプロセス**: シーケンシャルワークフローと条件付きロジックについては references/workflows.md を参照
-- **特定の出力形式または品質基準**: テンプレートと例のパターンについては references/output-patterns.md を参照
+## Description最適化
 
-これらのファイルには、効果的なスキル設計のための確立されたベストプラクティスが含まれています。
+SKILL.mdフロントマターのdescriptionフィールドは、ClaudeがSkillを呼び出すかどうかを決定する主要メカニズム。Skill作成・改善後、トリガー精度を最適化するdescription改善を提案する。
 
-#### 再利用可能なスキルコンテンツから始める
+### ステップ1: トリガー評価クエリの生成
 
-実装を開始するには、上記で特定した再利用可能なリソースから始めます：`scripts/`、`references/`、`assets/` ファイル。このステップにはユーザー入力が必要な場合があります。例えば、`brand-guidelines`スキルを実装する場合、ユーザーは`assets/`に保存するブランドアセットやテンプレート、または`references/`に保存するドキュメントを提供する必要があります。
+20個の評価クエリを作成 — トリガーすべきものとすべきでないものの混合。JSONとして保存。
 
-追加されたスクリプトは、バグがないこと、出力が期待どおりであることを確認するために実際に実行してテストする必要があります。多くの類似したスクリプトがある場合、すべてが機能することを確信しながら完了までの時間とのバランスを取るために、代表的なサンプルのみをテストする必要があります。
+クエリは現実的で、Claude CodeやClaude.aiユーザーが実際にタイプするもの。抽象的ではなく、具体的で詳細なリクエスト。ファイルパス、個人的なコンテキスト、カラム名、会社名、URL等。少しの背景。一部は小文字や略語やタイプミスやカジュアルな話し方。長さを混ぜ、明確なケースよりエッジケースに焦点。
 
-スキルに必要のない例のファイルとディレクトリは削除する必要があります。初期化スクリプトは構造を示すために`scripts/`、`references/`、`assets/`に例のファイルを作成しますが、ほとんどのスキルはそれらすべてを必要としません。
+**Bad**: `"Format this data"`, `"Extract text from PDF"`, `"Create a chart"` — 抽象的すぎて何もテストしない
 
-#### SKILL.mdの更新
+**Good**: `"ok so my boss just sent me this xlsx file (its in my downloads, called something like 'Q4 sales final FINAL v2.xlsx') and she wants me to add a column that shows the profit margin as a percentage. The revenue is in column C and costs are in column D i think"` — 具体的、カジュアル、背景あり
 
-**記述ガイドライン**: 常に命令形/不定詞形を使用してください。
+**トリガーすべき**クエリ（8-10個）はカバレッジを考える。異なるフレーズ、フォーマル/カジュアル混在、スキル名を明示しないが明らかに必要なケース、珍しいユースケース。**トリガーすべきでない**クエリ（8-10個）はニアミス — キーワードを共有するが実際には異なるものが必要なクエリ。「フィボナッチ関数を書いて」のような明らかに無関係なクエリは避ける — テストにならない。
 
-##### フロントマター
+### ステップ2: ユーザーとレビュー
 
-`name`と`description`を持つYAMLフロントマターを記述します：
+HTMLテンプレートで評価セットをユーザーに提示：
 
-- `name`: スキル名
-- `description`: これはスキルの主要なトリガーメカニズムであり、Claudeがいつスキルを使用するかを理解するのに役立ちます。
-  - Skillが何をするか、使用するための特定のトリガー/コンテキストの両方を含めます。
-  - すべての「使用すべき場合」情報をここに含めてください - 本文ではありません。本文はトリガー後にのみ読み込まれるため、本文の「このスキルを使用すべき場合」セクションはClaudeにとって役立ちません。
-  - `docx`スキルの例の説明: "変更履歴、コメント、書式保持、テキスト抽出をサポートする包括的なドキュメント作成、編集、分析。Claudeが専門的なドキュメント（.docxファイル）で作業する必要がある場合に使用：(1) 新しいドキュメントの作成、(2) コンテンツの変更または編集、(3) 変更履歴の操作、(4) コメントの追加、またはその他のドキュメントタスク"
+1. `assets/eval_review.html`のテンプレートを読む
+2. プレースホルダーを置換：
+   - `__EVAL_DATA_PLACEHOLDER__` → 評価項目のJSON配列
+   - `__SKILL_NAME_PLACEHOLDER__` → Skill名
+   - `__SKILL_DESCRIPTION_PLACEHOLDER__` → 現在のdescription
+3. 一時ファイルに書き出してブラウザで開く
+4. ユーザーが編集し「Export Eval Set」をクリック
 
-YAMLフロントマターに他のフィールドを含めないでください。
+### ステップ3: 最適化ループの実行
 
-##### 本文
+バックグラウンドで実行：
 
-スキルとそのバンドルリソースを使用するための指示を記述します。
+```bash
+python -m scripts.run_loop \
+  --eval-set <path-to-trigger-eval.json> \
+  --skill-path <path-to-skill> \
+  --model <model-id-powering-this-session> \
+  --max-iterations 5 \
+  --holdout 0.4 \
+  --verbose
+```
 
-##### 言語の考慮事項
+セッションのモデルIDを使用（`--model`）。`--holdout 0.4`（デフォルト）で60% train / 40% test分割。各クエリ3回実行で信頼性のあるトリガー率を取得。extended thinkingのClaudeで改善を提案（改善専用モデルは`--improve-model`で変更可）。train/testの両方で再評価し、最大5回反復。テストスコアは改善モデルに見せない（blinded_history）ため過学習を防止。完了時にHTMLレポートをブラウザで自動起動し、`best_description`をJSONで返す。`--results-dir <dir>`で全出力をタイムスタンプ付きサブディレクトリに保存可能。
 
-スキルの言語をプロジェクトの主要言語に合わせます：
+### スキルトリガーの仕組み
 
-1. プロジェクト設定で言語設定を確認：`CLAUDE.md`、`.kiro/steering/`、または `spec.json` ファイル
-2. SKILL.md本文はプロジェクトの主要言語で記述
-3. フロントマター`description`：主要な説明はプロジェクトの主要言語を使用しますが、チームが使用する他の言語で重要なトリガーフレーズを含めます（バイリンガル説明はトリガーの失敗を防ぎます）
-4. referenceファイルと出力テンプレートもプロジェクトの言語に従うべき
-5. 技術用語（API名、ツール名、ファイル形式）はプロジェクト言語に関係なく英語のままで構いません
+SkillはClaudeの`available_skills`リストにname + descriptionで表示される。Claudeは自力で簡単に処理できるタスクにはSkillを参照しない。複雑で複数ステップの専門的なクエリはdescriptionが一致するとSkillを確実にトリガーする。評価クエリはSkillの参照が有益なほど実質的であるべき。
 
-### ステップ5: スキルのパッケージ化
+### ステップ4: 結果の適用
 
-スキルの開発が完了したら、ユーザーと共有される配布可能な.skillファイルにパッケージ化する必要があります。パッケージ化プロセスは、すべての要件を満たしていることを確認するために、まずスキルを自動的に検証します：
+JSON出力の`best_description`をSkillのSKILL.mdフロントマターに更新。ユーザーにbefore/afterを表示しスコアを報告。
 
-```bash
-scripts/package_skill.py <path/to/skill-folder>
-```
+---
 
-オプションの出力ディレクトリ指定：
+### パッケージ化と提示（`present_files`ツールが利用可能な場合のみ）
 
 ```bash
-scripts/package_skill.py <path/to/skill-folder> ./dist
+python -m scripts.package_skill <path/to/skill-folder>
 ```
 
-パッケージ化スクリプトは：
+---
 
-1. **検証**：スキルを自動的に検証し、以下を確認：
+## Claude.ai固有の手順
 
-   - YAMLフロントマター形式と必須フィールド
-   - スキル命名規則とディレクトリ構造
-   - 説明の完全性と品質
-   - ファイル構成とリソース参照
+Claude.aiではサブエージェントがないため、一部の手順を変更する。コアワークフロー（ドラフト→テスト→レビュー→改善→繰り返し）は同じ。
 
-2. **パッケージ化**：検証が通過した場合、スキル名にちなんだ.skillファイル（例：`my-skill.skill`）を作成し、すべてのファイルを含み、配布のための適切なディレクトリ構造を維持します。.skillファイルは.skill拡張子を持つzipファイルです。
+- **テスト実行**: サブエージェントなし＝並列実行不可。各テストケースを順次に自分で実行。これはサブエージェント版より厳密性が低い（スキル作成者がスキル実行者でもあるため完全なコンテキストを持つ）が、有用なサニティチェックであり、人間のレビューステップが補完する。ベースライン実行はスキップ
+- **結果レビュー**: ブラウザが使えない場合、会話内で直接結果を提示。出力がファイルの場合はパスを伝える
+- **ベンチマーク**: スキップ（ベースライン比較がサブエージェントなしでは意味をなさない）
+- **Description最適化**: `claude` CLI（`claude -p`）が必要なためスキップ
+- **ブラインド比較**: サブエージェントが必要。スキップ
 
-検証が失敗した場合、スクリプトはエラーを報告し、パッケージを作成せずに終了します。検証エラーを修正し、パッケージ化コマンドを再度実行します。
+---
 
-### ステップ6: 反復
+## Cowork固有の手順
 
-スキルをテストした後、ユーザーは改善を要求する場合があります。多くの場合、これはスキルを使用した直後、スキルがどのように機能したかの新鮮なコンテキストで発生します。
+- サブエージェントあり、メインワークフロー（テスト並行実行等）は動作する
+- ブラウザがないため、ビューア生成時は`--static <output_path>`を使用
+- フィードバックは`feedback.json`としてダウンロード（ファイルアクセスのリクエストが必要な場合がある）
+- テスト実行後は**必ず**`generate_review.py`で評価ビューアを生成してから自己評価すること
 
-**反復ワークフロー**:
+---
 
-1. 実際のタスクでスキルを使用
-2. 苦労や非効率性に気づく
-3. SKILL.mdまたはバンドルリソースをどのように更新すべきかを特定
-4. 変更を実装し、再度テスト
+## リファレンスファイル
 
-## einja固有の注意事項
+agents/ディレクトリには専門サブエージェントの指示がある。関連サブエージェントを起動する時に読む。
 
-### 命名規約
+- `agents/grader.md` — アサーションの出力に対する評価方法
+- `agents/comparator.md` — 2つの出力のブラインドA/B比較方法
+- `agents/analyzer.md` — 一方が勝った理由の分析方法
 
-einjaプロジェクトでは、Skillには`einja-`プレフィックスを付けることを推奨します。
+references/ディレクトリには追加ドキュメント：
+- `references/schemas.md` — evals.json、grading.json等のJSON構造
 
-例：`einja-coding-standards`、`einja-component-design`、`einja-api-development`
+---
 
-### ディレクトリ構造
+## スキルの初期化（init_skill.py）
 
-einjaでは`references/`（複数形）を使用します。公式仕様に準拠しています。
+新しいSkillをゼロから作成する場合は、`init_skill.py`スクリプトを実行する。
 
+```bash
+scripts/init_skill.py <skill-name> --path <output-directory>
 ```
-einja-skill-name/
-├── SKILL.md
-├── scripts/          # オプション
-├── references/       # 複数形（公式仕様準拠）
-└── assets/           # オプション
-```
-
-### マネージドセクション
 
-einjaの一部のドキュメントは、CLIツールによって自動更新される「マネージドセクション」を使用します。Skillでこれらのパターンを使用する場合：
+## スキルのパッケージ化（package_skill.py）
 
-**マネージドセクション**（CLIツールによる上書き）:
-```markdown
-<!-- @einja:managed:start -->
-この内容は`einja sync`で上書きされる
-<!-- @einja:managed:end -->
+```bash
+scripts/package_skill.py <path/to/skill-folder> [output-directory]
 ```
 
-**シードセクション**（プロジェクト固有の追記）:
-```markdown
-<!-- @einja:seed:start id="unique-id" -->
-プロジェクト固有の内容をここに追記
-<!-- @einja:seed:end -->
-```
+---
+
+コアループの再掲（見落とし防止）：
 
-### ビルドシステム連携
+- Skillの目的を理解する
+- Skillをドラフトまたは編集する
+- テストプロンプトでSkill付きClaudeを実行する
+- ユーザーと共に出力を評価する：
+  - benchmark.jsonを作成し`eval-viewer/generate_review.py`でユーザーレビューを支援
+  - 定量的評価を実施
+- 満足するまで繰り返す
+- 最終Skillをパッケージ化してユーザーに返す
 
-einja management templateでは、`.claude/skills/einja-*/` 内のファイルはビルド時に `presets/default/.claude/skills/einja-*/` に自動的にコピーされます。
+**TodoList**: ステップを見失わないよう、TodoListが利用可能であればステップを追加すること。特にCowork環境では「evalsのJSONを作成し `eval-viewer/generate_review.py` を実行して人間がテストケースをレビューできるようにする」を必ずTodoListに含める。
 
-**重要**: `presets/default/` 内のファイルは直接編集しないでください。ビルド時に上書きされます。
+### 横断比較ツール（compare_runs.py）
 
-### サブエージェント出力形式との連携
+複数スキルの`run_loop.py`出力を横断比較する場合は`compare_runs.py`を使用：
 
-einjaでは、サブエージェントの出力形式が `einja-output-format` Skillで定義されています。サブエージェント用のSkillを作成する場合、この形式テンプレートを参照してください。
+```bash
+python -m scripts.compare_runs result1.json result2.json --verbose --json
+```
 
-詳細は `.claude/skills/einja-output-format/SKILL.md` を参照。
+<!-- @einja:excluded:start -->
+## プロジェクト固有セクションの記入
 
-## 関連ドキュメント
+SKILL.md等のmdファイルの末尾には以下を記入する:
+
+```markdown
+<!-- @einja:project-private:start id="{既存と同じID}" -->
+<!-- プロジェクト固有の情報を記入 -->
+<!-- @einja:project-private:end -->
+```
+<!-- @einja:excluded:end -->
 
-- [einja-output-format](../einja-output-format/SKILL.md) - サブエージェント出力形式
-- [einja-coding-standards](../einja-coding-standards/SKILL.md) - コーディング規約の例
-- [einja-component-design](../einja-component-design/SKILL.md) - コンポーネント設計の例
+<!-- @einja:project-private:start id="einja-skill-creator-project" -->
+<!-- プロジェクト固有の情報を記入 -->
+<!-- @einja:project-private:end -->