skill-router

skill-router skill 概览

skill-router 是做什么的

skill-router skill 是多 skill Claude Code 工作流里的前置分流器。它不是直接完成任务，而是先分析请求、判断最适合调用哪个专用 skill；如果需求太模糊，无法高置信度路由，还会主动追问澄清。对于正在评估 agent-playbook，或者想把基于 skill 的工作流真正落到团队协作中的用户来说，skill-router 往往是最先帮你减少试错成本的那一环。

哪些人适合安装 skill-router

skill-router 最适合以下场景：你的环境里有不止一个 skill，而且经常会遇到这类提示——“这个该用哪个 skill？”，“帮我处理一下这个项目”，“给我用个 skill 解决”。它尤其适合：

• 需要统一 agent 选 skill 方式的团队
• 刚接触一套 skill 库的用户
• 同一个模糊请求，可能对应 review、debugging、docs、testing 或 design 等不同工作的流程

如果你平时只用一两个 skill，而且已经很清楚每种情况该调用哪个，那 skill-router 带来的增益就会比较有限。

skill-router 真正解决的问题

skill-router 真正要解决的，不只是“推荐一下用哪个”。它更重要的作用，是把一个定义不充分的请求转成可执行的下一步：选出一个 skill、说明为什么这么选，并补齐刚好足够推进任务的上下文。这一点很关键，因为很多 skill 系统并不是死在执行质量，而是在一开始的分流决策上就已经出错了。

skill-router 的关键差异点

和普通的“我该用什么工具？”提示词相比，skill-router 有几个更实用的优势：

• 它就是为“尽早触发”而设计的，避免一开始就选错专用 skill
• 它带有明确的目录映射思路，会把用户意图对应到已有 skill 清单
• 当意图不明确时，它支持继续澄清
• 它会通过 after_complete hook 记录路由决策；如果你想长期观察 skill 选择是怎么发生的，这点很有用

安装 skill-router 前最该先确认什么

在决定引入 skill-router 之前，先看两件事：

1. 你的环境里是否真的有一组值得被路由的下游 skills
2. 你的用户是否经常带着模糊目标进入，而不是一开始就把任务定义得很清楚

skill-router 最强的用法，是作为一个经过整理的 skill 生态里的分发入口。如果你的 skill 目录很小、长期没更新，或者已经做了大量定制却没有同步更新 router 逻辑，它作为独立组件的价值就会明显下降。

如何使用 skill-router skill

skill-router 的安装上下文

在这个仓库里，skill-router 位于 skills/skill-router。仓库 README 给出的安装方式是基于符号链接：

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

如果你的环境支持 skill manager，可以把安装路径改成你本地的 skill 目录。关键点是：SKILL.md 必须能被 Claude Code 的 skill loader 用预期的 skill 名称发现。

先看这两个文件

如果你想快速判断 skill-router 值不值得装，优先读：

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

SKILL.md 里有真正决定安装价值的信息：激活逻辑、允许使用的工具、路由行为，以及可用的 skill catalog。README.md 更适合看整体流程和示例，但和安装决策最相关的细节，主要还是在 SKILL.md。

什么时候应该先触发 skill-router

当请求在“该选哪个 skill”这一层还不够明确时，优先用 skill-router，比如：

• “帮我看看这个代码库”
• “用个 skill 优化一下这个”
• “这个 PR 我该用哪个 skill？”
• “我需要帮助，但不确定这是 debugging 还是 refactoring”

仓库里的定位很明确：skill-router 是处理 skill 相关请求的默认入口，尤其适合用户提到 “skill”、“which”、“how to”，或者明显表达不确定性的场景。

skill-router 需要什么输入信息

skill-router 在以下输入信息足够明确时效果最好：

• 任务目标
• 产物类型：PR、bug、README、test suite、design file、commit 等
• 期望结果
• 你对“需要哪种帮助”存在的疑问或不确定性

这些信息能让 router 更准确地把意图映射到合适的 skill，而不是退回到一轮又一轮的泛泛澄清。

把模糊请求改写成可路由的提示

较弱的输入：

• “Use a skill for my project”

更强的输入：

• “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?”

为什么后者更好：

• 明确了处理对象
• 说清了关注的质量维度
• 缩小了可能对应的 skill 类别
• 同时仍然把最终路由交给 skill-router

常见的 skill-router 使用方式

适合直接路由的例子：

• “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.”

适合先澄清再路由的例子：

• “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.”

skill-router 路由后的推荐工作流

一个实用的流程是：

1. 先用粗粒度任务触发 skill-router
2. 对它的澄清问题做简短但具体的回答
3. 确认它推荐的 skill
4. 带着整理后的任务描述切换到对应的专用 skill
5. 保留前面澄清出的上下文，让下游 skill 一开始就拿到足够信息

这正是 skill-router 的价值所在：把“意图模糊”到“可以明确调用专用 skill”之间的交接成本压缩掉。

你可以期待的 skill-router 目录分类

仓库摘录显示，skill-router 围绕一套 skill catalog 构建，覆盖的方向包括：

• 核心开发
• design 和 UX
• documentation 与 testing

目录中出现的 skill 示例包括 commit-helper、code-reviewer、debugger、refactoring-specialist、figma-designer，以及面向文档的相关 skills。这也意味着：只有当你的请求确实落在这些已编目类别里时，skill-router 的价值才会最大化。

