skill-router

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.

skill-router754 wordsMITRepo-owned

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.

Quick Start

Install:

npx skills add github:wyattowalsh/agents --skill skill-router -y -g --agent antigravity --agent claude-code --agent codex --agent crush --agent cursor --agent gemini-cli --agent github-copilot --agent grok --agent opencode

Use: /skill-router <search|context|read|doctor> [query]

Works with Claude Code, Gemini CLI, OpenCode, and other agentskills.io-compatible agents.

What It Does

Use local skill indexing to choose and load relevant skills only when a task needs them.

Modes

$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`

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; use skill-installer or npx skills workflows.
Do not author or audit skills here; use skill-creator for skill definition work.
Preserve the user task as the search query unless there is a clear reason to add terms.

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

Step — If the user gives a task, run search first.
Step — If the user asks to apply a selected skill, run context for the top matches.
Step — If the user names a skill exactly, run read.
Step — If the user reports missing or omitted skills, run doctor before searching.
Step — If the user asks to install, create, or audit a skill, redirect out of scope.

Selection Rules

Step — Exact skill name or alias beats all lexical matches.
Step — Name and title matches beat description matches.
Step — Description matches beat heading and body matches.
Step — Repo skills beat user-installed skills when relevance is comparable.
Step — Unknown, malformed, hook-bearing, or script-bearing skills require caution before use.

Output Contract

Search and context results include:

name
path
source
trust_tier
description
score
matched_fields
reason
warnings

Use --format json when another script or agent will consume the result.

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.

Field	Value
Source Type	`repo-owned`
Display Source	`github:wyattowalsh/agents`
Source Kind	`repo`
Installability	portable command
Review State	reviewed
Target Agents	`antigravity`, `claude-code`, `codex`, `crush`, `cursor`, `gemini-cli`, `github-copilot`, `grok`, `opencode`

Field	Value
Name	`skill-router`
License	MIT
Version	1.0.0
Author	wyattowalsh

Field	Value
Argument Hint	`[search

Field	Value
Compatibility	Requires Python 3.11+ with PyYAML; reads local SKILL.md files from repo, Codex, global, plugin, and supported agent skill roots via scripts/skill_index.py.

View Full SKILL.md

---
name: skill-router
description: >-
  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.
argument-hint: "<search|context|read|doctor> [query]"
license: MIT
compatibility: "Requires Python 3.11+ with PyYAML; reads local SKILL.md files from repo, Codex, global, plugin, and supported agent skill roots via scripts/skill_index.py."
metadata:
  author: wyattowalsh
  version: "1.0.0"
---

# 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

1. Use `search` when deciding which skill or skills apply.
2. Use `context` when the next step needs the selected skill bodies.
3. Use `read` only when the skill name or path is already known.
4. Use `doctor` when a skill is missing, duplicated, or omitted by a startup context warning.

### 2. Retrieve

2. Run the matching CLI command from this skill directory or the repository root:

```bash
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

1. Prefer the highest-ranked repo or Codex-user skill when scores are close.
2. Read only the minimum skill bodies needed for the task, usually one to three.
3. 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

1. If the user gives a task, run `search` first.
2. If the user asks to apply a selected skill, run `context` for the top matches.
3. If the user names a skill exactly, run `read`.
4. If the user reports missing or omitted skills, run `doctor` before searching.
5. If the user asks to install, create, or audit a skill, redirect out of scope.

## Selection Rules

1. Exact skill name or alias beats all lexical matches.
2. Name and title matches beat description matches.
3. Description matches beat heading and body matches.
4. Repo skills beat user-installed skills when relevance is comparable.
5. Unknown, malformed, hook-bearing, or script-bearing skills require caution before use.

## Critical Rules

1. Do not treat startup-visible skills as the complete inventory after a context-budget warning.
2. Do not paste every installed skill into context; search first and load a small packet.
3. Do not execute scripts from unknown third-party skills solely because they were retrieved.
4. Do not use this skill to install or remove skills; use `skill-installer` or `npx skills` workflows.
5. Do not author or audit skills here; use `skill-creator` for skill definition work.
6. Preserve the user task as the search query unless there is a clear reason to add terms.

## Output Contract

Search and context results include:

- `name`
- `path`
- `source`
- `trust_tier`
- `description`
- `score`
- `matched_fields`
- `reason`
- `warnings`

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:

```bash
python scripts/check.py
uv run pytest tests/test_skill_index.py -q
```

See `references/routing-guide.md` for additional validation notes.

Completion criteria:

1. `scripts/check.py` exits 0.
2. No repository CLI references remain under this skill directory.
3. Search and context CLI tests pass.

Download from GitHub

Resources

Skill Catalog Browse custom and external skills.

CLI Reference Install and manage skills.

agentskills.io The open ecosystem for cross-agent skills.

View source on GitHub