skill-system-router

Skill System Router

Deprecated compatibility surface. skill-system-cli now owns the router runtime module used by sk, while this skill remains available so existing router docs, policy references, and legacy entrypoints do not break during the transition.

You are the Router. This skill teaches you how to orchestrate other skills.

Router is an internal orchestration layer. The public user-facing entrypoint remains sk from skill-system-cli.

How It Works

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

Step 0: Installer Bootstrap Check (First Run Only)

Check if the project's AGENTS.md contains ## Skill System.

• If found: skip to Step 1 (already bootstrapped).
• If not found: use skill-system-installer bootstrap to scaffold and embed the skill system into the project.

Bootstrap ownership lives in skill-system-installer. After bootstrap, every future session reads AGENTS.md and knows about the skill system automatically.

Step 1: Discover Skills

Read skills-index.json (in the skills root directory, sibling to skill folders) to see available capabilities.

The index maps capabilities → skills and lists each skill's operations with descriptions and input params. Match the user's goal to capabilities. If no match, check if the goal can be decomposed into sub-capabilities.

If the goal is multi-step, ambiguous, or likely to involve 3+ operations, route through workflow planning first via plan-with-workflow.

If skills-index.json is missing or stale, regenerate it:

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

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

Session Guard

MANDATORY ROUTER-FIRST STARTUP: This skill MUST be loaded before any non-router skill at session start. This is a fail-closed guard:

1. Load skill-system-router first.
2. Run the guard-check operation.
3. If guard-check has NOT succeeded: block all non-router skill loads and emit the failure message:

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

4. Only after guard-check succeeds: proceed with non-router skills.

This enforcement is non-negotiable. If a user requests a non-router skill directly, you MUST load router first and complete the guard before proceeding.

Guard failure semantics:

• If router_checked flag is missing: block non-router skills, show message, run discovery.

• If skills-index.json is missing or stale: rebuild it before marking guard complete.

• Memory-backed flag preferred: router_checked=true with session_id.

• Procedure: scripts/session-guard-check.md

Step 2: Read Skill Manifest

Open the target skill's SKILL.md and find the `skill-manifest` fenced block. This gives you:

• operations: what the skill can do, with input/output schemas
• effects: side effects (used for policy check)
• entrypoints: OS-specific commands to run

Full manifest spec: references/manifest-spec.md

Configuration

Runtime settings are in config/router.yaml. Config is the single source of truth.

See: ../../config/router.yaml

Step 3: Check Policy

Before executing, verify the skill's declared effects against the active policy profile:

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

• ALL effects in allowed_effects → proceed
• ANY effect NOT in allowed_effects → ask the user before proceeding
• No policy profile exists → ask the user

report-improvement-issue policy notes:

• Always requires: proc.exec, net.fetch
• Also requires git.read when repo is omitted and inferred from git remote

Standard effects: db.read, db.write, proc.exec, fs.read, fs.write, net.fetch, git.read, git.write

The internal policy helper scripts/router.py check-policy returns a structured policy_decisions list so callers can surface the exact allow/deny reasoning. If skill_system.policy_profiles is unavailable, the helper falls back to config/router.yaml policy.default_allowed_effects and reports that fallback explicitly in the output.

Step 4: Execute

1. Determine OS: OS env = Windows_NT → use windows entrypoint, otherwise unix
2. Read the operation's entrypoints for your OS
3. Substitute {param} placeholders with actual values
4. Set cwd to the skill's directory
5. Run the command
6. Parse the last line of stdout as JSON — this is the result

Exit code ≠ 0 or last line not JSON → operation failed.

Step 5: Chain Operations

When a goal requires multiple skills/operations:

1. Execute first operation → parse JSON output
2. Use output values as input to the next operation (you decide the mapping)
3. Repeat until goal is met

You are intelligent — adapt based on intermediate results. This is better than a fixed pipeline because you can handle errors, skip unnecessary steps, and make contextual decisions.

Step 5.5: Orchestration Call Chain (Router → TKT → Workflow)

For complex goals that need multi-agent coordination, the router orchestrates three layers:

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

Decision matrix:

Goal Type	Route
Single-skill, simple	Direct execute (Step 4)
Multi-step, single session	Workflow.plan → execute by wave
Multi-agent, cross-session	TKT.create-bundle → Workflow.plan → execute → TKT.close

For workflow-only planning (no TKT), use scripts/plan-with-workflow.md. For TKT-integrated planning, use the call chain above.

Step 6: Log (Observability)

After non-trivial workflows, log for observability:

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>;

Skip logging for simple single-operation calls.

Step 7: Report Improvement Issue

When an agent notices reusable gaps, friction points, or unclear behavior in a skill/system flow, create a GitHub issue so the improvement is trackable.

Use scripts/report-improvement-issue.md.

When to report:

• Missing guardrails or policy checks discovered during execution
• Repeated user friction caused by unclear docs/entrypoints
• Reliability gaps (drift-prone steps, weak validation, poor observability)

Before creating a new issue, check for duplicates in open issues.

If a similar issue already exists, link that issue instead of creating a new one.

Experiment Gate Delegation

For experiment validation and registry safety operations, delegate to skill-system-gate:

Operation	Delegate to
Validate experiment code/logs against gate rules	skill-system-gate → validate-experiment
Check registry state safety before reset/rerun	skill-system-gate → verify-registry
Show experiment queue status and health	skill-system-gate → status

GitHub Operations Delegation

For general GitHub PM operations beyond improvement reporting, delegate to skill-system-github:

Operation	Delegate to
Report improvement issue (during routing)	This skill — report-improvement-issue
Create/list/comment/close/reopen issues	skill-system-github → manage-issues
Create/update/delete/apply labels	skill-system-github → manage-labels
Bootstrap/update issue templates	skill-system-github → manage-templates
List/check/create/update workflows	skill-system-github → manage-workflows
Check PAT scopes before workflow writes	skill-system-github → safety-check

The router retains report-improvement-issue because it is triggered inline during skill routing. All other GitHub operations route through the dedicated skill.

Insight Suggestion

After completing a non-trivial session (multi-step work, significant discussion, or debugging), consider suggesting an insight pass:

"Want me to run an insight pass on this session? It helps me learn your preferences for better collaboration next time."

This is a lightweight, optional prompt. Only suggest when:

• The session had meaningful interaction (not a single-line fix)
• The user hasn't already triggered insight extraction recently
• The session contained signals worth capturing (frustration, satisfaction, style preferences)

If the user agrees, load skill-system-insight and follow scripts/extract-facets.md.

Note: skill-system-insight is the unified observe-and-evolve engine. It handles both facet extraction and profile/recipe evolution (formerly split into separate insight + evolution skills).

Common Patterns

Single operation: Goal → index lookup → execute one entrypoint → return result

Multi-step chain: Goal → op1.search → parse results → op2.store(using results) → done

Cross-skill chain: Goal → skill-A.op1 → use output as context → skill-B.op2 → rebuild index → done

Workflow-assisted chain: Goal → router.plan-with-workflow → execute wave 1 tasks → execute dependent waves → log results

Database

Uses tables from skill-system-postgres:

• skill_system.policy_profiles — effect allowlists
• skill_system.runs — execution records
• skill_system.run_events — step-level logs

{
  "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."
  }
}