sensei

Sensei

「真の師は教え諭すのではなく、磨き上げることで教えます。」

Ralph ループパターンを使用してスキルのフロントマターを自動改善します。テストに合格し、中〜高レベルの準拠度に達するまで、スキルを反復的に改善します。

ヘルプ

ユーザーが「sensei help」と言った場合、または sensei の使い方を尋ねた場合：

╔══════════════════════════════════════════════════════════════════╗
║  SENSEI - Skill Frontmatter Compliance Improver                  ║
╠══════════════════════════════════════════════════════════════════╣
║                                                                  ║
║  USAGE:                                                          ║
║    Run sensei on <skill-name>              # Single skill        ║
║    Run sensei on <skill-name> --fast       # Skip tests          ║
║    Run sensei on <skill1>, <skill2>        # Multiple skills     ║
║    Run sensei on all Low-adherence skills  # Batch by score      ║
║    Run sensei on all skills                # All skills          ║
║                                                                  ║
║  WHAT IT DOES:                                                   ║
║    1. READ    - Load skill's SKILL.md and count tokens           ║
║    2. SCORE   - Check compliance (Low/Medium/Medium-High/High)   ║
║    3. SCAFFOLD- Create tests from template if missing            ║
║    4. IMPROVE - Add WHEN: triggers (cross-model optimized)       ║
║    5. TEST    - Run tests, fix if needed                         ║
║    6. TOKENS  - Check token budget                               ║
║    7. SUMMARY - Show before/after comparison                     ║
║    8. PROMPT  - Ask: Commit, Create Issue, or Skip?              ║
║    9. REPEAT  - Until Medium-High score achieved                 ║
║                                                                  ║
║  TARGET SCORE: Medium-High                                       ║
║    ✓ Description > 150 chars, ≤ 60 words                         ║
║    ✓ Has "WHEN:" trigger phrases (preferred)                     ║
║    ✓ No "DO NOT USE FOR:" (risky in multi-skill envs)             ║
║    ✓ Has "INVOKES:" for tool relationships (optional)            ║
║    ✓ SKILL.md < 500 tokens (soft limit)                          ║
║                                                                  ║
║  MCP INTEGRATION (when INVOKES present):                         ║
║    ✓ Has "MCP Tools Used" table                                  ║
║    ✓ Has Prerequisites section                                   ║
║    ✓ Has CLI fallback pattern                                    ║
║    ✓ No skill-tool name collision                                ║
║                                                                  ║
╚══════════════════════════════════════════════════════════════════╝

設定

Sensei では次のデフォルト値を使用します（プロンプトで指定すると上書きできます）。

設定	デフォルト	説明
スキルディレクトリ	skills/ または .github/skills/	SKILL.md ファイルの保存場所
テストディレクトリ	tests/	テストファイルの保存場所
トークンのソフト上限	500	SKILL.md の目標値
トークンのハード上限	5000	SKILL.md の最大値
目標スコア	中〜高	最低準拠レベル
最大反復回数	5	スキルごとのループ上限

次の順に確認して、スキルディレクトリを自動検出します。

1. プロジェクトルートの skills/
2. .github/skills/
3. ユーザー指定のパス

呼び出しモード

単一スキル

Run sensei on my-skill-name

複数のスキル

Run sensei on skill-a, skill-b, skill-c

準拠レベル別

Run sensei on all Low-adherence skills
Run sensei on all Medium-adherence skills

すべてのスキル

Run sensei on all skills

高速モード（テストをスキップ）

Run sensei on my-skill --fast

GEPA モード（詳細な最適化）

Run sensei on my-skill --gepa
Run sensei on my-skill --gepa --fast
Run sensei on all skills --gepa

--gepa を使用すると、ステップ 5（改善）が GEPA の進化的最適化に置き換わります。 テンプレートベースの改善の代わりに、GEPA は既存のテストハーネスを適合度関数として使用し、 LLM によって多数の改善候補を自動的に提案・評価します。

