skill-system-router

スキルシステムルーター

非推奨の互換性用インターフェースです。skill-system-cli が、sk で使用されるルーターのランタイムモジュールを担うようになりました。このスキルは、移行期間中に既存のルータードキュメント、ポリシー参照、レガシーのエントリーポイントが機能し続けるよう、引き続き利用可能です。

あなたはルーターです。このスキルでは、他のスキルをオーケストレーションする方法を説明します。

ルーターは内部オーケストレーションレイヤーです。ユーザー向けの公開エントリーポイントは、引き続き skill-system-cli の sk です。

動作の仕組み

User goal → Read skills-index.json → Match capabilities → Read skill manifest
→ (Complex goal: plan with workflow) → Check policy → Execute entrypoints → Parse JSON output → Decide next step → Log

ステップ 0：インストーラーのブートストラップ確認（初回のみ）

プロジェクトの AGENTS.md に ## Skill System が含まれているか確認します。

• 見つかった場合：ステップ 1 に進みます（ブートストラップ済みです）。
• 見つからない場合：skill-system-installer のブートストラップを使って、スキルシステムをプロジェクトに足場を作成して組み込みます。

ブートストラップは skill-system-installer が担います。ブートストラップ後は、以降のセッションで AGENTS.md を読み込むことで、スキルシステムが自動的に認識されます。

ステップ 1：スキルを検出する

スキルのルートディレクトリ（スキルフォルダーと同じ階層）にある skills-index.json を読み込み、利用可能な機能を確認します。

インデックスには、機能とスキルの対応関係、および各スキルの操作、説明、入力パラメーターが記載されています。ユーザーの目標に合う機能を特定します。一致するものがない場合は、目標をサブ機能に分解できるか確認します。

目標が複数のステップにわたる、曖昧である、または 3 つ以上の操作が必要になりそうな場合は、まず plan-with-workflow を使ってワークフローの計画を行います。

skills-index.json が存在しないか古い場合は、再生成します。

bash "<this-skill-dir>/scripts/build-index.sh"

powershell.exe -NoProfile -ExecutionPolicy Bypass -File "<this-skill-dir>\scripts\build-index.ps1"

セッションガード

必須のルーター優先スタートアップ：セッション開始時に、ルーター以外のスキルより先にこのスキルを読み込む必要があります。これはフェイルクローズのガードです。

1. 最初に skill-system-router を読み込みます。
2. guard-check 操作を実行します。
3. guard-check が成功していない場合：ルーター以外のすべてのスキルの読み込みをブロックし、次の失敗メッセージを出力します。

   Router guard failed: load skill-system-router and complete router discovery before using non-router skills.

4. guard-check が成功した後に限り、ルーター以外のスキルに進みます。

この適用は必須です。ユーザーがルーター以外のスキルを直接要求した場合も、先にルーターを読み込み、ガードを完了してから進む必要があります。

ガード失敗時の動作：

• router_checked フラグがない場合：ルーター以外のスキルをブロックし、メッセージを表示して検出を実行します。

• skills-index.json が存在しないか古い場合：ガード完了とする前に再構築します。

• メモリを使ったフラグが推奨されます：session_id を含む router_checked=true。

• 手順：scripts/session-guard-check.md

ステップ 2：スキルマニフェストを読む

対象スキルの SKILL.md を開き、フェンス付きブロック `skill-manifest` を探します。ここには以下が記載されています。

• operations：スキルで実行できること、および入力／出力スキーマ
• effects：副作用（ポリシー確認で使用）
• entrypoints：OS 固有の実行コマンド

マニフェスト仕様の全文：references/manifest-spec.md

設定

ランタイム設定は config/router.yaml にあります。設定が唯一の信頼できる情報源です。

参照先：../../config/router.yaml

ステップ 3：ポリシーを確認する

実行前に、スキルで宣言された effects が有効なポリシープロファイルに適合していることを確認します。

SELECT allowed_effects FROM skill_system.policy_profiles WHERE name = 'dev';

• すべての効果が allowed_effects に含まれる場合 → 続行します
• allowed_effects に含まれない効果が 1 つでもある場合 → 続行する前にユーザーに確認します
• ポリシープロファイルが存在しない場合 → ユーザーに確認します

report-improvement-issue のポリシーに関する注記：

• 常に必要：proc.exec、net.fetch
• repo が省略され、git remote から推定される場合は、git.read も必要です

標準的な効果：db.read、db.write、proc.exec、fs.read、fs.write、net.fetch、git.read、git.write

内部ポリシーヘルパー scripts/router.py check-policy は、呼び出し元が許可／拒否の具体的な理由を提示できるよう、構造化された policy_decisions リストを返します。 skill_system.policy_profiles が利用できない場合、ヘルパーは config/router.yaml の policy.default_allowed_effects にフォールバックし、 出力でそのフォールバックを明示的に報告します。

ステップ 4：実行

