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:

<skills-root>/<skill-name>/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:

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 <skills-root> for explicit paths.
   • Or use --agent <preset> --scope project --workspace <repo>.
   • Or use --agent <preset> --scope user for the user-level preset.
2. If the user has not already selected child skills, scan the catalog:

python3 scripts/agent_skill_router.py \
  --root .agents/skills \
  --suggest-routers

Use --suggest-min-size <n> 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 <prefix>
   • --skill <exact-name>
   • --skills-file <path>
4. Preview the selected skills before changing files:

python3 scripts/agent_skill_router.py \
  --root .agents/skills \
  --prefix <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:

python3 scripts/agent_skill_router.py \
  --root .agents/skills \
  --prefix <prefix> \
  --router-name <name> \
  --router-title "<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:

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.

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:

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:

python3 scripts/agent_skill_router.py --repair

Or repair one router:

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:

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.