Claude Code Skills 怎么用？SKILL.md 编写教程与实用 Skill 示例（2026）

Claude Code Skills 是给 Claude 装"技能包"的方式：把一套固定流程写进一个 SKILL.md 文件，Claude 会在需要时自动加载，你也可以用 /技能名 直接调用。发版检查、代码审查、写提交信息这类重复工作，写成 Skill 后一条命令就能完成。

本文讲清 Claude Code Skills 是什么、和 CLAUDE.md 有什么区别，演示 SKILL.md 怎么写，并给出 3 个可以直接复制的 Skill 示例。还不熟悉 Claude Code 的基本用法，可以先看《Claude Code 教程：2026 Claude Code 安装与使用指南》。

---

Claude Code Skills 是什么

官方的定义是：Skill 扩展了 Claude 能做的事。你写一个带说明的 SKILL.md，Claude 就把它加入自己的工具箱，在相关时自动使用，或者由你用 /skill-name 直接调用。

Skills、CLAUDE.md 与斜杠命令的区别

对比项	CLAUDE.md	Skills
加载时机	每次会话启动时完整加载	启动时只加载描述，用到时才加载全文
适合内容	每次都需要的规则：命令、规范、目录结构	只在特定任务中用到的流程和参考资料
调用方式	自动生效	Claude 自动调用，或你用 /名称 手动调用
Token 成本	每轮请求都占用	不用时几乎不占用

过去的自定义斜杠命令已经合并进 Skills：.claude/commands/deploy.md 和 .claude/skills/deploy/SKILL.md 都会创建 /deploy，用法相同，原有的 commands 文件可以继续使用。Skills 额外支持附带文件、控制谁能调用，以及由 Claude 自动加载。

CLAUDE.md 的写法见《CLAUDE.md 怎么写？Claude Code 项目记忆配置指南》。经验法则：每次都要遵守的写进 CLAUDE.md，偶尔才用的流程写成 Skill。

---

Claude Code Skills 放在哪里

位置	路径	生效范围
个人	~/.claude/skills/<技能名>/SKILL.md	你的所有项目
项目	.claude/skills/<技能名>/SKILL.md	当前项目，可通过 Git 共享给团队
插件	<插件>/skills/<技能名>/SKILL.md	安装该插件的项目，以 /插件名:技能名 调用
企业	托管设置目录下的 .claude/skills/	组织内所有人

同名 Skill 的优先级是：企业 > 个人 > 项目。

---

SKILL.md 怎么写

最小示例

官方文档的入门示例，保存为 ~/.claude/skills/summarize-changes/SKILL.md：

---
description: Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed, wants a commit message, or asks to review their diff.
---

## Current changes

!`git diff HEAD`

## Instructions

Summarize the changes above in two or three bullet points, then list any risks you notice such as missing error handling, hardcoded values, or tests that need updating. If the diff is empty, say there are no uncommitted changes.

其中 !`git diff HEAD` 这一行是动态上下文注入：Claude Code 会先执行这条命令，把输出替换到这一行，Claude 看到的就是真实的改动内容。

常用 frontmatter 字段

所有字段都是可选的，官方建议至少写 description，Claude 靠它判断什么时候使用这个 Skill。

字段	作用
name	/ 菜单中显示的命令名，默认是目录名
description	这个 Skill 做什么、什么时候用
when_to_use	补充触发场景，例如关键词或示例请求
argument-hint	输入命令时提示需要什么参数
disable-model-invocation	设为 true 时只能手动调用，Claude 不会自动加载
user-invocable	设为 false 时只允许 Claude 调用
allowed-tools	调用该 Skill 时无需确认即可使用的工具
model / effort	本轮使用的模型和思考强度
context	设为 fork 时在独立的子代理上下文中运行
paths	只在处理匹配的文件时激活

用 $ARGUMENTS 传参数

$ARGUMENTS 会被替换为调用时传入的全部参数，$0、$1 可以取单个参数。比如 Skill 正文写"按团队规范修复 GitHub Issue $ARGUMENTS"，运行 /fix-issue 123 时 Claude 收到的就是"修复 GitHub Issue 123"。如果正文里没有占位符，参数会以 ARGUMENTS: <输入内容> 的形式追加在末尾。

