Workflow Skill Router

A Codex-ready routing layer for one slice of agent sprawl: skill selection sprawl.

Not another prompt collection. A routing layer for multi-skill AI agents.

Modern AI coding agents can have dozens of skills, tools, connectors, and workflows. Workflow Skill Router turns that flat list into a small, reviewable decision before execution begins.

Workflow Skill Router addresses one layer of agent sprawl: skill selection sprawl. It does not replace scope contracts, runtime permissions, or approval policies. Instead, it gives agents a small, reviewable routing decision before work starts, using only the skills that already exist and are already allowed in your environment.

Positioning

Workflow Skill Router is a pre-execution skill selection layer. It helps an agent decide:

• which one skill should own the task as Primary,
• which supporting skills are truly needed,
• which tempting but unnecessary skills should stay out,
• why this route is the smallest useful skill set.

It is not a security boundary. Pair it with your normal scope contracts, runtime permissions, approval policies, and tool access controls.

Before And After

Without routing, a frontend bug can trigger every related skill:

frontend, ui, browser, playwright, qa, design-system, github, docs, deployment

With routing, the agent selects a small working set:

Route: Frontend / Debugging > Browser reproduction > Single-page app
Use SKILL: vue-expert, systematic-debugging, playwright
Reason: vue-expert handles component behavior; systematic-debugging keeps the investigation causal; playwright captures the regression.

Demo preview:

Watch the polished demo: MP4, WebM, or site showcase.
GIF fallback: high-resolution demo GIF or lightweight 60-second GIF
Short routing output demo: fuzzy request to route output GIF
Static preview: before/after routing SVG

30 Second Quickstart

Website: https://huangchiyu.com/Workflow-skill-router/
Traditional Chinese site: https://huangchiyu.com/Workflow-skill-router/zh-tw/

Which package should I download?

Try the framework without installing anything:

git clone https://github.com/eric861129/Workflow-skill-router.git
cd Workflow-skill-router
python scripts/validate-router.py starter/workflow-skill-router

Install the blank skill into Codex on Windows PowerShell:

$Repo = "https://github.com/eric861129/Workflow-skill-router"
$Zip = Join-Path $env:TEMP "workflow-skill-router-blank.zip"
$Validator = Join-Path $env:TEMP "workflow-skill-router-validate-router.py"
$Skills = Join-Path $env:USERPROFILE ".codex\skills"
Invoke-WebRequest "$Repo/raw/main/downloads/workflow-skill-router-blank.zip" -OutFile $Zip
Invoke-WebRequest "$Repo/raw/main/scripts/validate-router.py" -OutFile $Validator
New-Item -ItemType Directory -Force -Path $Skills | Out-Null
Expand-Archive -Force -Path $Zip -DestinationPath $Skills
python $Validator (Join-Path $Skills "workflow-skill-router")

For macOS and Linux install commands, see the Quickstart guide.

For a complete blank-router setup, see the Blank Router walkthrough. If installation or validation fails, open Troubleshooting.

Expected result:

OK: workflow-skill-router passed validation

Proof

• 80 benchmark scenarios in evaluation/scenarios.example.jsonl.
• Public routing metrics trend from v1.2.0 to v1.3.0.
• Public-safe Routing Gallery generated from root-level route cases.
• Unit tests for scanner, evaluator, route cases, and metrics behavior.
• Public-readiness audit for community files, downloads, manifests, examples, site entrypoints, and mojibake checks.
• Lighthouse gate across English and Traditional Chinese pages; latest local pass had 100 accessibility, best-practices, and SEO scores.
• Strict CI checks scanner privacy, duplicate skill ids, route violations, and exact routing expectations.

Download Skill Packages

• Blank Router package: the main download for people who want to build their own router from their own skills, naming conventions, triggers, exclusions, and routing rules.
• Reference Template package: a public-safe example for learning the structure before adapting the blank router to your own workflow.
• Full source archive: the larger source archive with per-skill README files, useful only when you need source context or audit material.
• Template Skill Catalog: the matching route catalog for the Reference Template.
• Template manifest: included skill folders, excluded private skill count, and sanitization summary.

Direct repository paths for audit and offline use: Blank Router, Reference Template, Full source archive.

Project Roadmap And Community

Follow releases or watch the repo to track work on:

• keeping multi-skill agents out of context overload,
• benchmarking routing decisions with repeatable scenarios,
• publishing public-safe skill catalogs without leaking private rules,
• building public-safe reference packages from local skill folders.

