本文摘要Skill 放对目录仍不生效是静默失败常被误判为模型问题。本文复现目录冲突、frontmatter 缺失与 instincts 抢占三种失败用日志确认加载。一、问题与结论从mattpocock/skills复制一个 Skill 到项目根目录的.agents/skills/敲/skills列表是空的把它挪进.claude/skills/列表还是空的装上 ECC 之后原本能触发的code-reviewSkill 也沉默了。三个现象看起来是三个 bug其实只有三类根因。结论先给第一Claude Code 只原生扫描.claude/skills/.agents/是社区多工具共用约定不在扫描范围内第二SKILL.md的 frontmatter 缺description或name与目录名不一致文件即使在正确路径也不会进索引第三ECC 的 instincts 在会话开始时先于 Skills 的描述匹配注入抢占了触发优先级。另外还有一条容易被忽略的已启动的会话不会重新扫描 Skills 目录改动后必须重启会话否则/skills给你的是缓存里的旧结果——这也是我明明改了怎么还没生效的直接来源。二、排查与选择依据按代价从低到高走三步每步都能独立证伪一个假设确认路径find . -name SKILL.md看文件到底落在哪个目录只有.claude/skills/下的会被扫描。确认 frontmatterhead -10打开文件检查name、description是否齐全且name与目录名一致。确认优先级禁用 ECC 后重启会话重复同一个请求若 Skill 恢复触发根因就是 instincts 抢占而非 Skill 配置错误。排查到第 3 步时通常已经要动配置了先看取舍。替代方案与取舍替代方案选择条件代价与边界以.claude/skills/为唯一真源ln -s到.agents/skillsClaude Code 是主力其他工具需要共读同一份 Skill一次软链接即可不支持符号链接的 CI 或 Windows 环境需改为复制脚本在CLAUDE.md中声明.agents/下存在 Skills团队坚持.agents/目录约定依赖上下文注入时机Skill 仍可能不进/skills索引效果需实测把 ECC 的 instincts 逐条改写成SKILL.md想保留 ECC 功能又消除优先级冲突需要读 ECC 源码并人工转化成本中等只细化 Skill 的description以提高触发优先级不愿改目录结构、也不想动插件改 frontmatter 即可但匹配逻辑在 Claude Code 内部效果未验证不该用本文方案的情况项目里 Claude Code 只是多个代理之一且各代理都坚持自己的扫描路径时强行统一到.claude/skills/会让其他工具失明——这时按工具分目录、用脚本同步比软链接更可控。三、关键原理Skills 的生效链路有四个环节任一环断裂都是静默失败扫描路径 → frontmatter 索引 → 会话级缓存 → 触发优先级。官方anthropics/skills仓库把标准路径定在.claude/skills/skill-name/SKILL.mdfrontmatter 的name与description共同构成身份与触发条件缺description时文件存在但不入索引。ECC 同时提供 Skills、instincts、memory 三类注入源其中 instincts 是会话级行为指令注入时机早于 Skills 的描述匹配——这就是插件启用顺序问题instincts 先到泛化指令吃掉了本该落到具体 Skill 的请求。四、可运行示例环境Claude Code 2.x、macOS 或 Linux、已安装 Git项目根目录下操作。mkdir-p.claude/skillsgitclone--depth1https://github.com/mattpocock/skills /tmp/skills-repofind/tmp/skills-repo-nameSKILL.mdcp-r/tmp/skills-repo/.agents/skills/repo-structure .claude/skills/repo-structurehead-10.claude/skills/repo-structure/SKILL.mdfind会显示该仓库的 Skill 全部位于.agents/之下复制后用head -10检查 frontmatter。随后重启 Claude Code 会话旧会话带着缓存不重启这一步等于白做执行/skills。预期输出/skills列出repo-structure说明路径与 frontmatter 都通过。实际输出未在本环境实测按上述失败条件推演repo-structure不在列表中——若文件确在.claude/skills/下则是 frontmatter 缺description若仍在.agents/skills/下则是路径未被扫描。常见失败与修复frontmatter 不完整或name与目录名不一致 → 在SKILL.md顶部补齐name、description并使两者与目录名相同改完仍不出现 → 退出并重启会话以丢弃扫描缓存重启后出现但调用时被泛化回答替代 → 禁用 ECC 对照确认 instincts 抢占。五、验证结果与边界可以确认的部分.agents/不在 Claude Code 原生扫描范围内.claude/skills/是官方仓库定义的路径frontmatter 字段缺失会导致不入索引。未验证的部分ECC instincts 与 Skills 的优先级关系是依据其Skills, instincts, memory功能描述的推断具体版本行为需实测调试日志能否直接打印扫描到的 Skill 清单也未在 2.x 上验证。本文方案适合 Claude Code 为主力的单工具工作流多代理共存、或依赖某个插件的会话级注入时目录统一与优先级假设都需要重新评估。参考资料anthropics/skillsmattpocock/skillsaffaan-m/ECC
