route-skill

Recommend from the catalog; load a skill only after the user selects it.

Routing

• "Use dataviz" or agreement to your specific recommendation authorizes fetching and using that skill. Do not ask again.
• A mention, explanation request, or generic task is not selection. Read only the catalog and recommend when useful.
• A name the catalog does not have is a miss, not a cue to load the nearest match: list fails and names the keyword neighbours. Say the name was missing; do not load a neighbour, and do not hand-roll what the named skill would have done — an unavailable skill authorizes nothing.
• Consult the catalog for explicit discovery or a concrete capability gap. A task without a matching skill does not itself require discovery; proceed directly when available capabilities suffice. Avoid repeated recommendations after refusal.
• Announce the selected skill briefly. Prefer local files or cache; fetch only when absent or explicitly asked for the latest version.
• Cached files do not authorize automatic use in a later task. Existing native skills retain their own invocation rules.
• If several sources match, show their paths and ask which one. Never silently replace a selected source.

Commands

Resolve these scripts relative to this skill's directory, regardless of the working directory.

python3 scripts/route_skill.py list chart
python3 scripts/route_skill.py get dataviz
python3 scripts/route_skill.py get dataviz --refresh

list ranks by how many query words a skill matches, its file names included, and reads metadata only; retry without a query if nothing matches. It reports local scope and compatibility. get prints the SKILL.md path on stdout, with source/version on stderr. Read that file completely before use. Supporting paths are relative to its directory. Check the skill's requirements before running its scripts. If requirements are missing, explain them; do not install dependencies or switch hosts without the required authorization. If fetch fails, report it. Explicit refresh failure returns an error and preserves the old cache. Skill selection does not grant permission for unrelated actions or bypass native invocation restrictions.

Persistent selection

Default to this task only. Link only when the user explicitly requests project or global availability:

python3 scripts/route_skill.py link dataviz --project
python3 scripts/route_skill.py link route-skill
python3 scripts/route_skill.py unlink dataviz --project

A skill may restrict itself with agents: frontmatter (agents: [codex]; known: claude, codex, pi, hermes). link then creates only those agent mirrors, prunes the ones it owns elsewhere, and keeps the canonical .agents/skills link so sync still tracks it. Omit the field to allow every agent.

Links require a local checkout. Keep machine-specific project links out of commits. sync repairs only links owned by this checkout; it does not install new skills or edit other managers' lockfiles. Selection stays per-host: do not copy activation links or lists between joi (Arch) and mini (macOS). Keep Hammerspoon enabled only on mini/macOS and the joi housekeeping workflow only on joi. Cross-platform source can be shared without enabling every skill. Run python3 scripts/route_skill.py --help for source selection and other options.