What This Project Helps You Do

• Inventory your available skills into a machine-readable catalog.
• Organize skills by workflow stage, technical domain, triggers, and exclusions.
• Route tasks to one primary skill and a small number of supporting skills.
• Validate that routes are explainable, bounded, and public-safe.
• Evaluate routing quality with repeatable scenarios and predictions.

Framework Quickstart

git clone https://github.com/eric861129/Workflow-skill-router.git
cd Workflow-skill-router

python scripts/validate-router.py starter/workflow-skill-router

python scripts/scan-skills.py ./sample-skills \
  --out references/skill-index.example.json \
  --markdown references/skill-index.example.md \
  --warnings references/skill-scan-warnings.example.md \
  --suggest-tree references/suggested-skill-tree.example.md

python scripts/evaluate-routing.py \
  --scenarios evaluation/scenarios.example.jsonl \
  --predictions evaluation/predictions.example.jsonl \
  --report evaluation/report.example.md

Recommended Workflow

1. Copy the starter.
2. Inventory available skills.
3. Define the skill tree.
4. Define routing rules.
5. Add routing scenarios.
6. Generate predictions.
7. Evaluate routing quality.
8. Run validation before publishing.

Quality Gates

• Max 4 skills per route unless the work is explicitly staged.
• Primary skill must be clear.
• Supporting skills should be minimal and distinct.
• Route explanation should be present.
• Forbidden skills should not be selected.
• Private markers should not appear in public packages or examples.
• Scenario coverage should grow as routing mistakes are discovered.

Example Report Preview

# Routing Evaluation Report

| Metric | Value |
| --- | ---: |
| Scenario Count | 80 |
| Primary Accuracy | 1.0 |
| Forbidden Skill Violation Rate | 0.0 |
| Max Skill Count Violation Rate | 0.0 |
| Over-routing Rate | 0.0 |

Before publishing your own router package or public examples, run the full repository audit:

python scripts/audit-public-readiness.py .
python scripts/check-markdown-links.py .

Expected result:

OK: public-readiness audit passed

Run the site quality gate before a public launch:

cd site
npm ci
npm run assets:demo:check
npm run assets:social:check
npm run audit:lighthouse
npm audit --omit=dev --audit-level=moderate

This builds the Starlight site, runs Lighthouse against key English and Traditional Chinese pages, and writes local reports to site/lighthouse-reports/.

Regenerate all three archives locally:

python scripts/package-downloads.py --skills-root <path-to-local-codex-skills> --exclude-prefix <private-prefix> --exclude-name <private-skill-name> --private-marker <private-text-marker>

The package builder refuses to use an implicit local skills directory. It also requires at least one private filter unless you explicitly pass --allow-no-private-filters after auditing your source directory.

The Reference Template is generated from a real local .codex/skills folder. It excludes organization-specific skills and omits sensitive lines from otherwise public skills. Use it to study the pattern, then adapt Blank Router to your own skill set.

Practical Routing Examples

API contract sync

User: Add a new customer settings endpoint, update OpenAPI, and make the frontend client follow it.

Route: API / Contract lifecycle > Backend-to-frontend sync
Use SKILL: api-designer, openapi-contract-generation-skill, openapi-to-typescript, qa-test-planner
Reason: api-designer stabilizes the endpoint; openapi-contract-generation-skill manages schema diff and contract generation; openapi-to-typescript updates the client types; qa-test-planner defines contract coverage.

Database migration with performance risk

User: Add audit tables for account changes and make sure the admin query does not become slow.

Route: Database / Schema and performance > Migration plus query review
Use SKILL: database-schema-designer, sql-pro, database-optimizer, qa-test-planner
Reason: database-schema-designer owns migration shape; sql-pro reviews SQL correctness; database-optimizer checks query plans; qa-test-planner defines regression coverage.

Browser-only frontend bug

User: A customer portal form only fails after a browser refresh. Reproduce it and add a regression check.

Route: Frontend / Vue / UI > Browser regression
Use SKILL: vue-expert, systematic-debugging, playwright
Reason: vue-expert handles component behavior; systematic-debugging keeps the investigation causal; playwright captures the regression.

PR review and CI repair

User: Review this auth PR, address comments, and fix the failing checks.

Route: Review / CI readiness > Security-sensitive change
Use SKILL: receiving-code-review, systematic-debugging, qa-test-planner, commit-work
Reason: receiving-code-review handles review feedback; systematic-debugging isolates failing checks; qa-test-planner defines verification; commit-work keeps the final change clean.

