Claude Code 如何发现和筛选技能

Skill 没触发，先别急着改 description。按这篇文章的解释，一个磁盘上的 SKILL.md，要经过目录发现、候选暴露、任务匹配，才有机会被 Claude Code 加载。问题可能出在第一步，描述写得再好也没用。

作者梳理的是 Skill 从目录进入候选列表的规则，重点在来源归属、monorepo 目录继承、同名处理和路径条件。对维护团队 AI 工作流的程序员，这套拆分最有用的地方，是把「为什么没生效」变成可以逐层排查的问题。

Skill 没触发，到底卡在哪一步

文章把经常混称为「自动发现」的过程拆成三道门。

第一道是文件系统发现：Claude Code 是否会从这个位置加载 Skill。它不会搜索电脑里的所有 SKILL.md，文件存在，只能证明你写过它。

第二道是候选暴露：发现之后，这个 Skill 是否能进入模型可见的能力列表。仅供用户调用的 Skill，可以存在于磁盘上，却不参与模型的自动选择；路径条件和运行模式也可能影响可见性。

第三道才是任务匹配：模型根据 description 和用户请求，判断是否加载完整指令。前一篇讨论的元数据、激活后的完整指令、按需读取的辅助资源，发生在这套发现机制之后。

排查 Skill 不触发，应该先确认它进入了候选列表，再调整 description。

这里还有一个时间维度。作者称，Claude Code 会监视已纳入发现范围的 Skill 位置，新增、修改或删除 Skill，都可能更新会话里的候选列表。但如果开始监视时顶层 Skills 目录还不存在，后来才创建，可能需要重启。

候选列表更新，也不等于已经加载的指令被替换。磁盘文件、候选元数据、对话上下文里的有效指令，是三个不同状态。修改 SKILL.md 后继续沿用旧会话，不能仅凭文件内容判断模型当前拿到的是什么。

四种来源，应该按谁负责来选

作者区分了 personal、project、enterprise 和 plugin 四种来源。选择标准不是哪个目录方便，而是谁负责维护、谁应该获得这项能力。

Personal 适合跨项目的个人习惯，例如私人审查流程、笔记整理、提交信息辅助，以及依赖本机工具的封装。它跟着用户走，同事克隆仓库不会自动获得。

Project 适合仓库共同维护的流程，例如发布检查、项目迁移、架构文档生成和测试工作流。只有提交进 Git，它才会随仓库分发，修改也才能与业务代码一起接受审查。

Enterprise 面向组织集中提供的流程和知识。使用者未必能编辑源文件，但集中下发指令，不代表已经建立了强制执行机制。权限和执行边界仍是另一层事情。

Plugin 则是可安装的扩展组件，除了 Skills，还可以携带脚本、资源、subagents、hooks 和 MCP server 配置。它使用 /plugin-name:skill-name 这样的命名空间，避免直接争抢裸名称。

对于 enterprise、personal、project 中的同名 Skill，文章给出的优先级是：

Enterprise > Personal > Project

要留意 Personal 高于 Project：仓库里有同名定义，并不能直接推断当前会话采用的就是仓库版本。

另外，来源范围和同步机制不能混为一谈。本地 ~/.claude/skills/ 不会因为属于个人范围，就自动出现在另一台机器、Claude API 或 claude.ai 中。作者提到，符合条件的会话也支持从 claude.ai 账户同步 Skills，但那是独立机制，原文没有展开具体条件。

monorepo 里的可用范围，为什么跟文件路径有关

从 repo/apps/web/ 启动会话，根目录的发布 Skill 不应该凭空消失。文章称，Claude Code 会从启动目录向父目录查找，直到仓库根目录，因此 repo/.claude/skills/release-check/ 仍可被发现。

向上查找解决共享流程继承，嵌套发现解决包内差异。

例如根目录和 apps/web/ 各有一个 .claude/skills/deploy/SKILL.md。如果启动时递归扫描整个 monorepo，无关包、示例目录里的能力也可能挤进候选列表。作者描述的机制是：工作进入对应文件树时，嵌套 Skill 才变得相关。只处理 repo/backend/ 时，前端的部署流程不必出现。

这类同名情况，也不能直接套用前面的来源优先级。根目录和嵌套版本可以并存：/deploy 对应根目录入口，/apps/web:deploy 明确指向前端变体。目录限定名保留了两种流程的区别，而不是简单用最近目录覆盖。

如果只是希望同一份规则对特定文件生效，也不用复制 Skill 目录。原文用 paths 把共享 API 审查限制在相关文件范围：

---
name: api-review
description: Reviews this project's API design and compatibility
paths:
  - "services/api/**"
  - "packages/contracts/**"
---

关键是 paths 下的两个模式：规则由项目统一维护，自动相关性则取决于当前处理的文件是否匹配。

paths 是自动激活的相关性条件，不是文件权限，也不是沙箱。

仓库外的共享能力还有另一条入口：启动会话时通过 --add-dir 加入 shared-engineering，Claude Code 也会关注其中的 .claude/skills/，例如 incident-review/ 和 architecture-check/。但不能据此推断 commands、agents 等其他配置也按相同规则加载，作者明确把这些行为分开。

符号链接同样可以复用源目录。文章称 enterprise、personal、project 的 Skill 文件夹可以链接到其他目录，Claude Code 会解析目标，避免同一 Skill 因多个入口被重复加载；plugin 符号链接另有分发规则。个人开发这样做方便，团队稳定分发则更适合使用插件或明确纳入版本管理的项目 Skill。

我的判断

这篇最有价值的是排查框架。它把安装位置、来源归属、候选可见性、描述匹配拆开，能避免团队把所有故障都归因于「模型没理解」。

但这是一篇机制解读，不是效果评测。作者没有给出嵌套发现相较全仓扫描的候选数量、触发准确率或耗时对照，也没有展示具体 Claude Code 版本和完整复现实验。因此，「减少无关能力干扰」有合理解释，改善幅度却不能替它下结论。

嵌套 Skill 和根目录加 paths，也没有谁普遍更好。前者适合由某个包维护、操作流程确实不同的能力；后者适合统一维护、只按文件范围判断相关性的规则。只是文件类型不同就复制整套流程，会增加维护负担；部署步骤已经不同，还强塞进同一个 Skill，也会让指令难读。

另一个局限是，原文解释了很多候选不可见的原因，却没有给出统一的候选列表检查命令，也没写明用户专用调用的配置字段。它能帮助定位故障层级，还不足以直接充当完整操作手册。

能拿来做什么

• 给前端仓库排查 Skill 不触发时，先核对目录是否被发现、是否存在同名高优先级来源、路径条件是否匹配，最后再改 description。不要只靠反复换提示词试运气。
• 给 monorepo 安排部署流程时，可以保留根目录的 /deploy，再为前端包维护 /apps/web:deploy，让共享入口和包内变体各有明确归属。
• 给 API 和契约文件建立统一审查流程时，可以参考 api-review 的 paths 写法，集中维护 services/api/** 与 packages/contracts/** 的规则，并把实际访问权限交给独立机制处理。
• 分发团队能力前，先确定交付方式：项目 Skill 提交进 Git，插件按安装与版本分发，仓库外共享目录通过 --add-dir 引入。修改已激活的 Skill 后，也要区分候选更新和上下文里已经加载的指令。