Claude Code Skill 不显示或不自动触发，先不要把所有问题都归因于“缓存”或“需要重启”。最有效的分流方法是：先看它是否出现在 /skills，再用 /skill-name 显式调用。完全不显示通常是目录、作用域、可见性或 frontmatter 问题；能显式调用但不会自动触发，才重点检查 description、when_to_use 和调用控制。本文依据 2026 年 8 月 28 日的 Claude Code 官方文档整理，未在本机当前版本完成端到端实测。
版本边界：截至核验时，Claude Code 官方最新 Release 为 v2.1.250。部分诊断能力有明确版本要求，例如 claude plugin validate 需要 v2.1.233 或更高版本。先运行 claude --version，旧版本遇到与文档不一致的行为时，应先查 Release 与升级说明，而不是直接删除配置。
先分四种症状
| 症状 | 优先判断 | 第一步 |
|---|---|---|
/skills 中完全没有 |
未发现或被隐藏 | 核对目录、文件名、作用域和 skillOverrides |
能看到，/name 也能运行，但不会自动触发 |
自动匹配失败或被禁止 | 检查 disable-model-invocation、description 与 when_to_use |
修改了 SKILL.md，行为还是旧的 |
监听未建立或实际加载了另一份 | 判断是否首次创建顶层目录，再排查同名优先级 |
| 偶尔触发，Skill 多时更明显 | 描述被压缩或描述互相重叠 | 看 /context 与 /doctor |
这一步的意义是缩小故障层级。显式调用成功，说明 Claude Code 至少已经发现了某个同名 Skill；此时反复移动目录通常没有帮助。显式调用也失败，则不要先改写正文，应先确认实际加载源。
建立最小测试
先用一个没有脚本、网络请求和额外工具权限的 Skill 验证发现链路。个人级路径适用于所有项目，项目级路径只适用于当前项目：
| 作用域 | 目录 | 适用范围 |
|---|---|---|
| 个人 | ~/.claude/skills/warpnav-skill-check/SKILL.md |
所有项目 |
| 项目 | .claude/skills/warpnav-skill-check/SKILL.md |
当前项目 |
| 插件 | <plugin>/skills/warpnav-skill-check/SKILL.md |
启用该插件的环境 |
SKILL.md 可先只放以下内容：
---
name: warpnav-skill-check
description: Returns a fixed diagnostic sentence. Use when the user asks to run the WarpNav skill check or verify whether a Claude Code skill can trigger.
---
Reply exactly: WarpNav skill discovery works.
- 打开
/skills，确认warpnav-skill-check出现。 - 输入
/warpnav-skill-check。预期只返回固定句子。 - 另开一轮对话，输入“请运行 WarpNav skill check”。预期自动匹配该 Skill。
如果第二步失败，问题在发现、可见性或解析层；如果第二步成功而第三步失败，问题在自动调用层。测试结束后可以把测试目录改名并移出 Skills 路径，或在 /skills 中关闭它。先保留原文件副本，不需要执行递归删除命令。
完全不显示
检查目录形状
Claude Code 要求每个 Skill 使用一个目录，并以大写文件名 SKILL.md 作为入口。把文件写成 .claude/skills/name.md 不会得到同样的发现结果；正确形状是 .claude/skills/name/SKILL.md。项目目录与个人目录也不要混用：前者跟随当前项目，后者位于用户目录并对所有项目生效。
先用 /context 查看 Skills 描述是否进入上下文，再用 /skills 查看来源。两处都没有时，继续查路径；已经存在时，不要再把“看不到”与“不自动调用”混为一件事。
检查启动位置
项目 Skill 会从 Claude Code 启动目录及其父目录一直发现到仓库根目录。嵌套在启动目录下方的 .claude/skills/ 不一定在启动时全部加载：当 Claude 首次读取或编辑对应子目录里的文件后，嵌套 Skill 才会按需出现。对于仓库外目录，--add-dir 或会话中的 /add-dir 可以扩展文件访问；Skills 是附加目录中会被发现的少数配置类型之一。
预期结果是：根级项目 Skill 直接显示；嵌套 Skill 在访问其所属子目录后显示为带目录限定的名称。若它仍未出现，确认 Claude Code 实际启动目录、仓库根和附加目录是不是你以为的那一组。
检查可见性
skillOverrides 可以在不编辑第三方 SKILL.md 的情况下改变可见性。官方现行状态包括 on、name-only、user-invocable-only 和 off；/skills 菜单会把选择写入项目的 .claude/settings.local.json。其中 off 会同时从模型列表和命令菜单隐藏，user-invocable-only 仍可由用户调用，但不会向模型暴露描述。
该设置不适用于插件 Skill，插件应通过 /plugin 管理。不要为了恢复一个插件 Skill，误改普通项目 Skill 的设置文件。
校验 frontmatter
YAML frontmatter 解析失败时，官方文档说明 Claude Code 可能仍加载正文，但元数据为空：显式 /name 可能工作，自动触发却缺少 description。在 v2.1.233 及以上可以运行：
claude plugin validate .claude/skills
个人 Skill 则把路径换成 ~/.claude/skills。预期结果是校验器没有报告 frontmatter 解析错误；若有错误，先修复 YAML，再用显式调用复查。低于该版本时不要照抄命令后把“不支持”误判为 Skill 损坏，可用 claude --debug 查看解析日志。
显示但不触发
先看调用控制
disable-model-invocation: true 的含义是只允许按需显式调用，Claude 不会自动加载。/skills 中的 user-only 标记就是直接线索。相反，user-invocable: false 是隐藏用户菜单和显式命令，让 Claude 在相关时自动使用；这两个字段控制的方向不同。
如果 Skill 会部署、提交、发消息或产生其他副作用，保留手动调用通常更安全。只有它本来就应该按任务自动提供知识或低风险流程时，才移除 disable-model-invocation。
重写 description
Claude 在 Skill 运行前主要根据名称和描述判断相关性。只写“帮助开发”或“处理项目任务”无法区分触发场景。更有效的描述应在开头说明能力和使用条件，并包含用户自然会说出的词：
description: Reviews a WordPress REST payload before upload. Use when the user asks to validate a WarpNav draft, inspect post fields, or check a WordPress payload.
when_to_use: Trigger for requests such as “检查文章草稿字段” or “验证 WordPress payload”.
description 与 when_to_use 合计会在 Skill 列表中截断，因此不是越长越好。把最关键的任务放在前面，避免和多个 Skill 使用相同的宽泛描述。显式调用成功但自然语言不触发时，先让测试请求更接近描述；若这样能触发，再逐步把描述扩展到真实表达，而不是堆一串同义关键词。
检查描述预算
Skill 很多时，Claude Code 会限制名称与描述列表占用的上下文。超出预算后，低频 Skill 可能只剩名称，模型仍知道它存在，却看不到“什么时候用”。/doctor 可以估算列表成本和被截断数量；/context 的 Skills 行显示模型实际收到的列表大小。
修复不一定是继续扩写 description。更合理的顺序是删除重复表述、关闭当前项目不需要的 Skill、把只手动运行的流程设为 user-only，然后再测试自然语言触发。
修改没有生效
官方文档区分了三种刷新情况：
- 修改现有
SKILL.md：个人、项目和--add-dir中已被监听的 Skill 通常会在当前会话热更新。 - 首次创建顶层 skills 目录：如果会话启动时该目录不存在，新建后需要重启 Claude Code，让监听器建立。
- 修改插件其他资源：插件里的 hooks、MCP、agents 和 output styles 需要
/reload-plugins；不要把这条规则机械套到普通项目 Skill。
如果重启后仍像旧版本，排查同名副本。非插件 Skill 的优先级是 enterprise 高于 personal、personal 高于 project。也就是说，个人目录已有 deploy 时，修改项目里的同名 deploy 可能看不出效果。插件 Skill 使用 plugin-name:skill-name 命名空间，通常不会和普通 Skill 直接冲突；旧的 .claude/commands/name.md 与 Skill 同名时，则由 Skill 优先。
诊断矩阵
| 症状 | 检查 | 预期结果 | 修复与回滚 |
|---|---|---|---|
/skills 没有条目 |
确认 <name>/SKILL.md、作用域与启动目录 |
能看到名称和来源 | 移到正确目录；保留原目录副本以便恢复 |
| 刚创建顶层目录后不显示 | 确认目录在会话启动时是否存在 | 重启后被监听 | 重启 Claude Code；无效则恢复目录变更并继续查设置 |
| 显式调用可用，自动调用失败 | 看 user-only、disable-model-invocation 和描述 |
低风险 Skill 的描述能匹配测试请求 | 只在确需自动触发时移除限制；否则保留手动调用 |
| 描述已经很长仍不触发 | /doctor、/context |
模型能看到关键描述 | 精简、去重或关闭无关 Skill；可恢复原设置 |
| 改项目 Skill 却仍运行旧内容 | 查 enterprise、personal、project 同名项 | 明确实际胜出的来源 | 改正确副本或换唯一名称；不要直接删除高优先级副本 |
| 嵌套 Skill 启动时没有 | 先让 Claude 读取该子目录文件 | 出现目录限定名称 | 调整启动位置或用明确名称调用 |
| frontmatter 看似存在但不匹配 | claude plugin validate 或 --debug |
没有 YAML 解析错误 | 修复 YAML；修改前保留原文件 |
| 插件脚本已改但行为不变 | 判断改的是 SKILL.md 还是插件资源 |
插件资源 reload 后更新 | 运行 /reload-plugins；失败则恢复插件改动 |
如果排查过程中发现 Skill 来自第三方仓库，且脚本、依赖、联网或凭据访问范围尚未确认，应先回到第三方 Agent Skill 安装前安全审计清单判断是否值得继续加载；来源行为没有审清时，不要把“让它成功触发”当作当前目标。
何时再报 Bug
只有在最小测试 Skill 的路径、可见性、解析、显式调用和描述都符合官方规则，并且当前版本仍能稳定复现问题时，才更像产品缺陷。提交 Issue 前记录 Claude Code 版本、操作系统、启动目录、Skill 来源、最小 SKILL.md、/skills 与 /context 结果，并移除用户名、仓库私密路径、密钥和业务内容。
如果问题只在真实配置出现，可以按官方配置排错文档使用干净配置目录逐项加入设置，但 Windows 和 Linux 的干净配置可能要求重新登录，受管组织策略仍会继续生效。不要把真实凭据复制进临时目录，也不要在没有备份时批量移动整个 ~/.claude。
想先确认 Claude Code 的产品入口、终端与 IDE 使用边界，可查看 WarpNav 的Claude Code 详情页；如果你还在判断该不该安装第三方 Skill，可先看从工作流出发判断 Skill 的方法。具体 Skill 项目页可以作为安装场景，但它们不能替代本页的发现与触发诊断。
主要官方资料（核验于 2026 年 8 月 28 日）：Claude Code Skills 文档 https://code.claude.com/docs/en/skills；配置排错 https://code.claude.com/docs/en/debug-your-config；Settings https://code.claude.com/docs/en/settings；Permissions https://code.claude.com/docs/en/permissions；官方 Releases https://github.com/anthropics/claude-code/releases/latest。版本、字段和菜单行为可能变化，遇到与本文不同的现象时应以当前官方文档为准。
© 版权声明
本站部分内容源于网络收集，文章等版权归原作者所有，若需删稿请联系管理员邮箱：satomini@warpnav.com
相关文章
暂无评论...