1. OS を判定します：OS 環境変数が Windows_NT の場合は windows エントリーポイントを使用し、それ以外の場合は unix を使用します
2. お使いの OS に対応する操作の entrypoints を読み取ります
3. {param} プレースホルダーを実際の値に置き換えます
4. 作業ディレクトリをスキルのディレクトリに設定します
5. コマンドを実行します
6. stdout の最後の行を JSON として解析します。これが結果です

終了コードが 0 以外、または最後の行が JSON でない場合、操作は失敗です。

ステップ 5：操作を連鎖させる

目標の達成に複数のスキル／操作が必要な場合：

1. 最初の操作を実行し、JSON 出力を解析します
2. 出力値を次の操作の入力として使用します（値の対応付けは自分で判断します）
3. 目標を達成するまで繰り返します

あなたは賢く、途中の結果に応じて対応できます。エラーへの対処、不要な手順の省略、状況に即した判断ができるため、固定されたパイプラインよりも優れています。

ステップ 5.5：オーケストレーションの呼び出しチェーン（Router → TKT → Workflow）

複数のエージェントによる連携が必要な複雑な目標では、ルーターが次の 3 層をオーケストレーションします：

1. Router identifies TKT-worthy goal
2. TKT.create-bundle → decomposes into tickets (000 + workers + audit)
3. Workflow.plan → orders tickets into a DAG with dependency waves
4. Router dispatches each ticket's skill execution by wave order
5. TKT.update / TKT.close → tracks results and triggers review

判定マトリクス：

目標の種類	経路
単一スキル、単純な処理	直接実行（ステップ 4）
複数ステップ、単一セッション	Workflow.plan → ウェーブごとに実行
複数エージェント、セッション横断	TKT.create-bundle → Workflow.plan → 実行 → TKT.close

Workflow のみで計画する場合（TKT なし）は、scripts/plan-with-workflow.md を使用します。 TKT と統合して計画する場合は、上記の呼び出しチェーンを使用します。

ステップ 6：ログを記録する（可観測性）

複雑なワークフローの後は、可観測性のためにログを記録します：

INSERT INTO skill_system.runs(task_spec_id, status, started_at, effective_policy)
VALUES (NULL, 'running', NOW(), '{}'::jsonb) RETURNING id;

INSERT INTO skill_system.run_events(run_id, level, event_type, payload)
VALUES (<run_id>, 'info', 'step_completed',
  jsonb_build_object('skill', '<id>', 'operation', '<op>', 'status', '<ok|error>', 'duration_ms', <ms>));

UPDATE skill_system.runs SET status='succeeded', ended_at=NOW(),
  metrics=jsonb_build_object('steps', <n>, 'duration_ms', <ms>) WHERE id=<run_id>;

単純な単一操作の呼び出しでは、ログ記録を省略します。

ステップ 7：改善の課題を報告する

エージェントが、再利用可能な不足点、摩擦点、またはスキル／システムのフローにおける不明瞭な動作に気づいた場合は、改善を追跡できるよう GitHub の課題を作成します。

scripts/report-improvement-issue.md を使用します。

報告するタイミング：

• 実行中に、ガードレールやポリシーチェックの不足が判明した場合
• ドキュメント／エントリーポイントが不明瞭なため、ユーザーの手間が繰り返し発生している場合
• 信頼性に関する不足（ドリフトしやすい手順、不十分な検証、可観測性の不足）

新しい課題を作成する前に、オープンな課題の中に重複がないか確認します。

類似した課題がすでに存在する場合は、新しい課題を作成する代わりに、その課題へのリンクを追加します。

実験ゲートの委任

実験の検証とレジストリの安全性に関する操作は、skill-system-gate に委任します：

操作	委任先
ゲートのルールに照らして実験コード／ログを検証する	skill-system-gate → validate-experiment
リセット／再実行の前にレジストリの状態の安全性を確認する	skill-system-gate → verify-registry
実験キューのステータスと健全性を表示する	skill-system-gate → status

GitHub 操作の委任

改善報告以外の一般的な GitHub PM 操作は、skill-system-github に委任します：

操作	委任先
改善の課題を報告する（ルーティング中）	このスキル — report-improvement-issue
課題の作成／一覧表示／コメント追加／クローズ／再オープン	skill-system-github → manage-issues
ラベルの作成／更新／削除／適用	skill-system-github → manage-labels
課題テンプレートの初期設定／更新	skill-system-github → manage-templates
ワークフローの一覧表示／確認／作成／更新	skill-system-github → manage-workflows
ワークフローへの書き込み前に PAT のスコープを確認する	skill-system-github → safety-check

改善報告はスキルのルーティング中にインラインで呼び出されるため、ルーターは report-improvement-issue を引き続き担当します。それ以外の GitHub 操作はすべて、専用スキルにルーティングされます。

インサイトの提案

複雑なセッション（複数ステップの作業、重要な議論、デバッグなど）を完了した後は、インサイトの抽出を提案することを検討してください。

「このセッションのインサイトを抽出しましょうか？次回のコラボレーションをより円滑にするために、お客様の好みを学習できます。」

これは手軽で任意のプロンプトです。次の場合にのみ提案してください。

