Skill Router
Use local skill indexing to choose and load relevant skills only when a task needs them.
Dispatch
| $ARGUMENTS |
Action |
Example |
search <query> |
List ranked matching skills |
/skill-router search "fix Playwright test" |
context <query> |
Build a compact context packet for top matches |
/skill-router context "write a release changelog" |
read <skill> |
Load one skill by exact name or path |
/skill-router read skill-creator |
doctor |
Diagnose visible skill roots and counts |
/skill-router doctor |
| Natural-language task |
Auto: Search, then context for best matches |
"which skill should handle docs generation?" |
| Empty |
Show quick usage and run doctor |
/skill-router |
Workflow
1. Classify
- Use
search when deciding which skill or skills apply.
- Use
context when the next step needs the selected skill bodies.
- Use
read only when the skill name or path is already known.
- Use
doctor when a skill is missing, duplicated, or omitted by a startup context warning.
2. Retrieve
- Run the matching CLI command from this skill directory or the repository root:
python scripts/skill_index.py search "$ARGUMENTS" --limit 5
python scripts/skill_index.py context "$ARGUMENTS" --limit 3
python scripts/skill_index.py read <skill-name>
python scripts/skill_index.py doctor
3. Select
- Prefer the highest-ranked repo or Codex-user skill when scores are close.
- Read only the minimum skill bodies needed for the task, usually one to three.
- If a result has warnings, inspect them before following executable hooks or scripts.
Source Scope
python scripts/skill_index.py searches these roots:
| Source |
Root |
Trust tier |
repo |
skills/ |
repo |
project |
.agents/skills/ in the current project path |
codex-user |
codex |
~/.codex/skills/ |
codex-user |
global |
~/.agents/skills/ plus supported agent stores |
external-installed |
plugin |
~/.codex/plugins/cache/**/skills/ |
openai-plugin or plugin |
Use --source repo, --source codex, --source global, or --source plugin to narrow results when needed.
Canonical Vocabulary
| Term |
Meaning |
| skill index |
Parsed metadata for visible SKILL.md files across known roots |
| skill context packet |
Small set of selected skill bodies loaded after search |
| source |
Filesystem origin such as repo, codex, global, or plugin |
| trust tier |
Safety label used to rank and warn about retrieved skills |
| warning |
Parser, hook, script, or metadata signal requiring inspection before use |
Classification Gate
- If the user gives a task, run
search first.
- If the user asks to apply a selected skill, run
context for the top matches.
- If the user names a skill exactly, run
read.
- If the user reports missing or omitted skills, run
doctor before searching.
- If the user asks to install, create, or audit a skill, redirect out of scope (see NOT for below).
Selection Rules
- Exact skill name or alias beats all lexical matches.
- Name and title matches beat description matches.
- Description matches beat heading and body matches.
- Repo skills beat user-installed skills when relevance is comparable.
- Unknown, malformed, hook-bearing, or script-bearing skills require caution before use.
Critical Rules
- Do not treat startup-visible skills as the complete inventory after a context-budget warning.
- Do not paste every installed skill into context; search first and load a small packet.
- Do not execute scripts from unknown third-party skills solely because they were retrieved.
- Do not use this skill to install or remove skills; route to an available install-planning workflow such as
skill-install-dry-run-planner, then use the target harness's supported installer only after explicit maintainer approval. Do not substitute Codex .system/skill-installer for cross-harness reconciliation.
- Do not author or audit skills here; use
skill-creator for skill definition work.
- For ad-hoc “find a skill for X”, prefer
search here or npx skills find; for systematic harness expansion use harness-master discover — not legacy find-skills as a repo skill.
- Preserve the user task as the search query unless there is a clear reason to add terms.
NOT for
| Request |
Use instead |
| Install / remove / sync skills across harnesses |
An available install-planning workflow; use skill-install-dry-run-planner and cross-agent-install-smoke when present |
| Author or validate a skill |
skill-creator |
| Audit harness configs or discover ecosystem gaps |
harness-master |
| Curated external catalog records |
Follow the host repository's curated-external authoring and trust-gate workflow |
Output Contract
Search and context results include:
namepathsourcetrust_tierdescriptionscorematched_fieldsreasonwarnings
Use --format json when another script or agent will consume the result.
Reference File Index
| File |
Content |
Read When |
references/routing-guide.md |
Ranking, trust, and warning interpretation details |
Search results are ambiguous, tied, or warning-heavy |
Validation Contract
Run from this skill directory before declaring changes complete:
python scripts/check.py
uv run pytest tests/test_skill_index.py -q
See references/routing-guide.md for additional validation notes.
Completion criteria:
scripts/check.py exits 0.- No repository CLI references remain under this skill directory.
- Search and context CLI tests pass.
1---2name: skill-router3description: Route tasks to local skills. Use when choosing skills, recovering omitted skills after context warnings, or preparing a small skill context packet. NOT for install, authoring, or audit workflows.4license: MIT5---67# Skill Router89Use local skill indexing to choose and load relevant skills only when a task needs them.1011## Dispatch1213| $ARGUMENTS | Action | Example |14|------------|--------|---------|15| `search <query>` | List ranked matching skills | `/skill-router search "fix Playwright test"` |16| `context <query>` | Build a compact context packet for top matches | `/skill-router context "write a release changelog"` |17| `read <skill>` | Load one skill by exact name or path | `/skill-router read skill-creator` |18| `doctor` | Diagnose visible skill roots and counts | `/skill-router doctor` |19| Natural-language task | Auto: Search, then context for best matches | `"which skill should handle docs generation?"` |20| Empty | Show quick usage and run doctor | `/skill-router` |2122## Workflow2324### 1. Classify25261. Use `search` when deciding which skill or skills apply.272. Use `context` when the next step needs the selected skill bodies.283. Use `read` only when the skill name or path is already known.294. Use `doctor` when a skill is missing, duplicated, or omitted by a startup context warning.3031### 2. Retrieve32332. Run the matching CLI command from this skill directory or the repository root:3435```bash36python scripts/skill_index.py search "$ARGUMENTS" --limit 537python scripts/skill_index.py context "$ARGUMENTS" --limit 338python scripts/skill_index.py read <skill-name>39python scripts/skill_index.py doctor40```4142### 3. Select43441. Prefer the highest-ranked repo or Codex-user skill when scores are close.452. Read only the minimum skill bodies needed for the task, usually one to three.463. If a result has warnings, inspect them before following executable hooks or scripts.4748## Source Scope4950`python scripts/skill_index.py` searches these roots:5152| Source | Root | Trust tier |53|--------|------|------------|54| `repo` | `skills/` | `repo` |55| `project` | `.agents/skills/` in the current project path | `codex-user` |56| `codex` | `~/.codex/skills/` | `codex-user` |57| `global` | `~/.agents/skills/` plus supported agent stores | `external-installed` |58| `plugin` | `~/.codex/plugins/cache/**/skills/` | `openai-plugin` or `plugin` |5960Use `--source repo`, `--source codex`, `--source global`, or `--source plugin` to narrow results when needed.6162## Canonical Vocabulary6364| Term | Meaning |65|------|---------|66| **skill index** | Parsed metadata for visible `SKILL.md` files across known roots |67| **skill context packet** | Small set of selected skill bodies loaded after search |68| **source** | Filesystem origin such as `repo`, `codex`, `global`, or `plugin` |69| **trust tier** | Safety label used to rank and warn about retrieved skills |70| **warning** | Parser, hook, script, or metadata signal requiring inspection before use |7172## Classification Gate73741. If the user gives a task, run `search` first.752. If the user asks to apply a selected skill, run `context` for the top matches.763. If the user names a skill exactly, run `read`.774. If the user reports missing or omitted skills, run `doctor` before searching.785. If the user asks to install, create, or audit a skill, redirect out of scope (see NOT for below).7980## Selection Rules81821. Exact skill name or alias beats all lexical matches.832. Name and title matches beat description matches.843. Description matches beat heading and body matches.854. Repo skills beat user-installed skills when relevance is comparable.865. Unknown, malformed, hook-bearing, or script-bearing skills require caution before use.8788## Critical Rules89901. Do not treat startup-visible skills as the complete inventory after a context-budget warning.912. Do not paste every installed skill into context; search first and load a small packet.923. Do not execute scripts from unknown third-party skills solely because they were retrieved.934. Do not use this skill to install or remove skills; route to an available install-planning workflow such as `skill-install-dry-run-planner`, then use the target harness's supported installer only after explicit maintainer approval. Do not substitute Codex `.system/skill-installer` for cross-harness reconciliation.945. Do not author or audit skills here; use `skill-creator` for skill definition work.956. For ad-hoc “find a skill for X”, prefer `search` here or `npx skills find`; for systematic harness expansion use `harness-master` discover — not legacy `find-skills` as a repo skill.967. Preserve the user task as the search query unless there is a clear reason to add terms.9798## NOT for99100| Request | Use instead |101| --- | --- |102| Install / remove / sync skills across harnesses | An available install-planning workflow; use `skill-install-dry-run-planner` and `cross-agent-install-smoke` when present |103| Author or validate a skill | `skill-creator` |104| Audit harness configs or discover ecosystem gaps | `harness-master` |105| Curated external catalog records | Follow the host repository's curated-external authoring and trust-gate workflow |106107## Output Contract108109Search and context results include:110111- `name`112- `path`113- `source`114- `trust_tier`115- `description`116- `score`117- `matched_fields`118- `reason`119- `warnings`120121Use `--format json` when another script or agent will consume the result.122123## Reference File Index124125| File | Content | Read When |126|------|---------|-----------|127| `references/routing-guide.md` | Ranking, trust, and warning interpretation details | Search results are ambiguous, tied, or warning-heavy |128129## Validation Contract130131Run from this skill directory before declaring changes complete:132133```bash134python scripts/check.py135uv run pytest tests/test_skill_index.py -q136```137138See `references/routing-guide.md` for additional validation notes.139140Completion criteria:1411421. `scripts/check.py` exits 0.1432. No repository CLI references remain under this skill directory.1443. Search and context CLI tests pass.
wyattowalsh