装完不触发、MCP 连不上：claude-skills 实操中高频踩的 5 个坑（附排查清单）

装完不触发、MCP 连不上：claude-skills 实操中高频踩的 5 个坑（附排查清单）

【免费下载链接】claude-skills380 Claude Code skills & agent skills & plugins (30+ Agents, 70+ custom commands, 380+ skills, customizable references, scripts)for Claude Code, Codex, Gemini CLI, Cursor, and 8 more coding agents — engineering, marketing, product, compliance, C-level advisory, research, business operations, commercial & finance, and your daily productivity skills.项目地址: https://gitcode.com/GitHub_Trending/cla/claude-skills

装一个技能包、/plugin install一条命令敲下去、满怀期待地输入触发词——结果模型像没看见一样继续干自己的事；或者技能是加载了，mcp__atlassian__createJiraIssue这类工具却一个都调不通。这不是个例。Claude Code 技能生态在过去一年迅速膨胀：以 claude-skills 为代表的仓库已经把技能做成了"标准化软件资产"，355 个生产级技能横跨工程、产品、营销、合规、C-Level 咨询、科研与日常效率，配套 602 个纯标准库 Python 工具，并原生兼容 Claude Code、Codex、Gemini CLI、Cursor 等 13 个编程代理。社区近期围绕"不触发、连不上"的求助帖、实操复盘也明显增多，问题高度集中在触发机制、MCP 配置、本地模型接入、跨平台适配和版本兼容五个环节。

本文不空谈原理，而是基于 claude-skills 仓库的真实文件结构、安装脚本与配置样例，把五个高频坑逐一拆开，最后给出一页纸排查清单。

坑 1：技能装完了，就是"不触发"

大多数人不触发，不是技能没装上，而是对触发机制的理解错了。Claude Code 生态里的技能触发不是"装了就自动生效"，而是基于SKILL.md的 frontmatter 语义匹配——模型读到你的请求后，把描述（description）与用户意图做语义比对，命中了才加载对应技能。这一点在仓库的跨平台文档中写得很明确：OpenClaw 按SKILL.md的 YAML frontmatter（name、description、tags）决定何时激活技能，"当你的 prompt 匹配 description 描述的使用场景时自动加载"（见 INSTALLATION.md）。也就是说，description 写得不精确、太宽泛或太窄，技能就等于没装。

由此衍生出三种高频场景：

场景 A：description 是"占位符"或纯技能名。这不是假设。claude-skills 的 CHANGELOG.md 里白纸黑字记录过一次事故：v2.0.0 批量导入时，有 21 个技能的 description 字段直接就是技能名本身——例如description: "Migration Architect"。这种描述对语义匹配几乎无用（"migration architect" 是角色而非任务描述），结果是技能永远不会被命中。仓库为此专门做了修复。如果你 fork 过老版本、或者从别的仓库复制过技能，第一件事就是检查 frontmatter 的 description 是否是"动词 + 场景 + 边界"的完整描述。

场景 B：装的是 deprecated 重定向技能。仓库里的 marketing-skill/skills/content-creator/SKILL.md 是一个很典型的案例：这个技能在 frontmatter 里明确标注status: deprecated，正文第一行就写着"该技能已被拆分为两个专家技能"，它本身不处理任何请求，只负责把"写文章"路由到 content-production、把"做内容规划"路由到 content-strategy。如果你照着老教程装了content-creator然后要求它写一篇带 SEO 的文章，得到的结果自然是"不触发"——因为它把所有请求都转发走了。装技能前先看 status 字段，比反复重装高效得多。

场景 C：装的位置/格式没被识别。仓库的自动转换脚本 scripts/convert.sh 在转换时会逐条读取 frontmatter，一旦name或description为空就直接跳过该技能并打印Skipping invalid frontmatter；而 scripts/sync-gemini-skills.py 里维护了一张DOMAIN_MAP，凡是不在映射表里的顶层目录（例如把技能随手扔进misc/）会被直接忽略，根本不会进入.gemini/skills/索引。装完不触发时，先跑一遍ls ~/.claude/skills/确认目录存在，再head -20检查 frontmatter 三段式（---包裹的name/description）是否完整。

