Claude Code调用Skill失败：先查目录再查开关

Claude Code 调用 Skill 失败，先别改提示词。先确认磁盘上是否有一份名为 SKILL.md 的入口文件，再确认当前会话读不读得到那个目录，最后才看 frontmatter 开关有没有把自动调用或斜杠菜单关掉。站内通用 Agent 失败页覆盖权限、模型拒绝和外部 API；Hermes 的 URL 安装是另一条产品线。本页只处理 Claude Code。步骤与字段以 2026-09-14 核验的官方 Skills 文档为准，不凭记忆补界面。

先用症状选入口，不要从重装开始

官方文档把自定义命令并进了 Skill：.claude/commands/deploy.md 和 .claude/skills/deploy/SKILL.md 都会形成 /deploy，同时存在时跑 Skill。排错时先在磁盘上找目录加 SKILL.md，不要只在聊天记录里搜“已经装过”。

第一层：路径和发现范围

个人技能放在用户目录下的 .claude/skills/名称/SKILL.md，对所有项目可见。项目技能放在仓库的 .claude/skills/名称/SKILL.md，只服务这个项目。插件技能带插件前缀。目录名变成你输入的命令；name 字段主要影响列表里的显示名。文档写明：个人目录和项目目录都有同名 deploy 时，/deploy 走个人那一份。项目技能可以覆盖捆绑技能。排错时把实际路径写下来，不要凭“我记得装过”。

项目技能从你启动 Claude Code 的目录向上找到仓库根。从子目录启动，仍应拿到根上的项目技能。启动时要读取工作区以外的技能目录，文档给出的方式是 --add-dir 或会话里的 /add-dir。它会加载被添加目录里的 .claude/skills/。settings.json 里的 permissions.additionalDirectories 只给文件访问，不加载技能或命令。把营销仓库设成“可以读”却不出现 /技能名，先查是不是只加了附加目录权限。

嵌套技能不在启动时全部装入。你在某个子目录里读或改文件之后，该子目录的 .claude/skills/ 才进入本会话。在单体仓库根目录问“跑 frontend 的发布技能”，却从未打开 packages/frontend/ 下的文件，嵌套技能可以既不出现自动补全，也不能按名调用。最小验证：打开或让 Claude 读那个子目录里的任意文件，再查 /skills。

文档还写：Claude Code 会监视已存在的个人目录、项目目录以及 --add-dir 目录里的技能变更，通常不必重启。若会话开始时顶层 skills 目录还不存在，你是中途新建的，需要重启后才开始监视。成功信号：/skills 列表出现该名称，路径与你在磁盘上看到的一致。

第二层：frontmatter 把调用关掉了吗

SKILL.md 必须是 YAML 头加 Markdown 正文。description 建议填写，模型靠它判断何时自动加载；省略时退回正文第一段。列表展示里，description 与 when_to_use 合计会被截到 1536 个字符。营销技能若把整份操作手册塞进 description，截断后可能丢掉唯一触发句，表现为“有文件，从不自动出现”。

disable-model-invocation: true 禁止模型自动加载，只保留你手动输入 /名称。从 v2.1.196 起，它也阻止把该技能当作定时任务提示语来跑。任务型、涉及发布或删改的营销技能常需要这个开关。现象是：你以为“提到发文章就会调用”，实际上它被设计成必须斜杠触发。不要把这种沉默当成安装失败。

user-invocable: false 则相反：对用户隐藏 / 菜单，输入 /名称 也不会跑，只留给模型在后台使用。知识型、不希望人手动点开的说明会这样设。现象是：同事说“技能在”，你在菜单里找不到。打开 SKILL.md 看这两项的实际值，不要先改正文。

布尔值在较新版本接受 yes/no、on/off、1/0；v2.1.218 之前只认 true/false。头信息写了 yes 却完全没生效，把版本和字段取值一起记下来，再对照当前文档，不要同时改内容和开关。

第三层：会话类型读不到你的个人目录

官方说明：Cowork 会话和云会话，包括例行任务，不会读取你机器上的个人技能目录。云会话可以读取克隆仓库里提交的 .claude/skills/。例行任务每次都是新的远程会话，只存在于本机个人目录的技能会报不存在。最小验证：同一技能放进仓库项目目录并提交，或按文档从 claude.ai 同步后再查。不要在远程失败后反复重装本机个人目录。

文档把 ~/.claude/skills/synced/ 留作从 claude.ai 同步下来的技能；该名称在企业、个人、项目位置都保留。非交互运行若设置了同步环境变量，会往这个目录拉技能。本地排错时，先分清你改的是自己写的目录，还是同步目录，避免两份同名互相覆盖。

按成本排列的验证动作

1. 在资源管理器或终端确认 SKILL.md 在 技能目录/名称/ 下，而不是把单文件丢在 .claude/ 根上，也不是保存成 .html。
2. 在当前会话执行 /skills，记下是否出现、来源分组是个人、项目、插件还是 claude.ai 同步。
3. 若是嵌套技能，先让会话读到对应子目录中的文件，再重复上一步。
4. 打开 YAML 头，抄下 disable-model-invocation、user-invocable、description 首句。
5. 确认启动方式：工作区是否在仓库内；外部目录是否用了 --add-dir 而不是仅附加目录权限。
6. 若失败发生在云端或例行任务，检查仓库是否提交了项目技能，不要只查笔记本本地路径。

成功信号：/skills 能指出路径；你用与开关匹配的方式调用（自动或斜杠）时，模型开始按 SKILL.md 正文执行，而不是按聊天里的口头摘要发挥。失败仍在，再查技能正文是否要求联网、写文件或发布——那是权限与批准问题，回到通用 Agent 失败页，不要在本页继续改目录。

营销场景里多出来的两处误报

从 Hub 复制安装说明时，网页不是技能包。站点安装提示写过：必须用 ZIP 里的完整文件。把产品页另存为 HTML 丢进 .claude/skills/，Claude Code 不会把它识别成技能。另一处：触发词写在对话里，但 SKILL.md 的 description 写的是另一套英文任务名。自动加载看的是文件头，不是你在中文聊天里的习惯叫法。改 description 或改用斜杠点名，不要同时改两处。

涉及对外发布、删文、改线上配置的技能，保持手动斜杠加人工批准。调用“成功”只表示技能被加载，不表示可以跳过发布检查点。本页不提供绕过权限的步骤。

预防：每个营销技能固定一个目录名；项目技能进仓库；远程会话只用仓库或文档允许的同步方式；改开关后用 /skills 做一次只读确认。Claude Code 在 Vibe Marketing 里是执行单元的宿主，不是可以凭感觉省略路径的聊天窗口。