Claude Code 里怎么用和写 Skills

这篇适合谁，读完能做到什么

如果你总在对话里反复粘贴同一套规范、检查清单或多步流程，这篇适合你。读完你能写出第一个 Skill，知道它该放在哪个目录，明白 description 怎样决定 Claude 何时调用它，也知道哪些字段会改变它的行为。^[1]

Skills 是什么，和 CLAUDE.md 有什么区别

Skill 是一个包含说明的 SKILL.md 文件。Claude 在相关时会自动使用它，你也可以直接用 /skill-name 调用。^[1]

什么时候该写 Skill？一个信号是，你发现自己一直在把同样的说明、清单或多步操作粘贴进对话；另一个信号是，CLAUDE.md 里的某一节已经从事实变成了流程。^[1]

两者的关键区别在加载时机。CLAUDE.md 的内容每次都会加载，而 Skill 的正文只在被使用时才加载，所以长篇参考资料在需要之前几乎不占上下文。^[1]

Claude Code 的 Skills 遵循开放标准 Agent Skills，同时在标准之上扩展了三项能力：调用控制、子 agent 执行和动态上下文注入。后面几节会分别讲到。^[1]

准备

你需要一个能运行 Claude Code 的环境，以及一个用来放 Skill 的目录。Skill 只是普通的文件夹和 Markdown，不需要额外安装工具。claude plugin validate 命令需要 Claude Code v2.1.233 或更高版本。^[1]

上手：写一个 Skill

1. 建立 Skill 目录。个人 Skill 放在 ~/.claude/skills/<skill-name>/ 下，对这台机器上的所有项目都生效，可以用 mkdir -p ~/.claude/skills/summarize-changes 之类的命令建立。^[1]
2. 在目录里写 SKILL.md。它由两部分组成：开头用 --- 包起来的 YAML frontmatter，告诉 Claude 何时使用这个 Skill；之后是 Markdown 正文，写的是 Skill 运行时 Claude 要遵循的指令。^[1]
3. 目录名，或者 frontmatter 里设置的 name，会成为你在输入框里敲的命令；description 则帮助 Claude 判断何时自动加载它。^[1]

下面是一个只允许 Claude 执行 git 提交相关命令、且只能由你手动触发的 Skill 示例：

``yaml --- name: commit description: Stage and commit the current changes disable-model-invocation: true allowed-tools: Bash(git add *) Bash(git commit *) Bash(git status *) --- ``^[1]

frontmatter 里只有 description 是推荐填写的字段，其余字段都是可选的。description 最好把最核心的使用场景放在最前面。它和 when_to_use 合起来，在 Skill 列表中会被截断到 1,536 个字符，超出的部分 Claude 看不到。^[1]

写完之后，如果 Claude 没有在该用的时候用它，可以按下面几步排查：description 里是否包含用户会自然说出的关键词；What skills are available? 能否列出这个 Skill；或者直接用 /skill-name 调用。如果 frontmatter 的 YAML 解析失败，Claude Code 会只加载正文、不带任何元数据，加上 --debug 运行可以看到解析错误。^[1]

放在哪里，谁能用

存放位置决定了哪些会话会加载它。^[1]

• 企业 Skill：放在托管设置目录里的 .claude/skills/ 下，在组织部署的机器上，所有用户都能用。^[1]
• 个人 Skill：~/.claude/skills/<skill-name>/SKILL.md，你在这台机器上的所有项目都能用，但不包括 Cowork 和云端会话。^[1]
• 项目 Skill：仓库里的 .claude/skills/<skill-name>/SKILL.md。提交到仓库之后，团队成员也能获得它。^[1]
• 插件 Skill：放在 <plugin>/skills/<skill-name>/SKILL.md，插件启用的地方都能用，调用名是 /plugin-name:skill-name。^[1]

项目 Skill 的查找范围比较宽。Claude Code 会从你启动的目录开始，一直往上查到仓库根目录，所以在 packages/frontend/ 里启动，也能读到根目录的 Skill。^[1]

反过来，子目录里的 Skill 不会在启动时加载。它们会在 Claude 第一次读取或编辑那个子目录里的文件时才加载，并在本次会话中一直可用。^[1]

用 --add-dir 添加的目录，其 .claude/skills/ 下的 Skill 也会在该次会话中加载。^[1]

还有一个规则：不要把 Skill 目录命名为 synced，不论大小写。Claude Code 把从 claude.ai 同步下来的 Skill 放在 ~/.claude/skills/synced/，同名的自建目录会被跳过。^[1]

改动之后要不要重启

不用。Claude Code 会监视 Skill 目录，你在 ~/.claude/skills/ 或项目的 .claude/skills/ 下增、改、删 Skill，都会在当前会话里生效，不必重启。唯一的例外是：如果你新建的是一个原先不存在的顶层 skills 目录，需要运行 /reload-skills 才能读到其中的 Skill，而且之后这个目录的每次改动都要再运行一次它。^[1]

调用控制与工具授权

默认情况下，你和 Claude 都能调用任何 Skill。两个 frontmatter 字段可以限制这一点。^[1]

• disable-model-invocation: true：Claude 不会自动加载它，适合有副作用、或者你想自己决定时机的流程，例如部署或发消息。默认值是 false。^[1]
• user-invocable: false：只有 Claude 能调用，它会从 / 菜单里隐藏，适合纯背景知识。默认值是 true。^[1]

allowed-tools 字段会让 Claude 在调用该 Skill 的那一轮里，无需询问就能使用列出的工具。这个授权会在你发送下一条消息时清除；想再次生效，需要重新调用。^[1]

需要注意，项目 Skill 的 allowed-tools 即使在你没有信任的文件夹里也会生效。所以在仓库中审查别人提交的 Skill 时，要先看它的 allowed-tools。^[1]

进阶：参数、子 agent 与支持文件

调用时跟在 Skill 名字后面的内容，会替换正文里的 $ARGUMENTS。$ARGUMENTS[N] 或 $N 可以按从 0 开始的下标取第 N 个参数。^[1]

${CLAUDE_SKILL_DIR} 展开为 SKILL.md 所在的目录。在需要引用 Skill 自带脚本的场景里，用它比写相对路径可靠，因为它不受当前工作目录影响。^[1]

加上 context: fork 后，Skill 会在一个新的子 agent 中运行，子 agent 的类型由 agent 字段指定。子 agent 看不到你的对话历史，所以 Skill 的指令必须能独立成立；如果任务依赖前面的讨论，就不该用这个设置。^[1]

Skill 目录里还可以放支持文件，比如 reference.md、examples.md 和 scripts/helper.py。在 SKILL.md 里说明每个文件的用途和何时读取，Claude 就会在需要时加载参考文件；脚本则是被执行，而不是被加载进上下文。^[1]

常见问题

Claude 中途不再遵循 Skill。 Skill 的内容会一直留在对话里，但 Claude Code 之后不会重新读取文件。如果会话被压缩，只会保留每个已调用 Skill 的前 5,000 个 token，所以最重要的指令要放在 SKILL.md 的前面。^[1]

必须每次都成立的规则。 这类规则不要只写进 Skill，而应该做成 hook。hook 会在对应事件发生时执行，不论 Claude 当时是否在遵循某个 Skill。^[1]

下一步

想看全部字段的说明、字符串替换变量和调用控制的完整细节，可以接着读 Claude Code 官方文档中的 Skills 页面。^[1]