# Agent Skill Router > Creates compact router skills for SKILL.md catalogs. Invoke when grouping related skills in .agents/skills or another local agent skill root. - Skill: `slepox/agent-skill-router` (Agent Skill, multi-file: 5 files) - Install (CLI): `npx skillmds@latest add slepox/agent-skill-router` - Raw SKILL.md: https://api.skillmd.com/api/skills/slepox/agent-skill-router/raw - Safety review: pending (external: skill-scanner PASS, skillspector CAUTION) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: slepox (https://skillmd.com/u/slepox) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/slepox/agent-skill-router --- # Agent Skill Router Use this skill when the user wants to group a set of related filesystem skills behind one router skill, scan a catalog for router opportunities, reduce skill catalog context, copy skills from one root into another root, repair child skill visibility, or refresh previously imported skill copies. This skill targets agents that use directory-backed `SKILL.md` files: ```text //SKILL.md ``` It is intentionally agent-neutral. Use `.agents/skills` examples by default, prefer an explicit `--root` path when the user gives one, and use the built-in presets only when the user asks for a known local agent root. ## Script The implementation lives next to this skill: ```bash python3 scripts/agent_skill_router.py --help ``` It has no third-party Python dependencies. ## Supported Presets Use `--print-presets` to inspect the current map. Presets resolve common local layouts such as: - `agents`: `.agents/skills` or `~/.agents/skills` - `claude-code`: `.claude/skills` or `~/.claude/skills` - `cline`: `.cline/skills` or `~/.cline/skills` - `codex`: `.agents/skills` or `~/.agents/skills` - `cursor`: `.cursor/skills` or `~/.cursor/skills` - `deepseek-harness`: `.dsh/skills` or `~/.dsh/skills` - `gemini-cli`: `.gemini/skills` or `~/.gemini/skills` - `github-copilot`: `.github/skills` or `~/.copilot/skills` - `goose`: `.agents/skills` or `~/.agents/skills` - `kilo-code`: `.kilo/skills` or `~/.kilo/skills` - `opencode`: `.opencode/skills` or `~/.config/opencode/skills` - `roo-code`: `.roo/skills` or `~/.roo/skills` - `trae`: `.trae/skills` or `~/.trae/skills` - `trae-cli`: `.traecli/skills` or `~/.traecli/skills` - `trae-cn`: `.trae/skills` or `~/.trae-cn/skills` - `vscode-copilot`: `.github/skills` or `~/.copilot/skills` - `windsurf`: `.windsurf/skills` or `~/.codeium/windsurf/skills` Unknown or custom agents should use `--root` directly. Do not add presets for agents whose documented extension mechanism is not a `SKILL.md` catalog. ## Workflow 1. Identify the destination skill root. - Use `--root ` for explicit paths. - Or use `--agent --scope project --workspace `. - Or use `--agent --scope user` for the user-level preset. 2. If the user has not already selected child skills, scan the catalog: ```bash python3 scripts/agent_skill_router.py \ --root .agents/skills \ --suggest-routers ``` Use `--suggest-min-size ` when the catalog needs a higher or lower bar than the default of 4 child skills. Treat suggestions as evidence, not commands: a shared prefix is only a discovery signal. A router is worthwhile only when inspected descriptions, headings, or body content show a coherent domain or workflow family. Use `--suggest-semantic-groups` only when the user wants broader non-prefix discovery; it can produce more candidates and needs stricter human review. 3. Select child skills with one or more of: - `--prefix ` - `--skill ` - `--skills-file ` 4. Preview the selected skills before changing files: ```bash python3 scripts/agent_skill_router.py \ --root .agents/skills \ --prefix \ --list-json ``` 5. Create a semantic router name and description from the selected child skill descriptions. Do not use a mechanical `*-router` name unless that is genuinely the clearest name. 6. Dry-run the write: ```bash python3 scripts/agent_skill_router.py \ --root .agents/skills \ --prefix \ --router-name \ --router-title "" \ --router-description "<description>" \ --dry-run ``` 7. Show the plan to the user before editing existing skill files. The side effect is that each selected child skill receives: ```yaml user-invocable: true disable-model-invocation: true ``` 8. After approval, rerun without `--dry-run`. 9. Verify: - The router `SKILL.md` exists and contains relative paths to child skills. - Child skill frontmatter contains the two visibility fields. - `routers.json` records the router. ## Importing From Another Root Use `--source-root` when the source catalog is not the destination catalog. The script copies selected source skill directories into the destination root, writes the router there, and records enough metadata for later refresh. ```bash python3 scripts/agent_skill_router.py \ --source-root <source-skills-root> \ --root <destination-skills-root> \ --prefix <prefix> \ --router-name <name> \ --router-title "<title>" \ --router-description "<description>" ``` Refresh recorded imports after the source catalog changes: ```bash python3 scripts/agent_skill_router.py --refresh-imports <router-name> ``` Add `--force` if the router table itself should be regenerated. ## Repairing If an agent or package manager updates child skills and removes visibility metadata, repair recorded routers: ```bash python3 scripts/agent_skill_router.py --repair ``` Or repair one router: ```bash python3 scripts/agent_skill_router.py --repair <router-name> ``` ## Router Registry (routers.json) Each router the script writes is recorded in `routers.json` (the sibling file of this skill). This registry is the memory that makes `--repair`, `--refresh-imports`, and `--list-records` work: those commands read the recorded selectors and paths instead of asking the user to re-specify them. Inspect the recorded routers before repairing or refreshing: ```bash python3 scripts/agent_skill_router.py --list-records ``` The file is `{"version": 1, "routers": [...]}`. Each router record stores: - `root`, `router_name`: destination skill root and router name; this pair is the unique key. Re-running with the same pair updates the entry in place. - `prefixes`, `exact_names`: the selectors used to match child skills. These are what `--repair` replays to re-apply visibility frontmatter. - `title`, `description`, `intro`: the router's `SKILL.md` text fields. - `created_at`, `updated_at`: ISO 8601 timestamps. - `source_root`, `import_mode`, `imported_directories`, `imported_at`: present only for imported routers, and used by `--refresh-imports` to re-copy from the source root. - `agent`, `scope`: present only when the router was resolved from a preset. Registry rules: - Use `--record-file <path>` to keep a separate registry, and pass the same path to later `--repair`, `--refresh-imports`, and `--list-records` calls. - Use `--no-record` for a one-off router that should not be tracked. - `--dry-run` never writes the registry. ## Router Quality Rules - Router names should describe the domain, platform, or workflow family. - Router descriptions must explain the domain and trigger conditions, not implementation mechanics. - Do not group unrelated skills just because they share a prefix. - Prefer router groups with concrete content evidence: overlapping product names, APIs, workflow terms, resource types, or trigger conditions. - If selected skills span separate domains, ask the user to narrow the selection or create multiple routers. - Keep child skill content unchanged except for the two visibility frontmatter fields.