先说结论
- 1按名字调用：
/skill-name或$skill-name。能跑起来，说明安装没问题。 - 2提示找不到？检查文件夹：
SKILL.md必须直接放在<skills folder>/<name>/里。 - 3还是不行？在下面找到你遇到的情况。
30 秒判断问题出在哪
左边找到你看到的现象，右边就是该去看的那一节。
按名字调用失败
Skill 不在 Agent 找的位置。见列表里没有这个 Skill。
点名能跑，平常说话它不接
去查描述或设置。见 Skill 不会自动触发。
跑起来的是另一个 Skill
两个 Skill 的描述撞了。见跑错了 Skill。
开始跑了，又停下
缺了它要用的东西。见中途失败。
跑的还是旧版本
别处还有一份，或者会话没刷新。见还是旧版本。
Claude Code、Codex、Cursor 的列表里找不到 Skill？
/skills 或 Customize → Skills 里没有它，说明 Agent 没加载到。最常见的是文件夹放错了地方，或者多套了一层。
| 可能的原因 | 怎么解决 |
|---|---|
用 Skillry CLI 给 Claude Code 装的，但没加 --agent claude-code | 加上这个参数重装一次。不加的话，CLI 默认装到 ~/.agents/skills/ |
| 解压 ZIP 时多出一层文件夹 | 把里面那层往上挪一级。Claude Code 要求路径正好是 skills/<name>/SKILL.md |
两行 --- 之间的 frontmatter 写错了 | 改过来。Codex 和 Cursor 都要求有 name 和 description，Cursor 还要求 name 和文件夹同名 |
| Agent 还没发现它 | Claude Code：运行 /reload-skills。Codex：在仓库里重启。Cursor：新开对话或重新加载窗口 |
ChatGPT 桌面应用里的 Codex，输入 $ 什么都搜不到 | 这是有人报过的 bug（openai/codex#28505）。先看 /skills，再试试重启，或者在 ~/.codex/skills/ 放一份副本（这个办法我们还没实测） |
每个 Agent 会读的全部目录，见 Skill 存放位置。
Skill 列表里有，却不会自动触发？
Agent 靠读描述来决定要不要用某个 Skill。只有点名才跑，要么是描述和你的说法对不上，要么是某个设置把它拦住了。
- 先用 Skill 页面上的示例提示词试试，它就是照着描述写的。
- 检查
paths：设了它，Skill 只会在匹配的文件上自动运行。 - 装的 Skill 很多？为了全部塞进上下文，Agent 会截短甚至丢掉一部分描述，所以要把主要用途写在最前面。见触发机制。
跑起来的是另一个 Skill？
两个 Skill 的描述管的是同一类活，它们就会抢，Agent 会挑和你的话更接近的那个。一般是给相似的活装了两个 Skill，或者同一个 Skill 装了两份。
| 实际情况 | 怎么解决 |
|---|---|
| 总被一个相似的 Skill 抢走 | 直接点名：Claude Code 和 Cursor 用 /skill-name，Codex 用 $skill-name。点了名，用的一定是这个 Skill。 |
| 你自己写的几个 Skill 管的事重叠 | 按输入、对象或产出把每个描述收窄，一个 Skill 只管一件事。见触发机制。 |
| 同名的 Skill 装了两份 | Claude Code 按 Enterprise、个人、项目的顺序取用；Codex 可能两份都列出来。只留一份。 |
| 某个 Skill 总在你没要它的时候跑起来 | 把它的描述写得更具体，讲清楚什么时候该用，免得和无关的请求对上；想用哪个 Skill 就直接点名。见触发机制。 |
开始跑了，中途却失败？
基本都是缺依赖：Node.js 版本不对，或者没装 Python、FFmpeg，没配 FAL key。Skill 页面写了它需要什么，先对照着查一遍：
更新了，跑的还是旧版本？
Skill 已经更新，Agent 却还按老样子做，原因通常是下面几种之一：
- 只换了
SKILL.md。用--force重装，或者把整个文件夹换掉。 - 别的目录里还有一份同名的。把它删掉。
- Claude Code 里，已经跑过的 Skill 在这次对话里会一直保持原样。新开一个对话，改动才会生效。
怎么备份、怎么回滚，见管理与更新。
本地能用，到云端就不行？
云端会话跑在另一台机器上，只存在你电脑里的 Skill 不会自动跟过去，得按下面的办法设置：
| Agent | 怎么解决 |
|---|---|
| Claude Code | 云端会话：把它提交到 .claude/skills/，或者在 claude.ai 上打开。Cowork：在 claude.ai 上打开。 |
| Codex | 单独的 Skill 到不了 ChatGPT 网页版和手机端，要打包进插件发布。 |
| Cursor | 放在 ~/.cursor/skills/，再到 Settings → Agents → Context and Tools 里打开 Sync Skills for Cloud Agents。 |
Skillry CLI 报错怎么办？
找到 Skillry CLI 打出来的那句提示，照右边一栏处理就行。
| 你看到的提示 | 怎么处理 |
|---|---|
| “Not logged in.” 或 “Session expired.” | 运行 npx --yes skillry-cli@latest login |
| “…already exists. Re-run with --force to replace it safely.” | 加上 --force，旧的那份会自动备份 |
| “This Skill requires a paid plan.” | 看一下这个 Skill 的价格，或者你的套餐 |
| “--agent and --target cannot be used together.” | 两个参数只留一个 |
| “Secure session storage is currently supported on macOS and Windows only.” | Linux 上请改用安装提示词，或者下载 ZIP |
常见问题
为什么我的 Claude Code Skill 加载不出来？
多半是装到了 ~/.agents/skills/，而不是 ~/.claude/skills/，或者多套了一层文件夹。把路径改对；如果文件夹是新建的，再运行一次 /reload-skills。
为什么 Skill 找我要 API key？
它要调用付费服务，Skill 页面的“外部成本”里写着是哪家。按那家服务文档说的方式配置 key，千万别贴进对话里。
怎么确认装好了？
能在 /skills 里看到它（Cursor 是 Customize → Skills），按名字调用时也能正常跑。
参考来源
这篇对你有帮助吗？