使用 skill-router 的实际限制

skill-router 不能替代专用 skill。它是选择器，不是最终执行者。如果你的任务已经明确到可以直接交给 debugger 或 code-reviewer，那先走一遍路由，反而可能只是增加额外步骤。

它的效果也高度依赖 catalog 质量。如果你实际安装的 skills 和 SKILL.md 里的目录不一致，推荐结果就可能过时，甚至误导。

值得注意的工具与行为

这个 skill 被允许使用 Read、AskUserQuestion、WebSearch 和 Grep。实际使用中，最关键的能力是 AskUserQuestion，因为一旦在推荐前先消除歧义，路由质量通常会明显提升。

它还定义了一个面向 session-logger 的 after_complete hook，原因是 “Log skill routing decisions.” 如果你重视可审计性，或者想分析用户最常在哪类任务上分不清该用什么 skill，这个实现细节会很有价值。

skill-router skill 常见问题

skill-router 适合新手吗？

适合，尤其是面对一长串可用 skills、却不知道该从哪里开始的新手。skill-router 能把“我需要有人帮我处理 X”转成“下一步请用这个具体的 skill”，明显降低上手门槛。

skill-router 只适用于 Skill Discovery 吗？

不是，但 skill-router for Skill Discovery 确实是它最强的使用场景之一。除此之外，它也很适合作为团队工作流中的标准路由层：在这种场景里，比起每个人是否熟悉 skill 目录，更重要的是第一步分流是否一致。

skill-router 和普通提示词有什么不同？

普通提示词当然也可以让模型推荐一个 skill，但 skill-router 把这套行为封装成了一个可复用、可触发的 skill：有明确的激活信号、有已知的 catalog、也有澄清逻辑。这样一来，路由这一步会更稳定，也更容易纳入正式流程。

什么时候应该跳过 skill-router？

以下情况可以直接跳过：

• 你已经知道正确的专用 skill 是什么
• 你的环境里本来就只有很少几个 skills
• skill-router 里的 catalog 和你真实安装的 skill 集合不一致
• 你需要马上直接执行，而且当前几乎没有歧义

skill-router 在自定义 skill 生态里好用吗？

可以，但前提是你要让 catalog 和真实 skills 保持同步。router 的价值来自准确映射；在高度定制的环境里，最主要的落地风险就是目录条目过期。

安装 skill-router 值不值？

通常是值得的，尤其是在多人共用同一套 skill 库，或者用户经常提出范围很大、定义不充分的问题时。如果你对 skills 的使用是个人化、低频，而且自己早就清楚每种情况该怎么选，那安装它更像是“可选增强”，而不是刚需。

如何改进 skill-router skill

给 skill-router 更强的路由信号

想让 skill-router 更快给出靠谱结果，最直接的方法就是在第一轮输入里提供更好的信号。建议包含：

• 任务类型
• 目标对象或产物
• 期望结果
• 约束条件，比如语言、仓库范围、截止时间

例如，“I need help with a failing CI test in packages/api and want to isolate the root cause” 就比 “something is broken.” 更容易被正确路由。

回答澄清问题时给出决策级信息

当 skill-router 继续追问时，不要只回答 “just improve it” 这种泛化表达。更好的回答应该指出你到底想优化什么：correctness、readability、docs quality、UX fidelity、test coverage，还是 release readiness。因为这些信息会直接改变最终应该选择哪个 skill。

保持 skill catalog 最新

对 skill-router 来说，最大的结构性改进其实就是维护 catalog。一旦仓库新增、移除或重命名了下游 skills，就要及时更新 router。router 的上限，取决于它知道有哪些可选项。

增强 skill-router 的消歧规则

skill-router 最常见的失效方式，是相邻 skill 类别之间的边界不清，比如 debugging vs refactoring，或者 documentation vs review。改进方向是把以下几组信号区分得更明确：

• 问题诊断 vs 代码改进
• review vs generation
• 设计理解 vs 实现规划

为真实的模糊请求补充更多例子

这个 skill 已经提供了直接路由和模糊路由的示例。要进一步提升采用率，建议补充更多贴近真实内部需求的例子，比如：

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

这类示例能帮助用户更自然地组织请求，从而让 skill-router 给出更干净、更稳定的路由结果。

利用路由日志持续优化 skill-router

由于 skill-router 会通过 session-logger 记录路由决策，如果你能拿到这些日志，就应该定期回看。重点找：

• 反复出现的澄清循环
• 持续被错误路由的请求
• 常见但没有强匹配 skill 的意图类型

这是长期改进 skill-router 最实际、也最可执行的反馈闭环之一。

第一次推荐不准时，继续迭代而不是放弃

如果第一次推荐看起来接近正确，但又差一点，不要立刻放弃这个 skill。更好的做法是补充缺失上下文，重新表述任务：

• 具体处理的产物是什么？
• 你需要的是 diagnosis、review、generation，还是 restructuring？
• 什么结果算成功？

很多时候，只要补齐这些信息，第二轮就能把一个泛化推荐收敛成真正合适的专用 skill 交接。

用一条简单规则推动团队采用 skill-router

一条很好用的操作规则是：只要用户请求的重点是“找到正确的帮助类型”，而不是“执行一个已经定义清楚的任务”，就先用 skill-router。这样可以让 router 聚焦在最有价值的分流环节，而不是被硬塞进所有工作流里。