Skill Router (L1 Master Dispatch)
Overview
skill-router is the master L1 dispatch coordinator for the 1,413+ skills in the 1ai-skills library. Rather than flatly injecting all skills into an agent's system prompt—which burns ~75k tokens, degrades model attention, and increases trigger collision rates—skill-router enforces a two-tier hierarchical dispatch architecture:
- Tier 1 (L1 Master Classification): Maps the user's intent to one of 19 specialized categories or 14 professional
role-* entry anchors using lightweight heuristic and trigger matching (<1k tokens).
- Tier 2 (L2 On-Demand Specialists): The agent loads only the specific domain playbook (
skill://<name> or read ~/.agents/skills/<name>/SKILL.md) needed for the task at hand.
This matches the ECC (Enterprise Context Control) two-tier pattern: separating daily harness instructions (DAILY) from specialized reference playbooks (LIBRARY).
When to Use
Trigger phrases:
- "skill router"
- "route skill"
- "find skill"
- "load skill"
- "discover skills"
- "which skill to use"
- "category router"
Use this skill when:
- Starting a complex or cross-functional project where the exact specialized playbook is unknown.
- The user query could span multiple domains (e.g. "audit our checkout page" involves frontend UI, payment rails, and API security).
- Finding the highest-leverage specialist skill without loading hundreds of prompt instructions into context.
- Programmatically querying the skill catalog via
scripts/skill_router.py.
When NOT to Use
- When the exact specialized skill name is already known (e.g.,
git-workflow-mastery, stripe-integration) — load that skill directly.
- For narrow cybersecurity attacks where the attack surface is already confirmed — use
cybersecurity/cybersecurity-router directly.
- For routing LLM model endpoints/providers at runtime — use
core/model-router.
- For Cloudflare edge routing, CDN, and DNS rules — use
core/cloudflare-router.
Anti-Rationalization Table
| Rationalization |
Reality |
| "I should dump all 1,400 skills into the prompt so the model knows everything." |
1,400 flat skills consume ~75k tokens. Accuracy drops below 65% due to needle-in-haystack attention dilution and prefix collisions (gate-*, p2p-*). |
| "I don't need a router; I can guess the skill name." |
Guessing creates nonexistent skills or misses deep canonical implementations (e.g., guessing xss-finder misses testing-for-xss-vulnerabilities). |
| "I'll read all SKILL.md files in the repo to pick one." |
Reading directory trees blows agent turn context. The router lookup requires a single tokenized scoring pass. |
| "All categories are the same." |
The 19 categories have distinct blast radiuses, compliance requirements, and validation gates. Security skills require strict scope proof; trading skills require risk bounds. |
Workflow
flowchart TD
UserQuery[User Request / Task Intent] --> Router{Classify Intent L1}
Router -->|Engineering / Code| RoleSWE[role-software-engineer / role-system-architect]
Router -->|Security / Exploit| SecRouter[cybersecurity-router / role-penetration-tester]
Router -->|Growth / Marketing| RoleMarketer[role-growth-marketer / seo-auditor]
Router -->|Trading / Crypto| RoleQuant[role-quantitative-trader]
Router -->|UI / Design| RoleUI[role-ui-ux-designer / impeccable]
Router -->|Operations / Product| RolePM[role-product-manager]
RoleSWE --> LoadL2[Load Specific L2 SKILL.md via read / skill://]
SecRouter --> LoadL2
RoleMarketer --> LoadL2
RoleQuant --> LoadL2
RoleUI --> LoadL2
RolePM --> LoadL2
LoadL2 --> Execute[Execute Playbook with Quality Gates]
1. Intent Classification Matrix (19 Categories & Anchors)
| Category |
Skill Count |
L1 Anchor Skill |
Primary Intent / Vector |
| cybersecurity |
801 |
cybersecurity-router / role-penetration-tester |
Pen-testing, threat hunting, forensics, SOC, cloud & API security |
| content |
103 |
role-ui-ux-designer / impeccable / hallmark |
UI/UX design, typography, writing, video rendering, anti-slop |
| development |
103 |
role-software-engineer / role-system-architect |
TDD, debugging, refactoring, code review, backend & frontend patterns |
| mindset |
55 |
mental-models / first-principles-thinking |
Decision frameworks, negotiation, leadership, root-cause analysis |
| core |
49 |
model-router / skill-router |
AI infrastructure, LLM routing, memory, agent self-improvement |
| marketing |
43 |
role-growth-marketer / ai-seo / seo-auditor |
SEO, GEO/AEO, cold email, paid ads, viral content, analytics |
| research |
38 |
role-research-analyst / market-research |
Deep research, competitive analysis, trend synthesis |
| devops |
32 |
role-devops-sre-engineer |
Docker, Kubernetes, CI/CD pipelines, GitOps, cloud ops |
| integrations |
29 |
stripe-integration / github / discord |
Third-party APIs, SaaS platforms, database connectors |
| trading |
27 |
role-quantitative-trader / crypto-trading-bot |
Crypto CEX/DEX, Polymarket, funding arbitrage, risk management |
| automation |
21 |
nocode-orchestrator / task-scheduler |
Web scraping, n8n, workflows, multi-platform bots |
| operations |
20 |
role-product-manager / project-management |
SOPs, incident command, PRD, business workflows |
| financial |
19 |
role-financial-analyst |
Cashflow modeling, DCF valuation, GL reconciliation, CFO ops |
| mcp |
15 |
mcp-server-builder / mcp-client |
Model Context Protocol servers, toolchain integration |
| agents |
14 |
planning-agent / autonomous / test-agent |
Autonomous multi-agent pipelines, specialized agent roles |
| meta |
13 |
auto-learner / continuous-learning |
Skill creation, performance monitoring, auto-evolution |
| sales |
13 |
b2b-sales-automation / high-ticket-closing |
B2B lead generation, outreach pipelines, closing frameworks |
| productivity |
10 |
personal-productivity / focus-time-management |
Time blocking, calendar management, inbox zero |
| data |
8 |
role-data-engineer |
Data pipelines, dbt, Spark, query optimization, ETL |
2. Programmatic Discovery via CLI
To find the top 5 matching skills without reading files:
python3 scripts/skill_router.py "audit web application authentication and session security"
Example Output:
Score Category Name Description
-----------------------------------------------------------------------------------------
95.0 cybersecurity auth-killer Use for OAuth SAML JWT SSO...
72.0 cybersecurity testing-api-authentication-weakness Test API authentication for...
65.0 cybersecurity cybersecurity-router Use when starting any cyber...
3. Execution Protocol
- Query & Score: Tokenize the user's task requirement and match against category and trigger indices.
- Select Anchor: If broad, initialize the relevant
role-* or *-router skill.
- Drill Down: From the anchor's deterministic dispatch matrix, read only the exact specialist
SKILL.md.
- Execute & Verify: Apply the specialized playbook's anti-rationalization table and verification gates.
Phase 4: External Discovery Fallback
When the local router returns a top score below 30, no specialist skill is a strong match. Rather than hallucinating or failing, delegate to find-skills (core/find-skills or meta/find-skills) to acquire a verified community skill.
Delegation Protocol
- Score Threshold Check:
should_delegate_external(results) returns True when results[0].score < 30 or results is empty.
- Probe Registry: Invoke
find-skills with the user's original query tokens. Prefer verified registries (skills.sh, ECC, own-repo).
- Validate: Run
scripts/lint-skills.py --write, scripts/check-broken-links.py, and scripts/test-skills.py --quick on the downloaded skill.
- Import: Copy the validated skill into
./skills/<name>/ with provenance metadata in frontmatter (provenance.source, provenance.imported_at).
- Index:
python3 scripts/lint-skills.py --write updates SKILLS.json.
- Sync Mirror:
bash scripts/sync-skills.sh populates ~/.agents/skills/<name>/.
- Re-Dispatch: Re-score the query; the imported skill now appears with its trigger bonus (+15 per token) and should clear the 30-point floor.
Guardrails
- Never auto-import without user confirmation. External skills execute code and inject prompts; the user must approve before import.
- Refuse import if skill has >3 unresolved links, no
## When to Use, or no ## Verification section.
- All imported skills MUST pass the full validation ladder (
lint-skills, check-broken-links, validate-skills, test-skills --quick).
- Append
(downloaded: <source>, <date>) to the skill's description for provenance.
- Default max 3 imports per delegation to prevent dependency sprawl.
Communication Contract
Pass to find-skills:
query_tokens: token set from user request
requested_capabilities: required tools/outputs inferred from query
max_imports: default 3
source_preference: "verified" (curated registries) or "exploratory" (github raw)
Expect back:
skill_name, skill_path, trigger_phrases, tools_provided, auth_requirements
Verification
1---2name: skill-router3description: Use when discovering, categorizing, and loading relevant skills across the 1,400+ 1ai-skills library without context bloat, attention dilution, or prompt budget exhaustion. Master L1 dispatch router for all 19 skill categories.4domain: core5subdomain: core-platform6category: core7version: 1.0.08author: oyi779license: Apache-2.010tags:11- routing12- skill-discovery13- meta-skill14- architecture15- agent-harness16- context-optimization17triggers:18- skill router19- route skill20- find skill21- load skill22- discover skills23- which skill to use24- category router25argument-hint: "[task query or category]"26metadata:27 source: https://skillmd.com/skills/oyi77/skill-router28---2930# Skill Router (L1 Master Dispatch)3132## Overview3334`skill-router` is the master L1 dispatch coordinator for the 1,413+ skills in the `1ai-skills` library. Rather than flatly injecting all skills into an agent's system prompt—which burns ~75k tokens, degrades model attention, and increases trigger collision rates—`skill-router` enforces a two-tier hierarchical dispatch architecture:35361. **Tier 1 (L1 Master Classification):** Maps the user's intent to one of 19 specialized categories or 14 professional `role-*` entry anchors using lightweight heuristic and trigger matching (<1k tokens).372. **Tier 2 (L2 On-Demand Specialists):** The agent loads only the specific domain playbook (`skill://<name>` or `read ~/.agents/skills/<name>/SKILL.md`) needed for the task at hand.3839This matches the ECC (Enterprise Context Control) two-tier pattern: separating daily harness instructions (`DAILY`) from specialized reference playbooks (`LIBRARY`).4041## When to Use4243**Trigger phrases:**44- "skill router"45- "route skill"46- "find skill"47- "load skill"48- "discover skills"49- "which skill to use"50- "category router"5152Use this skill when:53- Starting a complex or cross-functional project where the exact specialized playbook is unknown.54- The user query could span multiple domains (e.g. "audit our checkout page" involves frontend UI, payment rails, and API security).55- Finding the highest-leverage specialist skill without loading hundreds of prompt instructions into context.56- Programmatically querying the skill catalog via `scripts/skill_router.py`.5758## When NOT to Use5960- When the exact specialized skill name is already known (e.g., `git-workflow-mastery`, `stripe-integration`) — load that skill directly.61- For narrow cybersecurity attacks where the attack surface is already confirmed — use `cybersecurity/cybersecurity-router` directly.62- For routing LLM model endpoints/providers at runtime — use `core/model-router`.63- For Cloudflare edge routing, CDN, and DNS rules — use `core/cloudflare-router`.6465## Anti-Rationalization Table6667| Rationalization | Reality |68|---|---|69| "I should dump all 1,400 skills into the prompt so the model knows everything." | 1,400 flat skills consume ~75k tokens. Accuracy drops below 65% due to needle-in-haystack attention dilution and prefix collisions (`gate-*`, `p2p-*`). |70| "I don't need a router; I can guess the skill name." | Guessing creates nonexistent skills or misses deep canonical implementations (e.g., guessing `xss-finder` misses `testing-for-xss-vulnerabilities`). |71| "I'll read all SKILL.md files in the repo to pick one." | Reading directory trees blows agent turn context. The router lookup requires a single tokenized scoring pass. |72| "All categories are the same." | The 19 categories have distinct blast radiuses, compliance requirements, and validation gates. Security skills require strict scope proof; trading skills require risk bounds. |7374## Workflow7576```mermaid77flowchart TD78 UserQuery[User Request / Task Intent] --> Router{Classify Intent L1}79 Router -->|Engineering / Code| RoleSWE[role-software-engineer / role-system-architect]80 Router -->|Security / Exploit| SecRouter[cybersecurity-router / role-penetration-tester]81 Router -->|Growth / Marketing| RoleMarketer[role-growth-marketer / seo-auditor]82 Router -->|Trading / Crypto| RoleQuant[role-quantitative-trader]83 Router -->|UI / Design| RoleUI[role-ui-ux-designer / impeccable]84 Router -->|Operations / Product| RolePM[role-product-manager]85 86 RoleSWE --> LoadL2[Load Specific L2 SKILL.md via read / skill://]87 SecRouter --> LoadL288 RoleMarketer --> LoadL289 RoleQuant --> LoadL290 RoleUI --> LoadL291 RolePM --> LoadL292 93 LoadL2 --> Execute[Execute Playbook with Quality Gates]94```9596### 1. Intent Classification Matrix (19 Categories & Anchors)9798| Category | Skill Count | L1 Anchor Skill | Primary Intent / Vector |99|---|---:|---|---|100| **cybersecurity** | 801 | `cybersecurity-router` / `role-penetration-tester` | Pen-testing, threat hunting, forensics, SOC, cloud & API security |101| **content** | 103 | `role-ui-ux-designer` / `impeccable` / `hallmark` | UI/UX design, typography, writing, video rendering, anti-slop |102| **development** | 103 | `role-software-engineer` / `role-system-architect` | TDD, debugging, refactoring, code review, backend & frontend patterns |103| **mindset** | 55 | `mental-models` / `first-principles-thinking` | Decision frameworks, negotiation, leadership, root-cause analysis |104| **core** | 49 | `model-router` / `skill-router` | AI infrastructure, LLM routing, memory, agent self-improvement |105| **marketing** | 43 | `role-growth-marketer` / `ai-seo` / `seo-auditor` | SEO, GEO/AEO, cold email, paid ads, viral content, analytics |106| **research** | 38 | `role-research-analyst` / `market-research` | Deep research, competitive analysis, trend synthesis |107| **devops** | 32 | `role-devops-sre-engineer` | Docker, Kubernetes, CI/CD pipelines, GitOps, cloud ops |108| **integrations** | 29 | `stripe-integration` / `github` / `discord` | Third-party APIs, SaaS platforms, database connectors |109| **trading** | 27 | `role-quantitative-trader` / `crypto-trading-bot` | Crypto CEX/DEX, Polymarket, funding arbitrage, risk management |110| **automation** | 21 | `nocode-orchestrator` / `task-scheduler` | Web scraping, n8n, workflows, multi-platform bots |111| **operations** | 20 | `role-product-manager` / `project-management` | SOPs, incident command, PRD, business workflows |112| **financial** | 19 | `role-financial-analyst` | Cashflow modeling, DCF valuation, GL reconciliation, CFO ops |113| **mcp** | 15 | `mcp-server-builder` / `mcp-client` | Model Context Protocol servers, toolchain integration |114| **agents** | 14 | `planning-agent` / `autonomous` / `test-agent` | Autonomous multi-agent pipelines, specialized agent roles |115| **meta** | 13 | `auto-learner` / `continuous-learning` | Skill creation, performance monitoring, auto-evolution |116| **sales** | 13 | `b2b-sales-automation` / `high-ticket-closing` | B2B lead generation, outreach pipelines, closing frameworks |117| **productivity** | 10 | `personal-productivity` / `focus-time-management` | Time blocking, calendar management, inbox zero |118| **data** | 8 | `role-data-engineer` | Data pipelines, dbt, Spark, query optimization, ETL |119120### 2. Programmatic Discovery via CLI121122To find the top 5 matching skills without reading files:123124```bash125python3 scripts/skill_router.py "audit web application authentication and session security"126```127128*Example Output:*129```text130Score Category Name Description131-----------------------------------------------------------------------------------------132 95.0 cybersecurity auth-killer Use for OAuth SAML JWT SSO...133 72.0 cybersecurity testing-api-authentication-weakness Test API authentication for...134 65.0 cybersecurity cybersecurity-router Use when starting any cyber...135```136137### 3. Execution Protocol1381391. **Query & Score**: Tokenize the user's task requirement and match against category and trigger indices.1402. **Select Anchor**: If broad, initialize the relevant `role-*` or `*-router` skill.1413. **Drill Down**: From the anchor's deterministic dispatch matrix, read only the exact specialist `SKILL.md`.1424. **Execute & Verify**: Apply the specialized playbook's anti-rationalization table and verification gates.143144## Phase 4: External Discovery Fallback145146When the local router returns a top score **below 30**, no specialist skill is a strong match. Rather than hallucinating or failing, delegate to `find-skills` (core/find-skills or meta/find-skills) to acquire a verified community skill.147148### Delegation Protocol1491501. **Score Threshold Check**: `should_delegate_external(results)` returns `True` when `results[0].score < 30` or `results` is empty.1512. **Probe Registry**: Invoke `find-skills` with the user's original query tokens. Prefer verified registries (skills.sh, ECC, own-repo).1523. **Validate**: Run `scripts/lint-skills.py --write`, `scripts/check-broken-links.py`, and `scripts/test-skills.py --quick` on the downloaded skill.1534. **Import**: Copy the validated skill into `./skills/<name>/` with provenance metadata in frontmatter (`provenance.source`, `provenance.imported_at`).1545. **Index**: `python3 scripts/lint-skills.py --write` updates `SKILLS.json`.1556. **Sync Mirror**: `bash scripts/sync-skills.sh` populates `~/.agents/skills/<name>/`.1567. **Re-Dispatch**: Re-score the query; the imported skill now appears with its trigger bonus (+15 per token) and should clear the 30-point floor.157158### Guardrails159160- **Never auto-import without user confirmation.** External skills execute code and inject prompts; the user must approve before import.161- Refuse import if skill has >3 unresolved links, no `## When to Use`, or no `## Verification` section.162- All imported skills MUST pass the full validation ladder (`lint-skills`, `check-broken-links`, `validate-skills`, `test-skills --quick`).163- Append `(downloaded: <source>, <date>)` to the skill's description for provenance.164- Default max 3 imports per delegation to prevent dependency sprawl.165166### Communication Contract167168Pass to `find-skills`:169- `query_tokens`: token set from user request170- `requested_capabilities`: required tools/outputs inferred from query171- `max_imports`: default 3172- `source_preference`: `"verified"` (curated registries) or `"exploratory"` (github raw)173174Expect back:175- `skill_name`, `skill_path`, `trigger_phrases`, `tools_provided`, `auth_requirements`176177## Verification178179- [ ] Query matches route to the expected category anchor (e.g., SEO query → `marketing` / `ai-seo`)180- [ ] No more than 1 anchor skill loaded initially (zero context bloat)181- [ ] Target specialist skill exists on disk and resolves via `read` or `skill://`182- [ ] Router CLI (`scripts/skill_router.py`) executes without syntax or import errors183- [ ] Anti-rationalization table consulted before defaulting to brute-force context loading184- [ ] Phase 4 delegation triggered only when top score < 30 AND user confirms import