Local development stack

User: Create a Docker Compose setup with PostgreSQL, Redis, and MailDev for local development.

Route: DevOps / Local development > Repeatable service stack
Use SKILL: docker-compose-local-dev-skill, devops-engineer, systematic-debugging
Reason: docker-compose-local-dev-skill owns local service ergonomics; devops-engineer checks infra tradeoffs; systematic-debugging helps when startup order or health checks fail.

What Is Included

• starter/workflow-skill-router/: a Codex-ready starter skill with an agent-agnostic routing contract.
• examples/template-skill-catalog/: the single public example catalog that mirrors the template download package.
• sample-skills/: copyable public SKILL.md examples that pair with the template catalog.
• downloads/: generated blank and template SKILL zip packages.
• recipes/: short practical patterns for API contract sync, frontend debugging, PR/CI work, documentation, and connector-heavy workflows.
• scripts/validate-router.py: dependency-free validation for router structure plus a public-readiness audit for community files, downloads, template catalog/manifest parity, site assets, and stale examples.
• scripts/audit-public-readiness.py: dedicated release gate for the public repo surface, powered by the same checks as validate-router.py --public-readiness.
• scripts/check-markdown-links.py: dependency-free local Markdown/MDX link checker for docs, README, and examples.
• scripts/scan-skills.py: dependency-free skill inventory scanner that writes JSON, Markdown, warnings, and a suggested tree.
• scripts/evaluate-routing.py: dependency-free routing benchmark evaluator for scenarios and predictions.
• scripts/validate-route-cases.py: public route case schema and public-safety validator.
• scripts/build-route-gallery.py: generator for site gallery data and route-case evaluator scenarios.
• scripts/render-routing-metrics-trend.py: generator for release-level metrics trend docs and site data.
• route-cases/: canonical public-safe route cases accepted from maintainers and contributors.
• evaluation/: benchmark scenarios, predictions, schema docs, generated route-case scenarios, metrics history, and generated report.
• references/: generated example scanner outputs.
• tests/: standard-library unit tests for scanner, evaluator, route case, and metrics behavior.
• scripts/package-downloads.py: dependency-free packaging for downloadable SKILL archives.
• site/: Astro Starlight website for GitHub Pages, including Playwright smoke and visual tests.
• site/scripts/lighthouse-audit.mjs: formal Lighthouse and accessibility score gate for the public website.
• site/scripts/generate-demo-assets.mjs: reproducible demo poster/WebM asset generator.
• site/scripts/generate-social-assets.mjs: reproducible Open Graph/social preview generator.
• prompts/: copy-paste prompts for creating or updating a personalized router.
• docs/: conceptual docs, customization guidance, and validation checklists.

Example Routers

FAQ

Is this different from a system prompt?

Yes. A system prompt defines how an agent should behave. Workflow Skill Router decides which skill instructions should be loaded for a specific task. It sits before execution: classify the task, choose 1 primary skill and up to 3 supporting skills, then explain the route.

Is this an agent permission or sandbox layer?

No. Workflow Skill Router narrows skill selection before work starts. It does not grant permissions, enforce sandbox rules, approve tool calls, or replace your scope contract. Use it with your existing governance controls.

Why limit each route to 1-4 skills?

The limit keeps context focused. One primary skill owns the work; supporting skills add domain knowledge, verification, or tooling. If a task truly needs more than 4 skills, split it into stages and route each stage separately.

Can this work with Claude, Cursor, Gemini, or other agents?

Yes. The pattern is agent-agnostic. The starter is Codex-ready, but the contract is plain text: skill inventory, routing rules, sample routes, and validator. Any agent that can read project instructions or custom rules can adapt it. See the Claude, Cursor, and Gemini adapter notes.

The install command failed. Where should I look?

Open the Troubleshooting guide. It covers install paths, PowerShell, Python, zip extraction, validator errors, and public-readiness checks.

Learn More

• English guide
• 繁體中文說明
• Website
• Traditional Chinese site
• Blank Router walkthrough
• Troubleshooting
• Claude, Cursor, and Gemini adapter notes
• Agent governance positioning
• Customization guide
• System theory
• Validation checklist
• Dependency governance
• Roadmap
• Case studies
• Showcase
• Anti-over-routing guide
• Forward tests
• Shareable demo asset
• Social preview PNG

License

MIT. See LICENSE.