先说结论
点名调用能成功，说明 Skill 装好了。它会不会自己运行，要看描述：Agent 先读描述，还可能把它截短。这两种情况出问题的原因不同，要分开测。
Agent 是怎么挑 Skill 的
Agent 先读一份 Skill 清单，里面只有名称和描述，选中之后才加载完整的指令。这份清单来自每个 SKILL.md 开头的 front matter（很多人会搜成 skills.md），而且有篇幅上限：
| Agent | 先读什么 | 空间不够时 |
|---|---|---|
| Claude Code | 名称和描述，设置了 when_to_use 的也一起读；每项最多 1,536 个字符 | 清单约占上下文窗口的 1%；最少用到的描述最先被丢掉 |
| Codex | 名称、描述和文件路径 | 清单约占上下文窗口的 2%；先截短描述 |
| Cursor | 名称和描述 | 文档没有说明 |
装的 Skill 一多，又长又含糊的描述可能还没轮到 Agent 比较，就已经被截掉或丢掉了。所以第一句最要紧。
Skill 描述怎么写才会被选中
照同事找你要这份活时的说法写描述，第一句就讲主要用途。
Agent 拿你的请求去对这些词，所以要用大家真会输入的说法，比如“落地页”“发布页”“路演 PPT”。先说产出什么，再说什么时候用。
能被选中
做什么、什么时候用
- “Build a product launch page with a hero, feature grid, and pricing toggle. Use when asked for a landing or launch page.”
会被淹没
泛泛而谈
- “Helps with websites.”
- 要和所有做网页的 Skill 抢，截短之后几乎什么都没说。
怎么测它会不会触发
按这个顺序测。第一步先排除安装问题，之后哪一步不过，问题就出在描述上。
- 1点名调用。不成功就是安装问题，见故障排查。
- 2新开一个会话，免得刚才的点名还留在上下文里；不提名称，用平常的话提需求。
- 3问 Agent 用了哪个 Skill，再找一条只有这个 Skill 才会遵守的指令，看它有没有照做。
跑错了 Skill 怎么办
一般是两个描述有重叠，或者同一个 Skill 装了两份。
- 直接点名你要的那个，点名永远优先。
- 按输入、受众或产出把重叠的描述收窄，让每个 Skill 各管一件事。
- 同名的装在两处：Claude Code 按 Enterprise、个人、项目的顺序取用；Codex 可能两个都列出来。只留一份。
常见问题
Claude Skill 为什么不触发？
先点名调用试试。点名也不行，说明它没装在 Agent 会去找的位置；只有普通请求不触发，就用你平时真会输入的词重写描述。
Claude 怎么决定用哪个 Skill？
它会读每个 Skill 的名称和描述，再加载和你的请求最匹配的那个。输入 /skill-name 就跳过匹配，直接运行你点名的 Skill。
Skill 描述该怎么写？
写清它产出什么、什么时候用，第一句就讲主要用途。描述可能被截短，所以要用大家真会输入的词，比如“落地页”“路演 PPT”。
文件名是 SKILL.md 还是 skills.md？
是 SKILL.md，每个 Skill 文件夹里一份。Agent 选 Skill 时读的名称和描述，就写在它开头的 front matter 里。
参考来源
这篇对你有帮助吗？