坑 2：MCP 连不上，先分清是 stdio 还是 SSE

"技能加载了但 MCP 工具调不通"是第二个高频重灾区。claude-skills 里实际存在两种完全不同的 MCP 配置形态，排查路径截然不同：

形态一：SSE 远程服务器。仓库的 project-management/.mcp.json 是标准样例：

{ "mcpServers": { "atlassian": { "type": "sse", "url": "https://mcp.atlassian.com/v1/sse" } } }

这种形态的特点写在 project-management/README.md 里：SSE transport handles OAuth automatically——不需要任何环境变量，OAuth 由 Claude Code 自己完成。连不上时优先排查网络可达性（能否访问mcp.atlassian.com）和 OAuth 会话是否过期，而不是去补环境变量。

形态二：stdio 本地进程 + 环境变量。engineering-team/playwright-pro/.mcp.json 是典型样例：

{ "mcpServers": { "pw-testrail": { "command": "npx", "args": ["tsx", "${CLAUDE_PLUGIN_ROOT}/integrations/testrail-mcp/src/index.ts"], "env": { "TESTRAIL_URL": "${TESTRAIL_URL}", "TESTRAIL_USER": "${TESTRAIL_USER}", "TESTRAIL_API_KEY": "${TESTRAIL_API_KEY}" } } } }

这类配置有两个独立故障点：一是${TESTRAIL_URL}、${BROWSERSTACK_USERNAME}等环境变量在启动时未注入，server 进程起来就报错退出；二是${CLAUDE_PLUGIN_ROOT}这类占位符只有在以插件方式安装时才会被正确展开——如果你手动拷贝了技能目录而不是走/plugin install，占位符原样传给npx tsx，进程直接启动失败。所以排查顺序应该是：确认安装方式（插件 vs 手动拷贝）→ 确认 env 已导出 → 手动在终端把 command/args 跑一遍，看进程能否起来。

还有一个经常被忽略的检查点：工具命名规范。仓库自带的 engineering/skills/mcp-server-builder/scripts/mcp_validator.py 用^[a-z0-9_]{3,64}$校验工具名，而 project-management/references/atlassian-mcp-tools.md 专门强调：Atlassian MCP 的工具名是camelCase（mcp__atlassian__createJiraIssue），不是 snake_case，也不是 CLI 参数名——"永远不要发明工具名"。很多"连不上"其实是名字敲错了：文档里写的是 camelCase，你在 prompt 里用了 snake_case，模型找不到对应工具，表现和连接失败一模一样。以插件方式加载时前缀还可能变成mcp__plugin_<plugin>_atlassian__<toolName>，但尾部工具名不变。

坑 3：本地模型接入：技能能装，但"带不动"

不少用户把 claude-skills 装进本地模型（Ollama、本地部署的 LLM）或 Gemini CLI 后发现"完全不按技能走"。这里要分清技能的两类依赖：纯流程型技能和依赖型技能。

claude-skills 的大量技能是"流程驱动、零外部 API"的：SKILL.md 里是一套决策框架和检查清单，配套 Python 工具全部只用标准库（602 个脚本，零 pip 依赖），这类技能在任何模型上都能跑。README 中明确写到所有脚本"verified, stdlib-only"。

但另一类技能在 frontmatter 之外声明了对 MCP server、本地命令或外部服务的依赖，例如 project-management 领域的 Atlassian MCP（见坑 2）、marketing 里接 Google Search Console 的 SEO 技能。本地模型往往没有 Claude Code 的 MCP 客户端能力，或没有.mcp.json加载机制，装了也不会去调用工具，表现就是"技能像没装一样"。

