Task Skill Router Protocol

Use this after understanding the user's request and decomposing it into concrete execution tasks.

The goal is simple: do not guess which slash command, workflow, or skill should handle each subtask. Plan first, route each execution unit, then load the right SKILL.md.

Protocol

1. Understand the request.
2. Decompose it into concrete execution tasks.
3. Run task-skill-router on the decomposed tasks.
4. Load installed skills for execution.
5. Surface missing useful skills to the user.

For one task:

bash
task-skill-router "<decomposed execution task>"

For multiple tasks:

bash
printf '%s\n' \
  "<task 1>" \
  "<task 2>" \
  "<task 3>" \
  | task-skill-router --batch

To record recommendations for later hit-rate review:

bash
printf '%s\n' \
  "<task 1>" \
  "<task 2>" \
  "<task 3>" \
  | task-skill-router --batch --record

If task-skill-router is not on PATH, use:

bash
python3 ~/.task-skill-router/task-skill-router.py "<decomposed execution task>"

Router Output

Each match includes:

• skill: matched skill name
• installed: whether the skill exists locally
• path: path to the matched SKILL.md, if installed
• confidence: TF-IDF cosine similarity score
• mode: suggested handling mode
• reason: why the skill matched
• install_hint: how to install or add the skill when missing

Batch output also includes top-level missing_skills. When --record is used, output includes audit_event_id or audit_event_ids that reviewers can use for hit-rate judgments.

What To Do With The Result

| Case | Behavior | | --- | --- | | installed: true and auto-load | Load the matched SKILL.md and follow its workflow. | | installed: true and recommend | Tell the user the recommended skill and why before proceeding. | | installed: false | Tell the user the useful skill is missing and show the install hint. | | auto-run | Only run deterministic, low-risk commands explicitly provided by the mapping. |

High-risk tasks involving auth, secrets, config, deploys, deletes, or destructive operations must stay in recommend mode.

Red Lines

| Don't | Do | | --- | --- | | Run router before understanding the request | Decompose first, then route subtasks | | Route only the original large request | Route each execution unit | | Guess from memory | Use the router result | | Treat confidence as probability | Treat it as a ranking score | | Ignore missing skills | Tell the user what skill would help | | Auto-run risky workflows | Ask before auth/config/deploy/delete work | | Use stale copied skill text | Load the current SKILL.md from path | | Trust completion claims | Verify with tests, build, or direct checks |

Hit-Rate Review

Use this only after there is enough evidence about the outcome.

bash
task-skill-router --pending-reviews --limit 20
task-skill-router --review <audit_event_id> --judgment hit --evaluator agent:reviewer
task-skill-router --review <audit_event_id> --judgment partial --correct-skill <skill-name> --evaluator skill:<name>
task-skill-router --review <audit_event_id> --judgment miss --correct-skill <skill-name> --evaluator gpt-5
task-skill-router --stats

Use hit when the top recommendation was appropriate, partial when it helped but was incomplete, miss when it was wrong, and unknown when there is not enough evidence.

Integration Notes

This protocol works best for terminal-first tools such as Codex CLI, Claude Code, OpenCode, and custom agents because they can run shell commands and read workspace instructions.

It does not require patching the agent's source code. Source-level integration is stronger, but a project instruction file such as AGENTS.md, CLAUDE.md, or another workspace rule file is usually enough for soft integration.