【Bug已解决】Claude Code 报错 No skills found despite installation 解决方案

1. 问题描述

按照文档在 ~/.claude/skills/ 目录下创建了自定义 Skill，或者通过插件市场安装了某个 Skill，执行 /skills 命令查看时，却提示完全没有找到任何 Skill：

/skills
No skills found.

1.1 具体现象

1. 确认目录下确实存在对应的 Skill 文件夹和描述文件
2. 文件权限看起来正常，没有明显的读取障碍
3. 重启 Claude Code 后问题依然存在
4. 有些人发现是路径拼写、目录层级放错了导致的

这个问题的常见根因和之前讨论过的"配置文件未生效"类问题类似——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
/skills

Skill 的扫描/索引可能只在启动阶段进行一次，中途新增的 Skill 文件需要重启会话才能被重新扫描到。

4. 各方案对比总结

方案	适用场景	推荐指数
核对目录结构	最常见的排查方向	⭐⭐⭐⭐⭐
校验 YAML frontmatter	手写 Skill 描述文件的场景	⭐⭐⭐⭐⭐
确认用户级/项目级路径	容易混淆的两种作用域	⭐⭐⭐⭐
确认插件安装完整性	通过插件市场安装的场景	⭐⭐⭐⭐
重启会话重新扫描	新增 Skill 文件后未生效	⭐⭐⭐⭐

5. 常见问题 FAQ

5.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 的扫描要求，而不是功能本身存在缺陷。核心处理思路：

1. 严格核对目录结构和文件命名规范，这是最常见的排查方向；
2. 校验 YAML frontmatter 的语法正确性，格式错误会导致整个 Skill 被静默跳过；
3. 区分清楚用户级和项目级路径的使用场景，不要混淆两种不同的作用域。

最佳实践建议：创建自定义 Skill 时，优先参考官方文档提供的标准模板结构，而不是凭记忆手写，能大幅降低这类因格式不规范导致的加载失败问题。