• 有意義なやり取りがあった（1行の修正ではない）
• ユーザーが最近、すでにインサイトの抽出を実行していない
• セッションに記録する価値のある兆候（不満、満足、スタイルの好み）が含まれていた

ユーザーが同意した場合は、skill-system-insight を読み込み、scripts/extract-facets.md に従ってください。

注：skill-system-insight は、観察と進化を統合したエンジンです。ファセットの抽出と、プロフィール／レシピの進化（以前はインサイトスキルと進化スキルに分かれていました）の両方を処理します。

よくあるパターン

単一の操作： 目標 → インデックスを検索 → 1つのエントリーポイントを実行 → 結果を返す

複数ステップの連鎖： 目標 → op1.search → 結果を解析 → op2.store（結果を使用） → 完了

スキルをまたぐ連鎖： 目標 → skill-A.op1 → 出力をコンテキストとして使用 → skill-B.op2 → インデックスを再構築 → 完了

ワークフロー支援型の連鎖： 目標 → router.plan-with-workflow → wave 1 のタスクを実行 → 依存する wave を実行 → 結果を記録

データベース

skill-system-postgres のテーブルを使用します。

• skill_system.policy_profiles — 効果の許可リスト
• skill_system.runs — 実行記録
• skill_system.run_events — ステップ単位のログ

{
  "schema_version": "2.0",
  "id": "skill-system-router",
  "version": "1.0.0",
  "capabilities": ["skill-discover", "skill-execute", "skill-chain", "index-rebuild", "skill-improvement-report", "workflow-route", "session-guard", "policy-check"],
  "effects": ["fs.read", "fs.write", "proc.exec", "db.read", "db.write", "net.fetch", "git.read"],
  "operations": {
    "rebuild-index": {
      "description": "Regenerate skills-index.json by scanning all skill manifests.",
      "input": {},
      "output": {
        "description": "Index file path and skill count",
        "fields": { "file": "string", "skill_count": "integer" }
      },
      "entrypoints": {
        "unix": ["bash", "scripts/build-index.sh"],
        "windows": ["powershell.exe", "-NoProfile", "-ExecutionPolicy", "Bypass", "-File", "scripts\\build-index.ps1"]
      }
    },
    "report-improvement-issue": {
      "description": "Create or link a GitHub issue for skill/system improvements discovered during routing.",
      "input": {
        "title": {"type": "string", "required": true, "description": "Issue title"},
        "summary": {"type": "string", "required": true, "description": "Concise problem statement and why it matters"},
        "repo": {"type": "string", "required": false, "description": "owner/repo override; default inferred from git remote"},
        "impact": {"type": "string", "required": false, "description": "User or system impact"},
        "repro_steps": {"type": "string", "required": false, "description": "Steps to reproduce observed friction"},
        "suggested_fix": {"type": "string", "required": false, "description": "Candidate fix or direction"}
      },
      "output": {
        "description": "Created or matched issue information",
        "fields": {"status": "created | linked", "issue_url": "string", "issue_number": "integer"}
      },
      "entrypoints": {
        "agent": "Follow scripts/report-improvement-issue.md procedure"
      }
    },
    "plan-with-workflow": {
      "description": "Use skill-system-workflow to plan complex goals as DAG waves, then route execution by dependency order.",
      "input": {
        "goal": {"type": "string", "required": true, "description": "Complex user goal"},
        "context": {"type": "string", "required": false, "description": "Optional files/constraints context"}
      },
      "output": {
        "description": "Workflow plan prepared for router execution",
        "fields": {"dag": "YAML", "mermaid": "string", "wave_count": "integer", "execution_notes": "string"}
      },
      "entrypoints": {
        "agent": "Follow scripts/plan-with-workflow.md procedure"
      }
    },
    "guard-check": {
      "description": "Mandatory fail-closed session-start guard: load skill-system-router first, confirm router discovery, and block non-router skills until the guard succeeds.",
      "input": {},
      "output": {
        "description": "Guard result and failure guidance",
        "fields": {"router_checked": "boolean", "message": "string"}
      },
      "entrypoints": {
        "agent": "Follow scripts/session-guard-check.md procedure"
      }
    },
    "check-policy": {
      "description": "Evaluate requested skill effects against the active policy profile and return structured allow/deny decisions.",
      "input": {
        "skill_id": {"type": "string", "required": true, "description": "Skill identifier being evaluated"},
        "effects": {"type": "array", "required": true, "description": "Requested effects to evaluate"},
        "profile": {"type": "string", "required": false, "description": "Policy profile name; defaults to dev"}
      },
      "output": {
        "description": "Policy lookup source, allowlist, and per-effect decisions",
        "fields": {"policy_decisions": "array", "all_allowed": "boolean", "policy_source": "string"}
      },
      "entrypoints": {
        "agent": "Invoke scripts/router.py check-policy with --skill-id, repeated --effect flags, and optional --profile"
      }
    }
  },
  "stdout_contract": {
    "last_line_json": false,
    "note": "rebuild-index prints summary to stdout; report-improvement-issue/plan-with-workflow are agent-executed."
  }
}