GEPA のスコアのみモード（LLM の呼び出しなしで、現在の品質だけを評価）：

Run sensei score my-skill
Run sensei score all skills

Ralph ループ

各スキルについて、スコアが中〜高以上になるまで次のループを実行します。

ステップ 1：読み込み

スキルの現在の状態を読み込みます。

{skills-dir}/{skill-name}/SKILL.md
{tests-dir}/{skill-name}/ (if exists)

トークン数をカウントします。

npm run tokens -- count {skills-dir}/{skill-name}/SKILL.md

ステップ 2：スコア付け

フロントマターを確認し、準拠度を評価します。

• 説明の長さ（150 文字以上、60 語以下。目標リポジトリの .sensei.json または AGENTS.md で短いトリガーフレーズが推奨されている場合、最小文字数の要件は免除されます）
• 「WHEN:」トリガーフレーズ（推奨）または「USE FOR:」
• ルーティングの明確さ（「INVOKES:」、「FOR SINGLE OPERATIONS:」）
• 「DO NOT USE FOR:」のアンチトリガーがないこと（複数スキル環境ではリスクがあります）

詳細な基準については、references/scoring.md を参照してください。

ステップ 3：確認

スコアが中〜高以上で、テストに合格した場合は、要約のステップに進みます。

ステップ 4：足場の作成（必要な場合）

{tests-dir}/{skill-name}/ が存在しない場合は、references/test-templates/ のテンプレートを使ってテストの足場を作成します。ツール関連ファイルがないと判断する前に、必ず ls または git ls-files で確認してください。ファイル名だけで判断しないでください。

ステップ 5：フロントマターの改善

SKILL.md の説明を改善し、次の内容を含めます。

1. 動作を表す動詞で始める - 最初の文は、固有の動作を表す動詞 + 分野にします
2. トリガーフレーズ - 「WHEN:」（推奨）または「USE FOR:」に、特徴的な引用符付きフレーズを 3〜5 個指定します
3. 説明は 60 語未満、1024 文字以内にします

⚠️ 「DO NOT USE FOR:」には状況に応じたリスクがあります。 複数のスキルが存在する環境（分野が重複するスキルが 10 個以上）では、アンチトリガー句に、Claude Sonnet や高速なパターンマッチングを行うモデルで誤ったスキルの起動を引き起こすキーワードそのものが含まれます（根拠）。小規模で独立したスキルセット（1〜5 個）では、リスクは低くなります。判断に迷う場合は、「WHEN:」と特徴的な引用符付きフレーズを使った肯定的なルーティングを使用してください。

テンプレート（複数モデル向けに最適化）：

---
name: skill-name
description: "[ACTION VERB] [UNIQUE_DOMAIN]. [One clarifying sentence]. WHEN: \"[phrase1]\", \"[phrase2]\", \"[phrase3]\", \"[phrase4]\", \"[phrase5]\"."
---

テンプレート（高スコア向けの明確なルーティング付き）：

---
name: skill-name
description: "**WORKFLOW SKILL** — [ACTION VERB] [UNIQUE_DOMAIN]. [Clarifying sentence]. WHEN: \"[phrase1]\", \"[phrase2]\", \"[phrase3]\". INVOKES: [tools/MCP servers used]. FOR SINGLE OPERATIONS: [when to bypass this skill]."
---

Step 5-GEPA：GEPA で改善する（--gepa フラグが設定されている場合）

Step 5 を置き換え、進化的最適化を自動で行います。Step 6（テストを改善する）は引き続き通常どおり実行されます。

1. テストハーネスを自動検出する：{tests-dir}/{skill-name}/triggers.test.ts を読み込み、 shouldTriggerPrompts と shouldNotTriggerPrompts の配列を自動的に抽出します。

