Zilmac 博客
← 返回技术实践

如何为 Claude Code 创建自定义 Skills?从 SKILL.md 编写、目录配置到实际调用的完整教程

AIDevelopment ·约 11 分钟阅读

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 个字符时可能被截断。把核心用途和触发条件放在描述前面,避免开头先写背景。

保存后按步骤验证识别与调用

>

从路径到输出逐项检查,能更快区分“没加载”和“加载了但没按预期执行”:

  1. 核对目录层级。 项目级文件应位于 .claude/skills/技能目录名/SKILL.md;个人级文件应位于 ~/.claude/skills/技能目录名/SKILL.md。检查文件名大小写和目录是否多套或少套一层。
  2. 检查 frontmatter。 确认文件第一行是 ---,YAML 格式有效,字段名与官方文档一致。不要把执行步骤写进元数据区。
  3. 检查是否加载。 如果会话启动后才新建顶层 Skills 目录,按当前文档运行 /reload-skills;若只是修改已加载目录里的 SKILL.md,Claude Code 通常会在会话中检测到变化。具体行为以官方会话内编辑说明为准。
  4. 显式调用。 在消息开头输入 /review-change,并附上任务,例如:“检查当前未提交改动,只列出有代码位置依据的问题,不要修改文件。”斜杠命令只在消息开头识别,后续文本作为参数;可参阅官方命令参考。
  5. 验证自动匹配。 新开一条消息,不输入斜杠命令,直接描述与 description 一致的任务。检查输出是否遵循步骤、给出具体依据,并遵守“不修改代码”的边界。
  6. 记录差异并复测。 若命令找不到,先排查路径和会话范围;命令可用但自动匹配不稳定,优先改写描述;已经触发却偏离流程,则补充明确步骤、限制和交付格式。

可给这轮验收设一个简单评分:路径与命令可见、显式调用符合要求、自动匹配符合要求,各计 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 环境。 — 立即了解套餐方案

限时优惠

Zilmac

通过 Zilmac 租用 Apple M4 裸金属 Mac,完整 macOS 环境适合持续开发与自动化任务。

返回首页
限时优惠 点击查看套餐