附带参考文件和脚本

一个 Skill 目录可以放多个文件：

my-skill/
├── SKILL.md        # 必需：概述和导航
├── reference.md    # 详细文档，需要时才读取
├── examples.md     # 使用示例，需要时才读取
└── scripts/
    └── helper.py   # 工具脚本，执行而不是读取

官方建议 SKILL.md 控制在 500 行以内，详细资料拆到附带文件里，用到时再读。

---

3 个实用 Claude Code Skills 示例

示例一：生成规范的提交信息

.claude/skills/commit/SKILL.md：

---
description: 根据暂存区改动生成符合团队规范的提交信息。用户要求提交代码或写 commit message 时使用。
disable-model-invocation: true
---

## 暂存区改动

!`git diff --cached`

## 要求

- 格式：<type>: <简短描述>，type 只能是 feat、fix、docs、refactor、test
- 第一行不超过 72 个字符，正文说明改动原因
- 生成后执行 git commit，不要 push

设置 disable-model-invocation: true，确保只有你输入 /commit 时才会提交，避免 Claude 自行决定提交代码。

示例二：按规范修复 Issue

.claude/skills/fix-issue/SKILL.md：

---
description: 按团队规范修复指定编号的 GitHub Issue
argument-hint: <issue 编号>
---

修复 GitHub Issue #$ARGUMENTS：

1. 用 gh issue view $ARGUMENTS 读取问题描述
2. 找到相关代码，先写一个能复现问题的测试
3. 修复代码，确保新测试和已有测试全部通过
4. 总结改动，不要直接提交

示例三：上线前检查清单

.claude/skills/release-check/SKILL.md：

---
description: 上线前检查清单。用户说要发版、上线或部署时使用。
---

依次执行并汇报结果，任何一项失败就停止：

1. 运行类型检查和 lint
2. 运行全部单元测试
3. 检查是否有未提交的改动
4. 列出自上次 tag 以来的提交，按 feat / fix 分类生成发版说明

---

Claude Code Skills 的 Token 占用

普通会话中，只有每个 Skill 的描述会进入上下文，完整内容在调用时才加载；单个 Skill 的 description 和 when_to_use 合计超过 1,536 个字符会被截断。所以：

• 描述写短、写准：说清"做什么、什么时候用"，Claude 才能在对的时候调用；
• 长篇参考资料放进附带文件，不要堆在 SKILL.md 里；
• 只想手动使用的 Skill 设置 disable-model-invocation: true，它的描述就不会常驻上下文。

把 CLAUDE.md 里的专项流程迁移到 Skills，是降低 Claude Code Token 消耗的有效方法之一，更多做法见《Claude Code Token 消耗太快？10 个 Claude Code 省 Token 技巧》。Skill 需要调用外部服务时，可以配合 MCP 使用，配置方法见《Claude Code MCP 怎么配置？》。

---

常见问题 (FAQ)

Q: Claude Code Skills 和斜杠命令有什么区别？

答： 自定义斜杠命令已经合并进 Skills，.claude/commands/ 下的文件和 .claude/skills/ 下的 SKILL.md 都会生成同名命令；Skills 额外支持附带文件、控制调用方式和由 Claude 自动加载。

Q: SKILL.md 必须写哪些字段？

答： 所有 frontmatter 字段都是可选的，官方建议至少写 description，说明这个 Skill 做什么、什么时候用，Claude 会据此判断是否自动调用。

Q: 怎么让 Skill 只能手动调用？

答： 在 SKILL.md 的 frontmatter 中设置 disable-model-invocation: true，这样 Claude 不会自动加载它，只有你输入 /技能名 时才会运行。

Q: Claude Code Skills 会占用很多 Token 吗？

答： 不会太多，会话中默认只加载每个 Skill 的描述，完整内容在调用时才加载；设置了 disable-model-invocation 的 Skill，描述也不会常驻上下文。

Q: 个人 Skill 和项目 Skill 同名时用哪个？

答： 同名时优先级为企业 Skill 高于个人 Skill，个人 Skill 高于项目 Skill，所以 ~/.claude/skills/ 下的同名 Skill 会覆盖项目里的。