Claude Code Skills 怎么写:SKILL.md 格式、放置位置、调用控制与排错
Claude Code Skills 是带 SKILL.md 的文件夹,可自动加载或用斜杠命令调用。本文按官方文档讲解 SKILL.md 写法、个人与项目技能位置、frontmatter 字段、调用控制、上下文成本和技能不触发的排查。
Claude Code Skills 就是一个带 SKILL.md 文件的文件夹:你把反复粘贴给 Claude 的说明、检查清单或多步骤流程写进去,Claude 会在相关时自动加载,你也可以输入 /技能名 直接调用。个人技能放在 ~/.claude/skills/<技能名>/SKILL.md,项目技能放在仓库的 .claude/skills/<技能名>/SKILL.md。下面按 Claude Code 官方文档讲清技能的写法、放置位置、调用控制和排错,帮你判断一段指令该写成技能还是留在 CLAUDE.md。
什么时候该写成技能
官方文档给出的标准很具体:当你一再把同一段说明、检查清单或多步骤流程粘贴进对话,或者 CLAUDE.md 里某一节已经从“事实”长成了“流程”,就该把它做成技能。两者的关键区别在于加载方式。CLAUDE.md 的内容每次会话都在上下文里,技能的正文只有被使用时才加载,所以很长的参考资料在用到之前几乎不占成本。
还有一个变化需要知道:自定义命令已经并入技能。放在 .claude/commands/deploy.md 的文件和放在 .claude/skills/deploy/SKILL.md 的技能都会生成 /deploy,效果相同,旧的 commands 文件继续可用。技能多出的能力是可以带配套文件、可以用 frontmatter 控制由谁调用,以及能被 Claude 在相关时自动加载。官方建议新工作优先用技能。
Claude Code 的技能遵循 Agent Skills 开放标准,这个标准可以在多个 AI 工具中使用;Claude Code 在标准之上增加了调用控制、在子代理中运行和动态上下文注入等扩展。
第一个技能:三步写好 SKILL.md
官方入门示例是一个总结未提交改动并标出风险的技能。第一步,在个人技能目录建文件夹:mkdir -p ~/.claude/skills/summarize-changes。个人技能对你本机的所有项目生效。
第二步,写 SKILL.md。每个技能文件由两部分组成:开头两行 --- 之间的 YAML frontmatter,告诉 Claude 何时使用这个技能;后面是 Markdown 正文,写 Claude 运行技能时要遵循的指令。文件夹名(或 frontmatter 里的 name)就是你要输入的命令名,description 帮助 Claude 判断何时自动加载。示例的 description 写的是“总结未提交的改动并标出风险,在用户问改了什么、要提交信息或要求审查 diff 时使用”。正文里有一行 ` !git diff HEAD `,这是动态上下文注入:Claude Code 会先执行这条命令,用输出替换这一行,Claude 看到技能内容时,当前的 diff 已经在里面了。
第三步,测试。在一个 git 项目里改一点东西,运行 claude,然后要么问一句和描述匹配的话,比如“我改了什么”,让 Claude 自动调用;要么直接输入 /summarize-changes。两种方式都应该得到一段改动摘要和风险列表。
技能放在哪里:个人、项目、插件和企业
放置位置决定哪些会话能加载它。官方列出的位置有:企业级,放在托管设置目录,覆盖组织部署到的所有机器上的所有用户;个人级,~/.claude/skills/,覆盖你本机的所有项目,但不包括 Cowork 和云端会话;项目级,仓库里的 .claude/skills/,覆盖这个仓库的会话,提交到版本库后团队成员也能用;嵌套级,放在子目录的 .claude/skills/ 里;插件级,以 /插件名:技能名 的形式在启用插件的地方可用;以及同步自 claude.ai 账号的技能。
重名时的规则也写得很清楚:企业级优先于个人级,个人级优先于项目级。比如 ~/.claude/skills/ 和项目 .claude/skills/ 里都有 deploy,/deploy 运行的是个人那一份。技能和 .claude/commands/ 里的同名文件冲突时,技能优先。你的技能和内置技能同名时,会替换内置命令,但不会替换它的别名。插件技能因为带命名空间,不会和其他技能冲突。
在 monorepo 里,Claude Code 会从启动目录一路向上到仓库根目录加载每一级的 .claude/skills/,所以在 packages/frontend/ 启动也能用到根目录定义的技能。启动目录下方子目录里的技能不会在启动时加载,要等 Claude 第一次读写那个子目录里的文件后才出现在斜杠菜单里。
云端要单独注意。Cowork 会话和云端会话不会读取你本机的 ~/.claude/skills/。想在这些会话里用个人技能,需要在 claude.ai 账号里启用它;对于项目线程以外的云端会话,也可以把技能提交到仓库的 .claude/skills/。
frontmatter 关键字段
frontmatter 的所有字段都是可选的,官方只推荐必写 description。几个最常用的字段:name 是斜杠菜单里显示的命令名,默认取文件夹名;description 说明技能做什么、何时使用,不写时取正文第一行非空内容;when_to_use 用来补充触发短语或示例请求;argument-hint 在自动补全时提示需要什么参数,例如 [issue-number];allowed-tools 列出调用技能那一轮里无需再询问就能使用的工具;paths 用 glob 限定只在处理匹配文件时自动加载;context: fork 让技能在独立的子代理里运行。
有两个细节决定技能能不能被正确识别。第一,只有当开头的 --- 位于文件第一行时,Claude Code 才会读取 frontmatter,否则整个文件都会被当作正文。第二,字段名必须和文档完全一致,Claude Code 会静默忽略不认识的字段,不会报错。另外,description 加 when_to_use 在技能列表里合计最多显示 1,536 个字符,超出部分会被截断,所以要把最关键的使用场景写在最前面。
控制谁来调用技能
默认情况下,你和 Claude 都可以调用任意技能。两个字段可以收紧这一点。disable-model-invocation: true 表示 Claude 不能自己调用,适合有副作用或需要你掌控时机的流程,比如提交、部署、发消息;官方的说法是,你不会希望 Claude 因为觉得代码差不多了就自己去部署。user-invocable: false 表示只有 Claude 能调用,适合不构成操作的背景知识,比如解释旧系统如何运作的说明。
这两个字段也影响上下文成本。默认和 user-invocable: false 时,技能描述始终在上下文里,完整内容在调用时加载;设了 disable-model-invocation: true 后,连描述都不进上下文,只在你手动调用时加载。
调用时可以传参数。正文里的 $ARGUMENTS 会被替换为技能名后面的内容,例如 /fix-issue 123;也可以用 $ARGUMENTS[0] 或简写 $0、$1 按位置取参数。如果调用时带了参数但正文没有占位符,Claude Code 会在技能内容末尾追加 ARGUMENTS: 加上你输入的内容。
配套文件和上下文成本
技能文件夹可以放多个文件,让 SKILL.md 只保留要点,详细的 API 文档、示例集合放到单独文件里,在 SKILL.md 中写明每个文件的内容和何时读取,Claude 需要时再加载;脚本可以直接执行,不必加载进上下文。官方建议 SKILL.md 控制在 500 行以内。
技能一旦被调用,渲染后的内容会作为一条消息留在对话里,后续轮次不会重新读取文件。所以正文要写成持续有效的指令,例如“每次修改后都运行测试”,而不是一次性的“运行测试”。自动压缩上下文时,Claude Code 会为每个技能重新附上最近一次调用的前 5,000 个 token,所有重新附加的技能共享 25,000 个 token 的预算,从最近调用的技能开始填充,因此最重要的指令要放在文件前面。allowed-tools 授予的权限只在调用那一轮有效,你发出下一条消息后就会清除。
技能不触发或不被遵守时怎么排查
技能不触发时,官方给出的检查顺序是:描述里是否包含用户自然会说的关键词;问一句“What skills are available?”看技能是否出现在列表里;换个更贴近描述的说法;直接用 /技能名 调用。如果 frontmatter 的 YAML 格式有误,技能仍会加载,但元数据为空,此时 /技能名 能用,Claude 却无法根据描述匹配;用 --debug 启动可以看到解析错误,也可以运行 claude plugin validate .claude/skills 查找解析失败的文件。
技能触发太频繁时,把描述写得更具体,或者加上 disable-model-invocation: true 改为只能手动调用。Claude 一开始遵守、后来不遵守时,官方建议分情况处理:必须每次都执行的规则改用 hook,因为 hook 在事件发生时一定运行;需要判断的指导改写成适用于整个任务的措辞;如果对话被压缩过,就重新调用一次技能恢复完整内容。
技能很多时,技能列表的描述会按预算被截断,预算是模型上下文窗口的 1%,最少调用的技能最先被去掉描述。运行 /doctor 可以估算列表的上下文成本。
Claude Code 的 Skills 和斜杠命令有什么区别
自定义命令已经并入技能,两种写法都能生成同一个斜杠命令。技能多了配套文件、调用控制和自动加载,官方建议新写的用技能。
技能写在 CLAUDE.md 里不行吗
可以,但 CLAUDE.md 每次会话都占上下文。流程性的长内容做成技能后,只在使用时加载。
个人技能为什么在云端会话里找不到
云端会话和 Cowork 不读取本机 ~/.claude/skills/。需要在 claude.ai 账号中启用该技能,或把技能提交到仓库。
SKILL.md 应该写多长
官方建议控制在 500 行以内,详细资料放进配套文件。
