【Bug已解决】Claude Code 报错 No skills found despite installation 解决方案1. 问题描述按照文档在~/.claude/skills/目录下创建了自定义 Skill或者通过插件市场安装了某个 Skill执行/skills命令查看时却提示完全没有找到任何 Skill/skills No skills found.1.1 具体现象确认目录下确实存在对应的 Skill 文件夹和描述文件文件权限看起来正常没有明显的读取障碍重启 Claude Code 后问题依然存在有些人发现是路径拼写、目录层级放错了导致的这个问题的常见根因和之前讨论过的配置文件未生效类问题类似——Skill 定义确实存在于磁盘上但没有被放置在 Claude Code 实际扫描识别的路径下或者其内部的描述文件frontmatter格式不符合要求。2. 原因分析Claude Code 的 Skills 机制要求每个 Skill 按照约定的目录结构和文件格式组织~/.claude/skills/ └── my-skill/ └── SKILL.md ← 包含 YAML frontmatter 描述信息常见的检测不到原因原因分类具体表现目录层级放置错误Skill 文件直接放在 skills 目录下而不是每个 Skill 一个独立子目录入口文件命名不规范文件名不是约定的SKILL.md或者大小写不匹配YAML frontmatter 格式错误描述信息的 YAML 语法有误导致整个 Skill 被判定为无效而跳过项目级与用户级路径混淆期望的是项目级 Skill却放到了用户级目录或反过来3. 解决方案方案一核对目录结构是否严格符合约定ls -la ~/.claude/skills/ # 确认每个 Skill 都是独立子目录子目录内包含 SKILL.md 文件 cat ~/.claude/skills/my-skill/SKILL.md # 确认文件名大小写完全正确方案二校验 SKILL.md 的 YAML frontmatter 格式--- name: my-skill description: 这个 Skill 用于处理特定任务说明触发场景 --- 具体的 Skill 指令内容...frontmatter 部分必须是合法的 YAML 语法用---包裹在文件最开头缺少任何一个分隔符或者字段格式错误都可能导致该 Skill 被跳过。方案三确认项目级和用户级路径是否用对了# 用户级全局生效 ~/.claude/skills/ # 项目级仅当前项目生效 .claude/skills/如果期望某个 Skill 只在当前项目里可用应该放在项目级路径如果期望全局可用则应放在用户级路径两者不能混用。方案四通过插件市场安装的 Skill确认安装是否真正完成# 检查插件安装状态 /plugin list # 如果状态异常尝试重新安装 /plugin install plugin-name部分情况下插件市场的安装流程可能因网络问题中断表面上显示已安装但实际文件未完整落地需要重新触发一次完整安装。方案五完全重启 Claude Code 并清理可能的缓存状态# 完全退出所有 Claude Code 相关进程后重新启动 claude /skillsSkill 的扫描/索引可能只在启动阶段进行一次中途新增的 Skill 文件需要重启会话才能被重新扫描到。4. 各方案对比总结方案适用场景推荐指数核对目录结构最常见的排查方向⭐⭐⭐⭐⭐校验 YAML frontmatter手写 Skill 描述文件的场景⭐⭐⭐⭐⭐确认用户级/项目级路径容易混淆的两种作用域⭐⭐⭐⭐确认插件安装完整性通过插件市场安装的场景⭐⭐⭐⭐重启会话重新扫描新增 Skill 文件后未生效⭐⭐⭐⭐5. 常见问题 FAQ5.1 通过 CC-Switch 等第三方工具安装的 Skill为什么反而更容易生效这类第三方工具通常会自动处理好目录结构和格式规范减少了手动配置出错的概率而通过/plugin install官方渠道安装时如果底层配置文件比如项目的 settings.json存在问题可能导致该渠道安装的 Skill 无法正常加载两者的生效链路存在细节差异。5.2 Skill 显示在列表里但对话中从来不会被自动触发是同一个问题吗不是这属于另一类问题——Skill 已经被正确识别加载但触发机制model-invoked即模型自主判断何时调用没有被激活通常需要检查 Skill 描述文本是否足够清晰明确让模型能准确判断适用场景。5.3 团队共享 Skill 时应该放在用户级还是项目级如果是团队协作共用的项目专属 Skill建议放在项目级路径并纳入版本管理这样团队所有成员克隆项目后都能自动获得一致的 Skill 配置个人习惯性使用的通用 Skill 则更适合放在用户级路径。5.4 排查清单速查表□ 1. 确认目录结构严格符合每个 Skill 一个独立子目录的约定 □ 2. 确认入口文件名为 SKILL.md大小写完全正确 □ 3. 校验 YAML frontmatter 语法是否合法 □ 4. 确认用户级/项目级路径没有混淆放置 □ 5. 插件市场安装的 Skill 确认安装流程真正完整完成 □ 6. 完全重启 Claude Code 会话重新触发 Skill 扫描6. 总结No skills found报错的本质是Skill 文件的目录结构、命名规范或描述格式不符合 Claude Code 的扫描要求而不是功能本身存在缺陷。核心处理思路严格核对目录结构和文件命名规范这是最常见的排查方向校验 YAML frontmatter 的语法正确性格式错误会导致整个 Skill 被静默跳过区分清楚用户级和项目级路径的使用场景不要混淆两种不同的作用域。最佳实践建议创建自定义 Skill 时优先参考官方文档提供的标准模板结构而不是凭记忆手写能大幅降低这类因格式不规范导致的加载失败问题。 【Bug已解决】Claude Code 报错 No skills found despite installation 解决方案
【Bug已解决】Claude Code 报错 No skills found despite installation 解决方案1. 问题描述按照文档在~/.claude/skills/目录下创建了自定义 Skill或者通过插件市场安装了某个 Skill执行/skills命令查看时却提示完全没有找到任何 Skill/skills No skills found.1.1 具体现象确认目录下确实存在对应的 Skill 文件夹和描述文件文件权限看起来正常没有明显的读取障碍重启 Claude Code 后问题依然存在有些人发现是路径拼写、目录层级放错了导致的这个问题的常见根因和之前讨论过的配置文件未生效类问题类似——Skill 定义确实存在于磁盘上但没有被放置在 Claude Code 实际扫描识别的路径下或者其内部的描述文件frontmatter格式不符合要求。2. 原因分析Claude Code 的 Skills 机制要求每个 Skill 按照约定的目录结构和文件格式组织~/.claude/skills/ └── my-skill/ └── SKILL.md ← 包含 YAML frontmatter 描述信息常见的检测不到原因原因分类具体表现目录层级放置错误Skill 文件直接放在 skills 目录下而不是每个 Skill 一个独立子目录入口文件命名不规范文件名不是约定的SKILL.md或者大小写不匹配YAML frontmatter 格式错误描述信息的 YAML 语法有误导致整个 Skill 被判定为无效而跳过项目级与用户级路径混淆期望的是项目级 Skill却放到了用户级目录或反过来3. 解决方案方案一核对目录结构是否严格符合约定ls -la ~/.claude/skills/ # 确认每个 Skill 都是独立子目录子目录内包含 SKILL.md 文件 cat ~/.claude/skills/my-skill/SKILL.md # 确认文件名大小写完全正确方案二校验 SKILL.md 的 YAML frontmatter 格式--- name: my-skill description: 这个 Skill 用于处理特定任务说明触发场景 --- 具体的 Skill 指令内容...frontmatter 部分必须是合法的 YAML 语法用---包裹在文件最开头缺少任何一个分隔符或者字段格式错误都可能导致该 Skill 被跳过。方案三确认项目级和用户级路径是否用对了# 用户级全局生效 ~/.claude/skills/ # 项目级仅当前项目生效 .claude/skills/如果期望某个 Skill 只在当前项目里可用应该放在项目级路径如果期望全局可用则应放在用户级路径两者不能混用。方案四通过插件市场安装的 Skill确认安装是否真正完成# 检查插件安装状态 /plugin list # 如果状态异常尝试重新安装 /plugin install plugin-name部分情况下插件市场的安装流程可能因网络问题中断表面上显示已安装但实际文件未完整落地需要重新触发一次完整安装。方案五完全重启 Claude Code 并清理可能的缓存状态# 完全退出所有 Claude Code 相关进程后重新启动 claude /skillsSkill 的扫描/索引可能只在启动阶段进行一次中途新增的 Skill 文件需要重启会话才能被重新扫描到。4. 各方案对比总结方案适用场景推荐指数核对目录结构最常见的排查方向⭐⭐⭐⭐⭐校验 YAML frontmatter手写 Skill 描述文件的场景⭐⭐⭐⭐⭐确认用户级/项目级路径容易混淆的两种作用域⭐⭐⭐⭐确认插件安装完整性通过插件市场安装的场景⭐⭐⭐⭐重启会话重新扫描新增 Skill 文件后未生效⭐⭐⭐⭐5. 常见问题 FAQ5.1 通过 CC-Switch 等第三方工具安装的 Skill为什么反而更容易生效这类第三方工具通常会自动处理好目录结构和格式规范减少了手动配置出错的概率而通过/plugin install官方渠道安装时如果底层配置文件比如项目的 settings.json存在问题可能导致该渠道安装的 Skill 无法正常加载两者的生效链路存在细节差异。5.2 Skill 显示在列表里但对话中从来不会被自动触发是同一个问题吗不是这属于另一类问题——Skill 已经被正确识别加载但触发机制model-invoked即模型自主判断何时调用没有被激活通常需要检查 Skill 描述文本是否足够清晰明确让模型能准确判断适用场景。5.3 团队共享 Skill 时应该放在用户级还是项目级如果是团队协作共用的项目专属 Skill建议放在项目级路径并纳入版本管理这样团队所有成员克隆项目后都能自动获得一致的 Skill 配置个人习惯性使用的通用 Skill 则更适合放在用户级路径。5.4 排查清单速查表□ 1. 确认目录结构严格符合每个 Skill 一个独立子目录的约定 □ 2. 确认入口文件名为 SKILL.md大小写完全正确 □ 3. 校验 YAML frontmatter 语法是否合法 □ 4. 确认用户级/项目级路径没有混淆放置 □ 5. 插件市场安装的 Skill 确认安装流程真正完整完成 □ 6. 完全重启 Claude Code 会话重新触发 Skill 扫描6. 总结No skills found报错的本质是Skill 文件的目录结构、命名规范或描述格式不符合 Claude Code 的扫描要求而不是功能本身存在缺陷。核心处理思路严格核对目录结构和文件命名规范这是最常见的排查方向校验 YAML frontmatter 的语法正确性格式错误会导致整个 Skill 被静默跳过区分清楚用户级和项目级路径的使用场景不要混淆两种不同的作用域。最佳实践建议创建自定义 Skill 时优先参考官方文档提供的标准模板结构而不是凭记忆手写能大幅降低这类因格式不规范导致的加载失败问题。