接入 Gemini CLI 时还要注意另一层：仓库用 scripts/sync-gemini-skills.py 生成.gemini/skills/索引，技能通过activate_skill(name="senior-architect")显式激活，而且索引里每个技能带有source相对路径（../../../marketing-skill/...）。如果克隆后没跑./scripts/gemini-install.sh就手忙脚乱地激活，索引里根本没有这条记录，自然激活失败。本地模型场景下的正确姿势是：先确认技能是否依赖外部工具，再确认目标平台是否支持 MCP/技能索引加载机制。

坑 4：跨平台适配：同一份技能，13 个装法

claude-skills 宣传"一个仓库、13 个平台"，但这份便利恰恰是坑的来源——每个平台的加载路径和文件格式都不一样。仓库用 scripts/convert.sh 做格式转换，用 scripts/install.sh 做安装，两者的目标路径差异极大：

从 scripts/install.sh 的源码可以看到，同一个技能在不同平台的 frontmatter 会被重写：转 Cursor 时只保留description+globs+alwaysApply，转 OpenCode 时追加compatibility: opencode，转 Antigravity 时补上risk: low、source: community。这意味着：你在一个平台验证过的技能，直接复制文件夹到另一个平台大概率不触发——必须走convert.sh生成目标格式，再install.sh装到正确路径。

另一个隐蔽坑：convert.sh会以find扫描深度为条件发现候选技能（-mindepth 4 -maxdepth 6），嵌套过深或过浅的技能目录会被漏掉。所以"跨平台装了但数量不对"时，先对比转换汇总输出里的 converted/skipped 计数，而不是怀疑目标平台。

坑 5：版本兼容：升级一时爽，触发火葬场

技能仓库迭代极快。claude-skills 的 CHANGELOG.md 记录了明确的兼容性承诺：遵循语义化版本、patch 版本内不破坏向后兼容、不删除不重命名技能（多次出现 "No skill removals or renames"）。但现实踩坑集中在三个地方：

其一，deprecated 技能的"假触发"。仓库为了兼容老用户，会给被拆分/重构的技能保留一个重定向壳（见坑 1 的 content-creator）。这类技能会一直存在于插件里，如果你按旧文章写触发词，它每次都会"响应"但实际什么都不做。升级后行为突变，先查status: deprecated。

其二，本地 patch 被/plugin update覆盖。通过/plugin marketplace add alirezarezvani/claude-skills+/plugin install安装的技能是受管理的，执行/plugin update会用仓库新版本整体覆盖本地修改。很多人改完 description 或脚本后升级，发现改动消失、行为回退，误以为是"版本不兼容"。

其三，跨镜像索引不同步。仓库同时维护.gemini/、.codex/、.hermes/、.vibe/多份预生成索引，CHANGELOG 里甚至记录过某次更新中.hermes/skills-index.json因"完整重生成会带入 33 个无关新技能条目"而被手动 patch。如果你在多个平台同时使用，各平台索引可能短暂停留在不同版本——症状是"这个平台能触发，那个平台不能"。升级后如果发现索引与技能目录对不上，重新跑对应的sync-*.py脚本即可。

一页纸排查清单

把上面五个坑浓缩成一张可复制的检查单，建议按顺序执行：

这套流程覆盖了触发、连接、模型、平台与版本五个维度。社区里流传的各种"装完没反应"教程，绝大多数都能在这个清单的第 1~3 步和第 9 步里找到答案——技能生态的价值建立在"可复用、可版本化、可验证"之上，而这一切的前提，是先搞清楚你装的到底是什么、它靠什么被唤醒。

【免费下载链接】claude-skills380 Claude Code skills & agent skills & plugins (30+ Agents, 70+ custom commands, 380+ skills, customizable references, scripts)for Claude Code, Codex, Gemini CLI, Cursor, and 8 more coding agents — engineering, marketing, product, compliance, C-level advisory, research, business operations, commercial & finance, and your daily productivity skills.项目地址: https://gitcode.com/GitHub_Trending/cla/claude-skills