1. 项目概述一个彻底改变LLM技能调用方式的“按需路由”方案如果你和我一样长期在Claude、Cursor这类AI编程工具里折腾肯定对“上下文窗口”又爱又恨。它像一块珍贵的画布但每次对话你都得把一堆可能用到的“技能说明书”也就是各种Skill一股脑儿塞进去生怕AI关键时刻掉链子。结果就是宝贵的Token被大量静态描述占用真正用于思考和输出的空间所剩无几。我手头一个项目里内置了230多个专业技能如果全量加载光是描述就得吃掉数万Token这简直是资源浪费。于是我花了几个月时间设计并实现了一个名为Skill Hub的解决方案。它的核心思想极其简单用9个固定工具的微小开销换来对海量技能的按需访问彻底告别技能描述常驻上下文的历史。简单来说Skill Hub扮演了一个“智能技能库管理员”的角色。它把所有技能Skill的详细说明书正文都存放在本地的“仓库”里而在与AI对话的上下文中只预先放置9个极其轻量的“工具调用指令”。当AI需要某个专业能力时——比如它想帮你写一段数据库优化代码或者设计一个用户界面——它不再需要从上下文中那堆冗长的描述里翻找而是通过这9个工具中的一个search_skills发出查询。Skill Hub接到指令后会快速在本地索引中检索如果找到了匹配的技能就将其完整的说明书动态加载到上下文中。用完后这个技能说明书就会被移出上下文始终保持清爽。这个过程对AI和用户来说几乎是透明的你感觉到的只是AI“突然”变得非常专业而背后是Skill Hub在高效地调度资源。这个方案特别适合那些深度集成MCPModel Context Protocol协议的工具生态比如Claude for Desktop、Cursor、Windsurf以及任何支持MCP Server的AI助手。它不是一个独立的APP而是一个标准的MCP Server可以无缝嵌入你的工作流。接下来我会详细拆解它的设计思路、实现细节并分享我在部署和扩展过程中踩过的坑和总结的经验。2. 核心设计为什么是“路由”而不是“仓库”很多同类工具把自己定位为“技能仓库”重点在于收集和展示。但Skill Hub的定位从第一天起就是“路由”。这两个字的差异决定了整个架构的天壤之别。仓库是静态的是目的地路由是动态的是调度中心。这个设计选择源于对LLM工作模式的两个关键洞察。2.1 洞察一LLM的“工作记忆”非常有限且昂贵我们可以把LLM的上下文窗口想象成它的“工作台”。这个工作台大小固定比如200K Token。传统做法是我们把可能用到的所有工具技能的说明书都摊开放在这个工作台上。即使当前只是在聊天写数据库代码的说明书、做UI设计的说明书、写法律文书的说明书也都占着地方。这导致两个问题第一真正用于处理当前任务比如写一段Python脚本的“操作空间”被严重挤压第二由于无关信息太多LLM有时反而会“分心”或产生混淆这就是所谓的“上下文污染”。Skill Hub的路由模式相当于把所有这些说明书都整理好放到了工作台旁边的书架上本地存储。工作台上只放一个目录索引9个工具的定义和一个图书管理员路由逻辑。当LLM需要某本书技能时它只需要对图书管理员说“请帮我找一下关于‘React性能优化’的书。” 管理员search_skills工具会快速查阅目录然后把那本书从书架上取下来放到工作台上。用完后书就被放回书架。工作台始终只为当前任务服务。2.2 洞察二LLM擅长语义理解但不擅长精确检索第二个洞察是关于分工的。很多系统试图用复杂的向量数据库、语义相似度算法来替LLM做检索和排序但这常常引入新的复杂度调参、维护、以及不可避免的“误判”。Skill Hub反其道而行之它承认并利用LLM自身的强项。它的搜索机制search_skills设计得非常“笨”——就是纯文本的Token匹配不评分、不排序、不搞语义相似度。比如你查询“如何设计一个登录按钮”。search_skills工具会机械地检查“设计”、“登录”、“按钮”这些词是否出现在任何一个技能组Group的ID、描述、关键词、别名里或者是否直接匹配某个技能的名称。它不会去理解“登录按钮”属于UI组件也不会去计算哪个技能描述和这句话最像。它只是返回所有包含这些Token的候选结果。那么谁来做最终的判断和选择是LLM自己。我们把语义理解这项LLM最擅长的工作完全交还给它。search_skills返回的结果里包含了匹配的技能组列表每个组都带有描述groupDescription和组内技能名称skillNames。LLM阅读这些信息后可以像人类一样判断“哦这个‘design’组看起来最相关里面有个叫‘ui-component-design’的技能应该就是我要的”。如果一次搜索没找到LLM还可以调用list_skill_groups浏览所有组的描述然后再调用list_group_skills查看某个组内的所有技能逐步逼近目标。这种“机械检索 智能决策”的分工让系统变得极其简单和稳定。检索部分几乎没有维护成本而决策部分则利用了LLM最强的能力。这是我在设计中最得意的一点。实操心得关于directMatch的妙用在search_skills的机制里有一个精妙的directMatch设计。当用户的查询词精确匹配某个技能的skillName或skillId时搜索结果里会额外附带这个技能的description。这相当于给LLM开了一个“快速预览”窗口。比如LLM明确知道它需要一个叫“python-decorator-advanced”的技能它发起搜索后不仅能知道这个技能在哪个组还能直接看到这个技能的简短描述从而立刻确认“对就是这个”无需再走“列出组内技能”的步骤。这个设计极大地优化了已知技能名的调用路径减少了不必要的工具调用回合提升了效率。在规划你自己的技能命名时尽量使用清晰、无歧义的ID能最大化利用这个特性。3. 架构与存储一个清晰、可扩展的本地文件系统一个设计良好的路由系统背后必须有一个稳定、清晰的数据存储结构。Skill Hub没有使用数据库而是选择了基于文件系统的存储方案。这基于几个考虑第一简化部署无需额外依赖第二方便版本管理和备份直接git管理第三对人类友好开发者可以直观地浏览和修改技能内容。它的目录结构设计得像一个精心规划的图书馆。3.1 核心目录结构解析data/hub/ ├── config/ │ └── groups.json # 图书馆的“分类法”总纲 ├── packages/ # 藏书区所有技能包 │ └── {skill-id}/ │ ├── SKILL.md # 技能正文必选核心藏书 │ ├── meta.json # 图书卡片自动生成含索引信息 │ ├── references/ # 参考书区可选相关文档 │ └── assets/ # 附件区可选图片、配置文件等 ├── staging/ # 新书编目区运行时临时区域 │ ├── imports/ # 待审查的新书 │ └── repaired/ # 已修复格式的新书 ├── index/ # 卡片目录索引运行时自动维护 └── logs/ # 图书馆工作日志1.config/groups.json- 分类体系的核心这个文件定义了技能的“分类法”。Skill Hub内置了16个大类Group如engineering工程、design设计、product产品等。每个组本质上是一个标签过滤器。技能在入库索引时系统会读取其关键词并计算与每个组关键词的匹配度自动将其归入最相关的组。groups.json文件定义了每个组的ID、描述、以及用于匹配的关键词和别名。你可以通过manage_group工具动态修改这个文件增加自定义组。2.packages/{skill-id}/- 技能的物理存在这是技能的“家”。每个技能都是一个独立的目录目录名就是技能的ID如python-async-advanced。里面必须有一个SKILL.md文件这是技能的正文。它采用标准的Markdown格式并且必须在文件开头包含Frontmatter至少提供name和description两个字段。这个描述非常重要它是搜索索引和组分类的主要依据。--- name: react-performance-optimization description: 深入讲解React应用性能分析与优化技巧包括Profiler使用、Memoization、代码分割、懒加载等。 --- # React性能优化指南 ## 1. 识别性能瓶颈 ...meta.json是系统自动生成的包含了从SKILL.md的Frontmatter和内容中提取的标准化信息如技能名称、描述、提取的关键词、所属的组、创建时间等。你一般不需要手动编辑它。references/和assets/是可选目录用于存放该技能相关的额外文件比如示例代码、配置模板、示意图等。当通过read_skill工具加载技能时这些文件的信息也会一并提供给LLM。3.staging/- 安全的“沙箱”区域这是为了保证数据安全而设计的中转区。当你使用install_skills工具从外部目录批量安装技能包时文件并不会直接拷贝到packages/下。而是先被复制到staging/imports/目录下。系统会在这里对新技能包进行格式校验、冲突检查等。如果发现有格式问题比如缺少SKILL.md系统会尝试自动修复并将修复后的版本移到staging/repaired/。只有经过这些步骤确认无误后技能才会被正式“安装”到packages/目录并建立索引。这个过程有效防止了损坏的或格式错误的技能包污染主仓库。4.index/- 高速检索的引擎这是运行时自动生成和维护的索引数据。它本质上是一系列JSON文件将packages/目录下的所有技能信息名称、描述、关键词、所属组、路径等预先加载并结构化以便search_skills等工具能够进行毫秒级的检索。当packages/目录下的文件有任何变化增、删、改时索引会自动更新。3.2 环境变量灵活定制你的HubSkill Hub通过几个环境变量提供了高度的可定制性让你可以根据自己的机器环境和需求进行调整。变量名默认值说明与调优建议SKILL_HUB_ROOT项目根目录/data/hub最重要的配置。你可以将它设置为一个绝对路径例如/Users/yourname/Documents/my-skills。这样你的技能库就可以脱离Skill Hub的安装目录独立存在方便在多台机器间同步用网盘或Git也便于备份。SKILL_ROUTER_SEARCH_LIMIT8search_skills返回结果的最大数量。如果技能库很大超过500个适当调高这个值比如到15可以让LLM在第一次搜索时看到更多候选减少后续list_skill_groups的调用。但注意返回太多结果也会占用上下文。SKILL_ROUTER_MAX_KEYWORDS12系统从每个技能描述中自动提取的关键词最大数量。如果你发现某些技能的关键词提取不准确导致分组错误可以尝试调低这个值比如到8让提取更聚焦于核心词汇。SKILL_ROUTER_MAX_RELATED_SKILLS5read_skill工具返回时同时返回的关联技能数量。关联技能是基于关键词相似度计算的。这个功能很棒相当于“看了这本书的人也看了这些书”。保持默认值5通常是个好选择。SKILL_ROUTER_WATCH1是否启用文件监听热重载。设置为0可以禁用。如果你在资源受限的环境下运行或者技能库非常稳定不常改动禁用监听可以节省少量系统资源。但绝大多数情况建议保持开启。注意事项路径与权限陷阱当你自定义SKILL_HUB_ROOT时最常见的坑是路径权限问题。确保运行MCP Server的进程比如你的Claude Desktop有对该路径的读写权限。在Linux/macOS上可能需要检查目录的chmod设置在Windows上可能需要以管理员身份运行或调整文件夹安全属性。另一个坑是相对路径。强烈建议使用绝对路径。例如不要用~/Documents/skills虽然Shell能解析有些Node.js环境下的子进程可能无法正确解析~导致找不到目录。最稳妥的方式是使用完整的绝对路径如/home/username/Documents/skills或C:\Users\username\Documents\skills。4. 九大工具详解从路由到管理的完整闭环Skill Hub的核心功能通过9个工具暴露给LLM。这9个工具构成了一个完整的闭环从搜索发现、阅读使用到安装管理。它们被精心设计成只读和读写两类兼顾了安全性和灵活性。4.1 只读工具技能发现与使用的核心路径这6个工具是LLM与技能库交互的主要接口它们不会修改技能库的任何内容。1.search_skills(query: string)- 智能检索的起点这是最常用、也是最核心的入口工具。它接收一个查询字符串在技能索引中进行Token匹配。输入一个描述你需求的字符串例如“帮我优化Python代码性能”。输出一个包含groups字段的数组。每个匹配的组会包含groupDescription组描述、skillNames组内匹配的技能名列表以及可选的directMatch如果查询精确匹配了某个技能会包含该技能的描述。工作流程LLM拿到结果后会阅读groupDescription和skillNames。如果某个组看起来高度相关并且skillNames里有合适的技能LLM可以决定直接调用read_skill。如果结果不理想LLM会进入标准路径调用list_skill_groups。2.list_skill_groups()- 浏览全局分类当search_skills没有直接命中时或者LLM想了解技能库的全貌时调用此工具。输入无。输出列出所有技能组Group的ID和描述。这是LLM进行“人工”筛选的依据。LLM会像人类浏览目录一样阅读这些描述例如“engineering- 软件开发、系统架构、DevOps相关”、“design- 用户界面、用户体验、视觉设计”然后选择一个最相关的组。3.list_group_skills(group: string)- 查看组内详情在选定一个组之后调用此工具查看该组内所有技能的清单。输入一个技能组ID例如engineering。输出该组内所有技能的skillName和keywords列表。LLM通过阅读技能名称和关键词最终锁定它想要的那个具体技能。4.read_skill(skill: string)- 加载技能的终极目标这是路由的终点。当LLM确定了需要哪个技能后调用此工具。输入一个技能的ID或名称与skillName匹配。输出该技能的完整内容。包括SKILL.md的全文、references/目录下的文件列表和内容预览、assets/目录下的文件列表。此外还会返回最多5个关联技能的信息基于关键词相似度。这个技能的全部内容此刻被加载到上下文中LLM可以运用其中的专业知识来回答你的问题或执行任务。任务完成后这些内容会随着上下文滚动而自然被遗忘不会常驻。5.validate_skills()- 仓库健康检查用于检查技能库的完整性。它会扫描所有技能包检查必要的文件SKILL.md是否存在Frontmatter格式是否正确是否有重复的技能ID等。输入无。输出一个包含valid有效技能列表、invalid无效技能及错误原因、duplicates重复ID的报告。这个工具更多用于维护和调试。6.get_hub_status()- 系统状态快照查看Skill Hub的运行状态。输入无。输出包含技能总数、组总数、索引最后更新时间、文件监听器状态等信息。用于确认Skill Hub是否正常运行以及数据是否已成功加载。4.2 写操作工具扩展与管理你的私人技能库这3个工具赋予了用户和LLM管理技能库的能力。请注意在Claude等环境中默认可能不允许LLM执行写操作。你需要根据具体AI助手的权限设置来决定是否开放这些工具。7.install_skills(sourceDir: string)- 批量导入技能这是扩充技能库的主要方式。你可以将一个包含多个技能包目录的文件夹路径传给它。输入一个本地目录的绝对路径。工作流程该工具会将源目录下的所有子目录每个子目录视为一个技能包复制到staging/imports/目录然后进行校验、修复如果需要最后正式安装到packages/并更新索引。支持增量更新如果技能已存在会根据文件修改时间决定是否覆盖。典型场景你从GitHub上克隆了一个别人整理好的技能包集合或者你自己在本地整理了一批.md文件都可以通过这个工具一键导入。8.create_skill(skillId: string, name: string, description: string, content: string)- 快速创建新技能当你需要临时创建一个新的、个性化的技能时可以使用这个工具。输入skillId唯一标识符name显示名称description描述contentMarkdown格式的技能正文。输出在packages/{skillId}/目录下创建SKILL.md文件并自动生成meta.json。你可以随后手动向该目录添加references/和assets/文件。9.manage_group(mode: string, groupId: string, data?: object)- 管理技能组用于管理config/groups.json文件。模式create: 创建一个新组。需要提供data包含description和可选的keywords,aliases。update: 更新一个现有组。data包含要更新的字段。delete: 删除一个组。注意删除组不会删除组内的技能包这些技能在下次索引重建时会被重新分配到其他组或归入specialized-domain。实操心得工具的组合使用模式在实际对话中LLM使用这些工具的模式是动态且智能的。一个典型的深度工作流可能是这样的你提出一个复杂问题“我想设计一个高并发的WebSocket消息系统并考虑用Redis做发布订阅帮我规划一下技术选型和架构。”LLM首先调用search_skills(“websocket redis pubsub architecture”)。返回结果可能匹配了engineering组并直接命中了backend-architecture-patterns技能directMatch。LLM通过directMatch的描述确认后调用read_skill(“backend-architecture-patterns”)加载该技能。在运用该技能知识回答的过程中LLM发现还需要更具体的“Redis集群配置”知识。它再次调用search_skills(“redis cluster configuration”)这次可能没有直接命中但返回了engineering和devops组。LLM调用list_group_skills(“devops”)在列表中发现了redis-deployment-optimization技能。最后调用read_skill(“redis-deployment-optimization”)将第二个技能也加载进来。 最终LLM的上下文中包含了两个高度相关的专业技能它能够综合这些知识给你一个非常专业的回答。而整个过程中上下文里始终只有当前在用的一两个技能正文加上那9个轻量工具定义效率极高。5. 部署与集成让Skill Hub在你的工具链中运行起来理论讲得再多不如动手跑起来。Skill Hub的部署非常灵活你可以选择最方便的方式将其集成到你的AI工作流中。下面我将以最常用的Claude Desktop和Cursor为例详细讲解配置步骤。5.1 安装方式选择npx vs 源码方式一npx一键运行推荐给绝大多数用户这是最简单、最干净的方式。你不需要安装Node.js、Git也不需要克隆仓库。npx会自动从npm仓库下载最新的skill-router-mcp包并运行它。你只需要在MCP配置文件中指定命令即可。优点零环境依赖只要你的系统能运行npx通常安装Node.js后就有就能用。自动更新每次运行都会检查并使用最新版本除非你有本地缓存。隔离性好不会污染你的全局环境或项目目录。方式二从源码安装适合开发者或需要深度定制如果你想研究代码、修改逻辑或者希望将Skill Hub作为一个子模块集成到自己的项目中可以选择源码安装。git clone https://github.com/halflifezyf2680/skill-hub.git cd skill-hub npm install # 或 pnpm install, yarn install安装后你需要使用项目的本地启动命令来运行MCP Server。5.2 配置Claude DesktopClaude Desktop是目前集成MCP最成熟的产品之一。配置Skill Hub作为其MCP Server后你可以在任何对话中直接使用这些技能工具。1. 找到配置文件macOS:~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:%APPDATA%\Claude\claude_desktop_config.jsonLinux:~/.config/Claude/claude_desktop_config.json如果文件或目录不存在手动创建即可。2. 编辑配置文件使用你喜欢的文本编辑器如VS Code、记事本打开该文件。如果文件是空的就从一个大括号{}开始写。如果已有内容确保格式正确。对于npx方式添加如下配置{ mcpServers: { skill-hub: { command: npx, args: [-y, skill-router-mcp] } } }对于源码安装方式假设你的skill-hub克隆在/Users/you/projects/skill-hub{ mcpServers: { skill-hub: { command: npm, args: [run, skill-hub], cwd: /Users/you/projects/skill-hub } } }这里cwd当前工作目录参数至关重要它告诉Claude Desktop在哪个目录下执行npm run skill-hub这个命令。3. 重启Claude Desktop保存配置文件后完全退出并重新启动Claude Desktop。这是必须的步骤因为它只在启动时读取一次配置。4. 验证集成启动后新建一个对话。你应该能在Claude的工具栏或附件按钮附近看到一个新的“技能”或“工具”图标不同版本UI可能不同。点击它如果能看到search_skills等工具列表说明集成成功。你也可以直接问Claude“你现在可以使用哪些工具” 它应该会列出包括Skill Hub工具在内的所有可用工具。5.3 配置Cursor IDECursor是另一个深度集成AI的代码编辑器它也支持MCP。配置方式与Claude Desktop类似。1. 找到或创建配置文件Cursor的MCP配置文件通常位于macOS/Linux:~/.cursor/mcp.jsonWindows:%USERPROFILE%\.cursor\mcp.json2. 编辑配置文件文件内容是一个MCP Server的数组。添加Skill Hub的配置[ { name: skill-hub, command: npx, args: [-y, skill-router-mcp] } // ... 你可以在这里添加其他MCP Server ]同样源码安装方式需要指定cwd。3. 重启Cursor保存文件重启Cursor。你可以在Chat界面中测试工具是否可用。5.4 配置其他支持MCP的工具任何支持MCP协议的工具其配置逻辑都是相通的在指定位置创建一个JSON配置文件声明MCP Server的名称、启动命令和参数。你可以查阅对应工具的官方文档找到配置MCP的部分。Windsurf、Continue.dev等编辑器/插件也正在逐步加入对MCP的支持。避坑指南配置失败的常见原因路径错误源码安装时cwd指定的路径必须精确到skill-hub项目的根目录即包含package.json的目录。一个常见的错误是指定到了skill-hub的子目录如.../skill-hub/src。命令不存在确保npx或npm在你的系统PATH环境变量中。可以在终端输入npx --version或npm --version来验证。端口冲突MCP Server默认会监听一个端口。如果该端口被占用启动会失败。Skill Hub内部会处理端口选择但如果你在同一台机器运行多个实例可能会有问题。确保只配置一个Skill Hub实例。权限问题在Linux/macOS上确保配置文件如claude_desktop_config.json的读写权限正确。在Windows上如果Claude Desktop安装在受保护目录尝试以管理员身份运行一次。缓存问题有时Claude Desktop会缓存旧的配置或工具列表。如果配置正确但工具不出现尝试彻底退出Claude Desktop包括在任务栏/活动监视器中结束所有相关进程然后重新启动。6. 技能生态与扩展打造你的私人AI智库Skill Hub内置了230多个技能这只是一个强大的起点。真正的威力在于你可以轻松地导入任何Markdown格式的知识文档将其转化为AI可调用的技能持续扩充你的私人智库。6.1 内置技能来源与质量项目初期集成了三个高质量的开源知识库这保证了技能内容的专业性和实用性agency-agents-zh提供了211个中文AI智能体专家知识覆盖编程、写作、营销、法律、医疗等多个垂直领域。这些技能的特点是“角色化”例如“资深Python后端工程师”、“品牌文案策划专家”能让AI更好地模拟特定专家的思维和口吻。awesome-design-md聚焦于品牌设计系统包含设计原则、色彩理论、排版规范、组件库等知识对于UI/UX设计和前端开发非常有帮助。superpowers一个AI编程工作流技能框架包含了许多代码重构、调试、测试、架构设计方面的具体技巧和步骤。这些技能都经过了格式标准化处理确保了SKILL.md的Frontmatter完整内容结构清晰。你可以通过validate_skills()工具查看所有内置技能的状态。6.2 如何导入你自己的技能包这是Skill Hub最激动人心的部分。假设你公司内部有一个很好的技术Wiki或者你在个人笔记里积累了大量某个领域的知识你都可以将它们变成技能。步骤一准备技能包目录结构创建一个文件夹比如叫my-custom-skills。在里面为你每个想要导入的知识点创建一个子目录。子目录名就是技能ID建议使用英文小写和连字符如my-company-onboarding。my-custom-skills/ ├── efficient-meeting-guide/ │ └── SKILL.md ├── sql-query-optimization/ │ └── SKILL.md └── project-retrospective-template/ ├── SKILL.md └── assets/ └── retrospective-board.png步骤二编写SKILL.md每个技能目录下必须有一个SKILL.md文件。文件开头必须是YAML Frontmatter至少包含name和description。--- name: 高效会议指南 description: 基于公司实践总结的高效会议组织流程、会前准备清单、会中引导技巧和会后跟进模板旨在提升会议决策效率。 --- # 高效会议指南 ## 一、核心原则 - 会议必须有明确目标和预期产出... - 参会人员必须精简... ## 二、会前准备清单 1. **明确会议目标**填写会议目标表... 2. **准备议程**至少提前24小时发出... ## 三、会中引导技巧 ...步骤三通过工具导入在Claude对话中你可以直接告诉AI“请使用install_skills工具导入我放在/Users/you/Documents/my-custom-skills目录下的技能。” AI会调用该工具完成导入。你也可以在配置好Skill Hub后在支持文件操作的AI对话中直接上传整个目录如果AI支持的话。步骤四验证与使用导入完成后让AI调用validate_skills()看看有没有错误然后尝试用search_skills搜索你新导入的技能关键词比如“会议”看看是否能找到并成功加载read_skill。6.3 创建与管理自定义技能组内置的16个组可能无法完全覆盖你的需求。比如你导入了很多关于“区块链”或“物联网”的技能它们可能被分散在engineering和specialized-domain里。你可以创建一个专属组来管理它们。使用manage_group工具创建组manage_group(“create”, “blockchain”, {“description”: “区块链技术、加密货币、智能合约开发相关技能”, “keywords”: [“blockchain”, “crypto”, “smart contract”, “web3”, “分布式账本”]})技能重新归类创建组本身不会移动技能。技能是在索引时根据关键词自动归组的。你需要确保你的区块链相关技能的description和内容里包含了“blockchain”等关键词。下次索引重建或你手动触发重建时这些技能就会被自动归入新的blockchain组。你也可以通过修改技能的Frontmatter来增加关键词。更新或删除组同样使用manage_group工具选择update或delete模式即可。经验分享技能内容编写的黄金法则为了让Skill Hub的路由系统发挥最大效用你在编写或整理技能内容时可以遵循以下法则Frontmatter是门面name要简洁准确description要详尽且包含核心关键词。想象一下LLM仅凭这两行文字来决定是否加载这个技能。好的描述应该像一篇论文的摘要。结构清晰至上技能正文使用清晰的Markdown标题#,##,###组织内容。LLM在阅读时能更好地理解和定位信息。避免一整块没有结构的“散文式”内容。示例化与模板化多提供具体的代码示例、命令模板、检查清单、流程图用文字描述。例如一个“服务器安全加固”技能应该包含具体的iptables规则、sshd_config修改项、安全检查脚本而不是空谈原则。控制篇幅聚焦主题一个技能最好聚焦一个相对独立的主题。如果“React性能优化”和“React状态管理”都是大话题就拆成两个技能。技能正文不宜过长通常建议在2000-5000字以内过长的技能加载时会占用大量上下文违背了按需加载的初衷。如果内容确实很多可以拆分成“基础篇”、“进阶篇”或者利用references/目录存放扩展内容。善用关联在技能正文的末尾可以手动添加“相关技能”部分列出其他相关技能的ID。虽然系统会自动计算关联但手动关联往往更精准。这能引导LLM在解决复杂问题时形成一个连贯的技能调用链。7. 故障排查与性能优化实录即使设计得再完善在实际使用中总会遇到各种问题。下面是我在长期使用和测试Skill Hub过程中遇到的一些典型问题及其解决方案希望能帮你少走弯路。7.1 常见问题速查表问题现象可能原因排查步骤与解决方案Claude/Cursor中看不到Skill Hub工具1. MCP配置错误或路径不对。2. Skill Hub进程启动失败。3. AI客户端未重启。1.检查配置文件确保JSON格式正确无拼写错误路径是绝对路径源码安装时。2.查看日志在Skill Hub的data/hub/logs/目录下查看最新的日志文件看是否有错误信息。如果是npx方式可以在终端手动运行npx -y skill-router-mcp看能否启动。3.重启AI客户端确保完全退出后重新启动。search_skills搜不到已知技能1. 技能索引未更新。2. 查询词与技能关键词不匹配。3. 技能文件格式错误。1.触发索引更新尝试在packages/目录下新建一个空文件再删除监听器会自动重建索引。或重启Skill Hub进程。2.检查技能元数据用validate_skills()查看目标技能是否在有效列表中。检查其meta.json中的keywords是否包含你的查询词。3.尝试精确匹配使用技能的完整skillName或skillId进行搜索利用directMatch功能。read_skill加载失败或返回空1. 技能ID错误。2.SKILL.md文件损坏或权限不足。3. 技能目录被意外移动或删除。1.确认ID使用list_group_skills确认技能的确切ID。2.检查文件直接去packages/{skill-id}/目录下查看SKILL.md文件是否存在且可读。3.查看日志日志中通常会记录文件读取错误的具体信息。技能导入(install_skills)失败1. 源目录路径错误。2. 源目录内没有符合规范的技能包。3. 磁盘空间不足或权限问题。1.检查路径确保提供给工具的路径是绝对路径并且该路径存在。2.检查结构确保源目录下是多个子目录每个子目录里都有SKILL.md。3.查看staging/目录导入过程会在staging/imports/留下痕迹检查里面的文件和日志看具体卡在哪一步。性能感觉慢工具调用有延迟1. 技能库非常大1000个索引加载慢。2. 运行环境资源CPU/内存不足。3. 文件监听器(watch)在频繁触发索引更新。1.优化索引对于超大型技能库考虑按领域拆分成多个独立的Skill Hub实例。2.调整环境变量尝试设置SKILL_ROUTER_WATCH0禁用文件监听改为手动重启服务来更新索引。3.检查硬件确保运行MCP Server的机器有足够资源。自定义组不生效技能未归入1. 自定义组的关键词与技能内容不匹配。2. 索引在创建组之前已生成未重建。3. 技能的关键词权重低于其他组。1.重建索引最有效的方法是重启Skill Hub服务或者手动触发索引重建修改config/groups.json后保存监听器会检测到。2.强化关键词在自定义组的keywords和aliases中多设置一些相关的词。同时确保技能描述中也包含这些词。7.2 高级调试技巧如果上述方法无法解决问题你可以进行更深入的调试1. 启用详细日志Skill Hub默认的日志级别是INFO。你可以通过设置环境变量DEBUGskill-router:*来启用更详细的调试日志如果底层使用了debug库。这会在控制台输出大量的内部运行信息帮助你定位问题。2. 手动运行MCP Server进行测试脱离AI客户端在终端手动运行Skill Hub可以排除客户端配置的问题。npx方式打开终端直接运行npx -y skill-router-mcp。观察启动输出有无报错。源码方式进入项目目录运行npm run skill-hub。如果服务器能正常启动并监听端口说明Skill Hub本身没问题问题很可能出在AI客户端的配置上。3. 检查MCP通信MCP Server使用标准输入输出(stdin/stdout)或HTTP与客户端通信。你可以使用一些MCP调试工具如modelcontextprotocol/inspector来手动发送工具调用请求模拟AI客户端的行文从而判断是Server的问题还是Client的问题。4. 核验技能文件格式有时问题出在单个技能文件上。一个快速的检查方法是用validate_skills()工具它会列出所有无效的技能及其具体错误原因比如“Missing frontmatter”、“Invalid YAML”等。7.3 性能调优建议对于追求极致体验的用户这里有一些进阶调优建议SSD是关键Skill Hub的索引和文件读取都是IO密集型操作。将SKILL_HUB_ROOT指向固态硬盘(SSD)目录能显著提升搜索和加载速度。控制技能库规模虽然Skill Hub能处理大量技能但“少即是多”。定期清理过时、低质量或重复的技能。一个维护良好、高度相关的500技能库远比一个杂乱无章的2000技能库好用。结构化你的技能在references/目录下存放大的代码文件、数据集而不是全部塞进SKILL.md。read_skill工具会列出参考文件LLM在需要时可以指示你或它自己如果有文件读取权限去查看具体文件避免一次性加载过大的内容到上下文。考虑网络版部署如果你需要在多台设备间同步技能库可以将SKILL_HUB_ROOT设在一个云同步目录如Dropbox、iCloud Drive、OneDrive。但要注意云盘的实时同步可能会频繁触发文件监听导致索引不必要的重建。一个更稳定的方案是定期手动同步或者使用Git管理技能库在需要更新时手动拉取。经过几个月的深度使用Skill Hub已经彻底改变了我与AI协作的方式。它把AI从一个“什么都知道一点但都不够深”的通才变成了一个随时能召唤出顶级专家的智库。当我在写代码时它能调用“系统设计模式”技能在写文章时它能调用“叙事结构”技能在分析数据时它能调用“统计检验方法”技能。而这一切都不需要我预先在提示词里塞满冗长的指令。这种“能力即插即用”的体验才是AI助理工具应该有的样子。如果你也受困于上下文限制或者苦恼于如何让AI更专业地为你服务强烈建议你花半小时部署一下Skill Hub它带来的效率提升是立竿见影的。