skill-router

Overview of skill-router skill

What skill-router does

The skill-router skill is a front-door selector for a multi-skill Claude Code setup. Instead of solving the task itself, it analyzes a request, decides which specialized skill fits best, and asks clarifying questions when the request is too vague to route confidently. If you are exploring agent-playbook or trying to make a skill-based workflow usable for teammates, skill-router is the piece that reduces guesswork first.

Who should install skill-router

skill-router is best for users who have more than one skill available and regularly face prompts like “which skill should I use?”, “help me with this project,” or “use a skill for this.” It is especially useful for:

• teams standardizing how agents pick skills
• users new to a skill library
• workflows where the same rough request could mean review, debugging, docs, testing, or design work

If you only use one or two skills and already know exactly which one to invoke, skill-router adds less value.

The real job to be done

The real job of skill-router is not just recommendation. It helps convert an underspecified request into a concrete next step: pick a skill, explain why, and gather just enough context to proceed. That matters because many skill systems fail at the first decision point, long before execution quality becomes the bottleneck.

Key differentiators of skill-router

Compared with a generic “which tool should I use?” prompt, skill-router has a few practical advantages:

• it is explicitly designed to trigger early, before the wrong specialist skill is chosen
• it includes a catalog mindset, mapping user intent to available skills
• it supports clarification when intent is ambiguous
• it logs routing decisions through an after_complete hook, which is useful if you want visibility into how skill selection happens over time

What matters most before you install

Before adopting skill-router, check two things:

1. whether your environment actually has a meaningful set of downstream skills to route to
2. whether your users often arrive with vague goals rather than precise task framing

The skill is strongest as a dispatcher in a curated skill ecosystem. It is weaker as a standalone asset if the catalog is small, outdated, or highly customized without matching updates to the router logic.

How to Use skill-router skill

skill-router install context

In this repository, skill-router lives at skills/skill-router. The repo README shows a symlink-based install pattern:

ln -s ~/Documents/code/GitHub/agent-playbook/skills/skill-router/SKILL.md ~/.claude/skills/skill-router.md

If your setup supports a skill manager, adapt the install path to your local skill directory. The important part is that the SKILL.md becomes discoverable by your Claude Code skill loader under the expected skill name.

Read these files first

For a fast evaluation, read:

1. skills/skill-router/SKILL.md
2. skills/skill-router/README.md

SKILL.md tells you the actual activation logic, allowed tools, routing behavior, and available skill catalog. README.md is useful for the higher-level flow and examples, but the install-decision details live primarily in SKILL.md.

When to trigger skill-router usage

Use skill-router first when the request is unclear at the skill-selection level, for example:

• “Help me with this codebase”
• “Use a skill to improve this”
• “Which skill should I use for this PR?”
• “I need help, but I’m not sure if this is debugging or refactoring”

The repository explicitly positions skill-router as the default entry point for skill-related requests, especially when the user mentions “skill,” “which,” or “how to,” or signals uncertainty.

What input skill-router needs

skill-router works best when the input includes:

• the task goal
• the artifact type: PR, bug, README, test suite, design file, commit, etc.
• the desired outcome
• any uncertainty about what kind of help is needed

That gives the router enough signal to map intent to a skill instead of falling back to broad clarification.

Turn a vague request into a routable prompt

Weak input:

• “Use a skill for my project”

Stronger input:

• “I need help reviewing a pull request for a Node.js API. I want feedback on correctness, security, and maintainability. Which skill should I use?”

Why this is better:

• names the object of work
• states quality dimensions
• narrows the likely skill category
• still leaves routing to skill-router

Example skill-router usage patterns

For direct routing:

• “Which skill should I use to write a clean commit message for these staged changes?”
• “I need to diagnose a failing test suite in a Python service. What skill fits best?”
• “Use skill-router for Skill Discovery across docs, testing, and refactoring tasks in this repo.”

For ambiguous routing where clarification is expected:

• “Help me improve this project before release.”
• “Use a skill for this design handoff.”
• “I’m stuck and not sure whether I need debugging, review, or refactoring.”

Suggested workflow after routing

A practical workflow is:

1. invoke skill-router with the rough task
2. answer its clarification questions briefly but concretely
3. confirm the recommended skill
4. switch to the specialist skill with the refined task statement
5. keep the clarified context so the downstream skill starts with enough detail

This is where skill-router creates value: it compresses the handoff from vague intent to actionable specialist invocation.

Available catalog categories to expect