2. 評価器を構築する：以下の項目で候補を採点する GEPA 評価器を構築します。

   • コンテンツの品質（## Triggers、## Rules、## Steps、USE FOR、WHEN があること）
   • Frontmatter の説明への準拠（長さ、トリガーフレーズ）
   • トリガーの正確さ（説明から抽出したキーワードがテストプロンプトに正しく一致すること）

3. 最適化を実行する：GEPA 自動評価スクリプトを呼び出します。

   python scripts/src/gepa/auto_evaluator.py optimize \
     --skill {skill-name} \
     --skills-dir {skills-dir} \
     --tests-dir {tests-dir} \
     --iterations 80
   

4. 出力を確認する：GEPA は最適化された SKILL.md の本文を生成します。差分をユーザーに表示します。 GEPA 評価器は既存のテストから自動生成されるため、手動での設定は不要です。

重要：GEPA は既存のテストを適応度関数として使用します。テストを置き換えたり変更したりすることはありません。 LLM が改善した SKILL.md のテキストを提案し、評価器が CI で使用されているものと同じテストプロンプトに照らして各候補を採点します。より高いスコアを獲得した改善案のみが採用されます。

Step 6：テストを改善する

新しい frontmatter に合うようにテストプロンプトを更新します。

• shouldTriggerPrompts - 「WHEN:」または「USE FOR:」のフレーズに一致するプロンプトを 5 件以上
• shouldNotTriggerPrompts - 無関係なトピックや別のスキルを使うケースのプロンプトを 5 件以上

Step 7：検証する

テストを実行します（--fast フラグがある場合はスキップします）。

# Framework-specific command based on project
npm test -- --testPathPattern={skill-name}  # Jest
pytest tests/{skill-name}/                   # pytest
waza run tests/{skill-name}/trigger_tests.yaml  # Waza

Step 8：トークン

トークン予算を確認します。

npm run tokens -- check {skills-dir}/{skill-name}/SKILL.md

予算の目安：

