Skill 文件写好了,却在 Claude Code 里找不到,或任务来了也没有按流程执行?
最快解法是:Claude Code 创建自定义 Skills 时,先把 SKILL.md 放进支持的 Skills 目录,再检查元数据,并用真实任务验证识别和调用。目录、字段及加载行为可能随版本调整,操作前先核对Claude Code Skills 官方文档。
适合正在使用 Claude Code、想把重复编程任务整理成可复用流程的开发者。
也适合需要在项目内共享流程,或要验证 AI Agent 工作流是否能稳定调用 Skills 的团队。
如果只是临时给 Claude 一条指令,直接写在对话里即可,不必急着创建 Skill。
Claude Code 创建自定义 Skills 的完成标准
>创建完成不等于文件“保存成功”。至少要通过三项检查:SKILL.md 位于支持的目录结构中;Claude Code 能识别该 Skill;一个真实任务能按文件里的要求执行。显式调用能验证命令是否可用,自动匹配则需要另外测试。
⚠️ Skill 出现在命令列表中,只能说明它可以被显式调用,不代表 Claude 一定会在适合的对话中自动选择它。自动调用取决于任务与 Skill 描述是否匹配。
还要区分 Skill 和项目说明:Skill 用来封装按需执行的步骤;CLAUDE.md 更适合提供持续适用的项目背景和规范。Claude Code 会在 Skill 被使用时加载其正文,因此完整流程不必全部放进每次会话都要读取的说明文件。可参阅官方关于项目记忆与说明文件的文档。
按使用范围完成目录配置
>Claude Code 的项目级 Skills 目录是 .claude/skills/,个人级目录是 ~/.claude/skills/。项目内的 Skill 可随仓库共享;个人目录中的 Skill 则适合在本机多个项目中复用。对应路径如下:
项目根目录/
└── .claude/
└── skills/
└── review-change/
└── SKILL.md
~/.claude/skills/review-change/SKILL.md
选择时按用途判断:
- 如果同一仓库的协作者都要复用这个流程,放在项目的
.claude/skills/,并纳入版本管理。 - 如果流程是个人习惯,希望在本机多个项目中使用,放在
~/.claude/skills/。 - 如果在单体仓库的子目录工作,子目录也可能有自己的
.claude/skills/;从仓库根目录启动和从子目录启动,发现范围可能不同。 - 如果使用云端会话,不要假设本机个人目录会自动同步;确认该会话实际能访问的 Skills 来源。
上述目录与加载范围以官方 Skills 路径说明为准。不要把 Skill 文件误放进 .claude/settings.json:设置文件用于权限和行为配置,不是 Skills 的存放目录;需要了解设置文件作用范围时,可查看官方设置说明。
决策条件:
- 若流程只服务于一个仓库,选择项目级;若希望自己在多个本机项目使用,选择个人级。
- 若从子目录启动后找不到项目级 Skill,先从仓库根目录启动进行对照,再检查对应子目录是否有自己的 Skill。
- 若只是要封装一个重复流程,先创建独立 Skill;只有需要把多个扩展组件一起分发时,再研究官方插件结构。
编写 SKILL.md 时写清任务、条件和边界
>新建 review-change/SKILL.md,在文件开头写 YAML frontmatter,之后用 Markdown 编写操作说明。下面是演示示例,实际效果仍要在目标项目和当前 Claude Code 会话中测试:
---
name: review-change
description: 检查当前代码改动中的明显错误、遗漏测试和风险。用户要求审查改动、检查差异或准备提交前复核时使用。
---
# 代码改动检查
按以下顺序执行:
1. 先确认本次改动范围,并阅读相关文件。
2. 仅报告能指向具体文件或代码位置的问题;不确定时标注为待确认。
3. 检查相关测试是否覆盖改动;不要声称运行过未实际执行的测试。
4. 先列问题和依据,再给出建议;未经请求不要直接修改代码。
5. 如果没有发现问题,说明检查范围及尚未验证的事项。
示例将任务、适用条件、执行步骤和边界分别写清楚。description 应说明 Skill 做什么、何时使用;正文则说明触发后具体怎么做。只写“帮助审查代码”太宽泛,Claude 难以判断哪些请求适合自动匹配。
Claude Code 当前文档说明,frontmatter 的 YAML 区块必须位于文件第一行的 --- 之后;字段名必须准确,无法识别的字段会被忽略。当前文档将 description 列为推荐字段,并说明 Skill 名称可来自目录名,也可由 frontmatter 的 name 指定。字段和格式以官方 frontmatter 参考为准。
若还要兼容 Agent Skills 开放规范,需留意两套说明的差异:该规范要求 name 和 description,并要求名称为 1–64 个字符,仅使用小写字母、数字和连字符;Claude Code 当前文档则说明 name 可以省略。为便于移植,示例保留 name 并与目录名一致。开放规范还建议主文件少于 500 行,较长资料可以拆到 references/ 等文件。详情见Agent Skills 格式规范及官方 Skill 创建示例。
💡 Claude Code 文档指出,
description与when_to_use会合并用于 Skill 列表展示,合计超过 1,536 个字符时可能被截断。把核心用途和触发条件放在描述前面,避免开头先写背景。
保存后按步骤验证识别与调用
>从路径到输出逐项检查,能更快区分“没加载”和“加载了但没按预期执行”:
- 核对目录层级。 项目级文件应位于
.claude/skills/技能目录名/SKILL.md;个人级文件应位于~/.claude/skills/技能目录名/SKILL.md。检查文件名大小写和目录是否多套或少套一层。 - 检查 frontmatter。 确认文件第一行是
---,YAML 格式有效,字段名与官方文档一致。不要把执行步骤写进元数据区。 - 检查是否加载。 如果会话启动后才新建顶层 Skills 目录,按当前文档运行
/reload-skills;若只是修改已加载目录里的SKILL.md,Claude Code 通常会在会话中检测到变化。具体行为以官方会话内编辑说明为准。 - 显式调用。 在消息开头输入
/review-change,并附上任务,例如:“检查当前未提交改动,只列出有代码位置依据的问题,不要修改文件。”斜杠命令只在消息开头识别,后续文本作为参数;可参阅官方命令参考。 - 验证自动匹配。 新开一条消息,不输入斜杠命令,直接描述与
description一致的任务。检查输出是否遵循步骤、给出具体依据,并遵守“不修改代码”的边界。 - 记录差异并复测。 若命令找不到,先排查路径和会话范围;命令可用但自动匹配不稳定,优先改写描述;已经触发却偏离流程,则补充明确步骤、限制和交付格式。
可给这轮验收设一个简单评分:路径与命令可见、显式调用符合要求、自动匹配符合要求,各计 1 分。总分 3 分表示这轮测试均通过;若显式调用成功但自动匹配失败,说明 Skill 至少可调用,下一步应针对描述和测试任务迭代,而不是直接重建目录。
按症状排查未识别或调用异常
>- 输入斜杠命令时找不到 Skill: 检查文件是否位于技能目录内,而不是直接放在
.claude/skills/下;确认当前会话实际使用的是项目级还是个人级路径。 - 项目级 Skill 在子目录工作时不出现: 检查 Skill 是放在仓库根目录还是更深层目录。当前目录、父目录以及会话是否已访问子目录,都可能影响它何时被发现。
- 命令可用,但自动匹配不稳定: 将描述改成明确的任务和适用场景,例如“审查当前代码改动、核对相关测试时使用”,不要只写笼统的“代码助手”。
- Skill 已触发,但步骤执行不完整: 将长句拆成可检查的动作,写明先后顺序、禁止事项和输出格式;涉及修改文件时,注明是否需要先征求确认。
- 改完文件后行为没变化: 确认当前会话已重新加载新建的顶层目录,或开新会话复测;也要确认修改的是正在使用的那份 Skill,而非同名的另一份。
闭环操作是:一次只改一处路径、元数据或正文要求,重新加载,再用同一条任务复测,并比较输出是否变化。若要把 Skills 测试扩展为团队共用开发流程,可阅读 Zilmac 的远程 Mac 开发环境说明,但环境配置与 Skill 识别是不同问题,应分别验证。
常见疑问
>SKILL.md 应该写哪些内容?
写清任务用途、适用条件、执行步骤、禁止事项和交付格式。若 Skill 依赖特定脚本或参考资料,可把它们放在同一目录,并在正文注明何时读取或运行。示例中明确要求不得声称运行了未实际执行的测试,就是为了让输出边界可以检查,而非只给 Claude 一个宽泛目标。
个人项目和团队项目的目录如何选择?
只希望本人在本机多个项目中复用,使用 ~/.claude/skills/技能名/SKILL.md;希望同一仓库的协作者共享,使用仓库内 .claude/skills/技能名/SKILL.md 并纳入版本管理。不同会话环境对本机文件的访问范围可能不同,尤其不要假设本地个人目录会自动出现在云端会话。
显式调用成功,是否代表自动调用也能成功?
不代表。显式调用验证命令是否可用;自动调用还依赖任务描述与 description 的相关性。先用清楚匹配用途的请求测试自动选择,再检查结果是否符合 Skill 正文的约束;若仅自动匹配失败,优先收窄描述和触发条件。
自定义 Skill 没触发时,应该从哪里开始排查?
先尝试斜杠命令。如果命令不存在,检查路径、目录层级、frontmatter 和会话加载状态;如果命令可用但自动调用不稳定,修改 description,并用相同测试任务复测。若调用后执行偏离预期,则补充更具体的步骤和边界。每次改动后都用同一任务验证,避免同时改多个因素而无法定位原因。
创建完成后,拿一个团队反复遇到的真实任务,分别测试显式调用和自动匹配,比只看文件是否存在更有判断力。若本机环境足够稳定,继续本地运行即可;若还受设备占用或协作环境不一致影响,再比较远程环境的交付内容与访问方式。可先查看 Zilmac 的 Mac 租用信息,判断是否适合现有工作流;创建 Skill 本身并不要求额外租用设备。
常见问答
SKILL.md 里应该写哪些内容,才能让 Claude Code 按流程做事?
先在 YAML 元数据中写清 Skill 的名称和适用任务,再在正文列出前置条件、执行顺序、不可越过的边界和交付格式。示例应包含输入与预期输出;如果依赖脚本或参考资料,可以放在同一 Skill 目录下,并在正文说明何时读取或运行。
个人项目和团队项目的 Claude Code Skills 应该放在哪里?
只希望本人在这台机器的各项目中使用,就放在用户目录下的 `~/.claude/skills/技能名/SKILL.md`;希望同一仓库的协作者共享,就放在仓库的 `.claude/skills/技能名/SKILL.md` 并纳入版本管理。云端会话等不同运行环境可能有不同加载范围,不能假设本地个人目录会自动同步。
怎么确认 Claude Code 识别了 Skill,也真的调用了它?
先在会话中输入 `/` 并查找目录名对应的命令;再用 `/技能名` 显式调用,观察输出是否遵循 SKILL.md 的步骤和格式。自动调用则用描述中明确提到的适用任务发起新请求,并通过输出行为验证;仅看到 Skill 出现在命令列表,不等于自动匹配已经通过测试。
自定义 Skill 没触发,应该从哪里开始排查?
先确认当前工作目录能覆盖 Skill 所在位置,再检查目录名、`SKILL.md` 大小写和 YAML 分隔线;接着核对描述是否写明具体用途及触发场景。若显式调用可用而自动调用不稳定,优先改写描述并用清晰测试任务复测;若命令也找不到,再检查加载范围、会话环境和当前文档中的限制。
为你的开发流程准备一台专属云 Mac
通过 Zilmac 租用 Apple M4 裸金属 Mac,完整 macOS 环境适合持续开发与自动化任务。
支持 SSH 与 VNC 远程连接,无论在本地还是异地,都能接入自己的 Mac 环境。 — 立即了解套餐方案