The repository excerpts show skill-router is built around a catalog that includes areas such as:

• core development
• design and UX
• documentation and testing

Examples named in the catalog include commit-helper, code-reviewer, debugger, refactoring-specialist, figma-designer, and documentation-oriented skills. That means skill-router is most useful when your request fits one of these cataloged lanes.

Practical limits of skill-router usage

skill-router does not replace specialist skills. It is a selector, not the final executor. If your task is already precise enough to go directly to debugger or code-reviewer, routing first may be unnecessary overhead.

It also depends on catalog quality. If your actual installed skills differ from the catalog in SKILL.md, the recommendation can become stale or misleading.

Tools and behavior worth noting

The skill is allowed to use Read, AskUserQuestion, WebSearch, and Grep. In practice, the most important capability here is AskUserQuestion, because routing quality improves sharply when ambiguity is resolved before recommendation.

It also defines an after_complete hook for session-logger with the reason “Log skill routing decisions.” That is a useful implementation detail if you care about auditability or analyzing which tasks users struggle to classify.

skill-router skill FAQ

Is skill-router good for beginners?

Yes, especially if beginners see a long list of available skills and do not know where to start. skill-router lowers the entry barrier by turning “I need help with X” into “use this specific skill next.”

Is skill-router only for Skill Discovery?

No, but skill-router for Skill Discovery is one of its strongest use cases. It is also useful as a standard routing layer in team workflows, where consistent first-step triage matters more than individual familiarity with the catalog.

How is skill-router different from an ordinary prompt?

An ordinary prompt can ask the model to recommend a skill, but skill-router packages that behavior into a reusable, triggerable skill with explicit activation cues, a known catalog, and clarification logic. That makes the routing step more consistent and easier to operationalize.

When should I skip skill-router?

Skip it when:

• you already know the correct specialist skill
• your environment has very few skills
• the catalog in skill-router does not reflect your actual installed skill set
• you want direct execution immediately and there is little ambiguity

Does skill-router work well in a custom skill ecosystem?

It can, but only if you keep the catalog aligned with your real skills. The router’s value comes from accurate mapping. In a heavily customized environment, stale catalog entries are the main adoption risk.

Is skill-router install effort justified?

Usually yes if multiple people use the same skill library or if users often ask broad, underspecified questions. If your skill usage is personal, infrequent, and already well understood, the install may be optional rather than essential.

How to Improve skill-router skill

Give skill-router better routing signals

The fastest way to improve skill-router results is to supply better first-pass inputs. Include:

• task type
• artifact or target
• desired outcome
• constraints such as language, repo area, or deadline

For example, “I need help with a failing CI test in packages/api and want to isolate the root cause” routes better than “something is broken.”

Answer clarification questions with decision-making detail

When skill-router asks follow-up questions, do not answer with generic phrases like “just improve it.” Better replies mention what kind of improvement you want: correctness, readability, docs quality, UX fidelity, test coverage, or release readiness. That changes which skill should be selected.

Keep the skill catalog current

The biggest structural improvement for skill-router is catalog maintenance. If the repository adds, removes, or renames downstream skills, update the router promptly. A router is only as good as the choices it knows about.

Add stronger disambiguation rules

The most common failure mode is overlap between nearby skill categories, such as debugging vs refactoring or documentation vs review. Improve skill-router by tightening the cues that separate:

• diagnosis from code improvement
• review from generation
• design interpretation from implementation planning

Improve examples for real ambiguous requests

The skill already shows direct and ambiguous examples. To make adoption easier, add more examples that mirror real internal requests, such as:

• release prep
• failing CI with unknown root cause
• “make this PR ready”
• converting design files into implementation tasks

Examples like these help users phrase requests in ways that produce cleaner routing.

Use routing logs to refine the skill

Because skill-router logs routing decisions through session-logger, review those logs if available. Look for:

• repeated clarification loops
• requests that are consistently misrouted
• common intents with no strong matching skill

That feedback loop is one of the most practical ways to improve skill-router over time.

Iterate after the first recommendation

If the first recommendation feels close but not quite right, do not abandon the skill immediately. Reframe the task with missing context:

• what exactly is the artifact?
• do you need diagnosis, review, generation, or restructuring?
• what outcome will define success?

This often turns a broad recommendation into the right specialist handoff on the second pass.

Improve team adoption with a simple rule

A useful operating rule is: use skill-router first whenever the user request is about finding the right kind of help rather than doing clearly defined work. This keeps the router focused on high-value triage instead of forcing it into every workflow.