• SKILL.md：500 トークン未満（目標）、5000 未満（上限）
• references/*.md：各ファイル 1000 トークン未満

Step 8b：MCP 統合（INVOKES がある場合）

説明に INVOKES: が含まれている場合は、以下を確認します。

1. MCP Tools Used テーブル - スキルの本文にテーブルがあるか
2. Prerequisites セクション - 前提条件が記載されているか
3. CLI フォールバック - MCP が利用できない場合のフォールバックがあるか
4. 名前の競合 - スキル名が MCP ツール名と一致していないか

確認に失敗した場合は、mcp-integration.md のパターンを使って、不足しているセクションを追加します。

Step 9：概要

変更前後の比較を表示します。

╔══════════════════════════════════════════════════════════════════╗
║  SENSEI SUMMARY: {skill-name}                                    ║
╠══════════════════════════════════════════════════════════════════╣
║  BEFORE                          AFTER                           ║
║  ──────                          ─────                           ║
║  Score: Low                      Score: Medium-High              ║
║  Tokens: 142                     Tokens: 385                     ║
║  Triggers: 0                     Triggers: 5                     ║
║  Anti-triggers: 0                Anti-triggers: 3                ║
╚══════════════════════════════════════════════════════════════════╝

Step 10：ユーザーに確認する

次の手順を尋ねます。

• [C] Commit - sensei: improve {skill-name} frontmatter というメッセージで保存する
• [I] Create Issue - 概要と提案を含む Issue を作成する
• [S] Skip - 変更を破棄し、次のスキルに進む

Step 11：繰り返す、または終了する

• スコアが Medium-High 未満で、かつ反復回数が 5 未満の場合 → Step 2 に進む
• 反復回数が 5 以上の場合 → タイムアウトし、概要を表示して次のスキルに進む

スコアのクイックリファレンス

スコア	要件
Invalid	説明が 1024 文字を超える（仕様上のハードリミットを超過）
Low	説明が 150 文字未満、またはトリガーがない
Medium	説明が 150 文字以上でトリガーもあるが、60 語を超える
Medium-High	「WHEN:」（推奨）または「USE FOR:」があり、60 語以下
High	Medium-High に加えて、ルーティングが明確（INVOKES/FOR SINGLE OPERATIONS）

⚠️ 「DO NOT USE FOR:」は複数のスキルがある環境（重複するスキルが 10 個以上）ではリスクがあります。高速なパターンマッチングを行うモデルでは、キーワードの混同が生じるためです。小規模で独立したスキルセットであれば安全です。複数モデル間で安全に使えるよう、「WHEN:」を使った肯定的なルーティングにしてください。

MCP 統合スコア（INVOKES がある場合）

確認項目	状態
MCP Tools Used テーブル	✓/✗
Prerequisites セクション	✓/✗
CLI フォールバックパターン	✓/✗
名前の競合なし	✓/✗

すべての評価基準については、references/scoring.md を参照してください。 MCP のパターンについては、references/mcp-integration.md を参照してください。

Frontmatter のパターン

スキル分類のプレフィックス

スキルの種類を明確にするため、プレフィックスを追加します。

• **WORKFLOW SKILL** - 複数ステップのオーケストレーション
• **UTILITY SKILL** - 単一目的のヘルパー
• **ANALYSIS SKILL** - 読み取り専用の分析・レポート作成

ルーティングの明確化（高スコア向け）

スキルが MCP ツールや他のスキルと連携する場合は、次を追加します。

• INVOKES: - このスキルが呼び出すツール／スキル
• FOR SINGLE OPERATIONS: - このスキルを介さずに実行する場合

簡単な例

変更前（低スコア）：

description: 'Process PDF files'

変更後（ルーティング対応、クロスモデル向けに最適化、高スコア）：

description: "**WORKFLOW SKILL** — Extract, rotate, merge, and split PDF files. WHEN: \"extract PDF text\", \"rotate PDF pages\", \"merge PDFs\", \"split PDF\". INVOKES: pdf-tools MCP for extraction, file-system for I/O. FOR SINGLE OPERATIONS: Use pdf-tools MCP directly for simple extractions."

変換の変更前／変更後の例については、references/examples.md を参照してください。

コミットメッセージ

sensei: improve {skill-name} frontmatter

リファレンスドキュメント

• scoring.md - 詳細なスコアリング基準とアルゴリズム
• mcp-integration.md - MCP ツールの統合パターン
• loop.md - Ralph ループのワークフローの詳細
• examples.md - 変換の変更前／変更後の例
• configuration.md - プロジェクトのセットアップパターン
• test-templates/ - テストの雛形テンプレート
• test-templates/waza.md - Waza トリガーテスト形式

組み込みスクリプト

使い方の詳細については、npm run tokens help を実行してください。

トークンコマンド

npm run tokens count              # Count all markdown files
npm run tokens check              # Check against token limits
npm run tokens suggest            # Get optimization suggestions
npm run tokens compare            # Compare with git history

GEPA コマンド

必要なもの：pip install gepa（または uv pip install gepa）。requirements を参照してください。

# Score a single skill (no LLM calls, instant)
python scripts/src/gepa/auto_evaluator.py score --skill azure-deploy --skills-dir skills --tests-dir tests

# Score all skills
python scripts/src/gepa/auto_evaluator.py score-all --skills-dir skills --tests-dir tests

# Optimize a skill (requires LLM API — uses GitHub Models via gh auth token)
python scripts/src/gepa/auto_evaluator.py optimize --skill azure-deploy --skills-dir skills --tests-dir tests

# JSON output (for CI pipelines)
python scripts/src/gepa/auto_evaluator.py score-all --skills-dir skills --tests-dir tests --json

設定

制限をカスタマイズするには、.token-limits.json を作成します。

{
  "defaults": { "SKILL.md": 500, "references/**/*.md": 1000 },
  "overrides": { "README.md": 3000 }
}