Claude Code · 教学code.claude.com/docs/en/skills

Agent Skills · 可复用的能力扩展

Claude Code Skills
从零掌握

用一个 SKILL.md 文件，把反复出现的指令、流程、检查清单变成 Claude 随时可调用的能力。

SKILL.md 渐进式披露子代理 · 动态注入评估与分享

开场：今天带大家系统掌握 Claude Code 的 Skills 机制——如何把重复指令沉淀成可复用的能力。

Contents · 目录

今天讲四件事

01

认识 Skills

它是什么、何时该用、和 CLAUDE.md 的区别。

02

创建你的第一个 Skill

三步走 + 真实示例 + 存放位置与发现规则。

03

SKILL.md 结构与原理

frontmatter 字段、命令名、渐进式披露、调用控制。

04

高级用法与交付

动态注入、子代理、评估迭代、分享分发。

先看路线图：四个模块，从概念到实操再到高级与交付。

Concept · 它是什么

一个 SKILL.md，就是一项新能力

写一份带指令的 SKILL.md，Claude 就把它加入工具箱——相关时自动用，或用 /skill-name 直接调用。

📜

指令文件

SKILL.md = YAML 头 + Markdown 指令。Claude 按它办事。

🔌

随时调用

描述匹配时自动触发，也可 /name 手动调用。

🌐

开放标准

遵循 Agent Skills 标准，跨多种 AI 工具通用。

Skills 的本质：把指令沉淀成文件，Claude 按需加载。它遵循开放的 Agent Skills 标准。

When · 何时该做

CLAUDE.md vs Skills

信号：你总在反复粘贴同一段指令、检查清单或多步流程；或 CLAUDE.md 的某段从「事实」长成了「流程」。

📋 CLAUDE.md

常驻上下文，每轮都占用 token
适合放「事实」：约定、偏好、项目背景
长参考资料 = 持续成本

→

⚙️ Skill

按需加载，不用时近乎零成本
适合放「流程」：部署、提交、生成
长资料放进支持文件，按需读取

关键判据：内容是「事实」还是「流程」。事实进 CLAUDE.md，流程沉淀成 Skill，按需加载省钱。

Bundled · 开箱即用

Claude Code 自带的 Skills

每个会话都可用（除非用 disableBundledSkills 关闭）。大多是 prompt 驱动，让 Claude 编排工具完成工作。

命令	用途
`/code-review`	代码审查
`/batch`	批量处理任务
`/debug`	系统化调试
`/loop`	循环迭代优化
`/run` · `/verify`	启动并验证你的应用（v2.1.145+）
`/run-skill-generator`	为 /run、/verify 记录构建启动配方

先了解自带能力：审查、批量、调试、循环，以及 run/verify 这套启动验证组合。

Section · 02

创建你的
第一个 Skill

三步走，从空目录到一个能跑的 /skill-name。

进入实操模块：亲手创建一个 Skill。

How-to · 三步

从零到一个可调用的 Skill

1

建目录

mkdir -p ~/.claude/skills/summarize-changes

~30s

2

写 SKILL.md

两个 --- 之间写 YAML 头，下面写 Markdown 指令。

~3min

3

测试

直接 /summarize-changes 调用，或问个匹配描述的问题看是否自动触发。

~1min

4

迭代

改完即时生效——文件变动当轮就能用，无需重启。

循环

三步：建目录、写 SKILL.md、测试。第四步是持续迭代，因为热更新。

Example · 真实示例

summarize-changes / SKILL.md

frontmatter 的 description 决定何时自动触发；!`git diff HEAD` 是动态注入。

---
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.

注意两处：description 写清「做什么 + 何时用」；!`命令` 会在发给 Claude 前先执行并把输出替换进来。

Where · 放在哪

四层位置，作用范围不同

优先级：Enterprise > Personal > Project。任意层可覆盖同名的内置 Skill。

层级	路径	作用范围
Enterprise	见托管设置	组织内所有用户
Personal	`~/.claude/skills/<name>/SKILL.md`	你的所有项目
Project	`.claude/skills/<name>/SKILL.md`	仅当前项目
Plugin	`<plugin>/skills/<name>/SKILL.md`	启用该插件处，带命名空间

记住优先级链和三类路径：个人、项目、插件。项目级提交到版本控制就能团队共享。

Discovery · 发现机制

目录怎么被找到

① 向上发现
从工作目录的 .claude/skills/ 一路向上到仓库根，都会加载。
② 按需嵌套
在子目录里读/写文件时，该子目录的 .claude/skills/ 才被发现。
③ 同名加前缀
嵌套 Skill 与上层同名时，显示为 apps/web:deploy，输入全名调用嵌套版。
④ 热更新
增删改 Skill 当轮即生效；仅「新建一个会话启动时不存在的顶层 skills 目录」需重启。

四条发现规则。最实用的是热更新——改完不用重启就能测。

Structure · 目录长啥样

SKILL.md 是入口，其余按需

典型结构

my-skill/
├── SKILL.md          # 主指令（必需）
├── template.md      # 模板
├── examples/
│   └── sample.md    # 示例输出
└── scripts/
    └── validate.sh  # 可执行脚本

三条原则

SKILL.md 是唯一必需入口，其余可选
正文保持 ≤ 500 行，详尽资料移到支持文件
在 SKILL.md 里引用支持文件，让 Claude 知道何时读它们

把长内容拆到支持文件，靠引用驱动按需加载——这是控制 token 成本的关键。

Section · 03

SKILL.md
结构与原理

字段、命令名、渐进式披露、调用控制。

第三模块：拆解 SKILL.md 的字段与运行原理。

Anatomy · 两部分

SKILL.md = 头 + 身

① YAML 头（frontmatter）

夹在两个 --- 之间。告诉 Claude 何时用这个 Skill。

description 决定自动触发
其余字段控制调用、工具、模型等

② Markdown 正文

Claude 运行该 Skill 时遵循的指令。

说做什么，少讲为什么
加载后常驻上下文，每行都是成本
保持简洁

头部管「何时」，正文管「怎么做」。正文加载后常驻，所以要精简。

Content type · 写哪种

Reference 还是 Task？

📖 Reference（参考）

给 Claude 注入知识：约定、模式、风格、领域知识
inline 运行，与对话上下文并用
相关时自动加载

⚡ Task（任务）

给 Claude 分步骤指令：部署、提交、生成
常用 /name 直接调用
加 disable-model-invocation: true 防误触

两类内容：参考型偏知识、自动加载；任务型偏步骤、常手动调用并加开关防误触。

Reference · 字段速查

常用 frontmatter 字段

全部可选，仅 description 推荐。description + when_to_use 合计上限 1536 字符。

字段	作用
`description`	做什么 + 何时用；决定自动触发
`when_to_use`	补充触发场景，拼接到 description
`allowed-tools`	该 Skill 激活时免确认可用的工具
`disable-model-invocation`	true 则 Claude 不会自动加载
`context: fork`	在隔离子代理中运行
`model` / `effort`	指定模型 / 思考强度
`paths`	glob 限定激活条件

最常用就这几个。description 是核心，其余按需。

Naming · /命令名哪来的

命令名 = 目录名（通常）

来源	命名规则	示例
skills 目录下	取目录名	`.claude/skills/deploy-staging/` → `/deploy-staging`
嵌套同名	子目录路径 + 名	`apps/web/.../deploy/` → `/apps/web:deploy`
commands 文件	文件名去扩展名	`.claude/commands/deploy.md` → `/deploy`
插件	目录名 + 插件命名空间	`my-plugin/skills/review/` → `/my-plugin:review`

目录名即命令名。嵌套同名加目录前缀消歧义。commands 旧文件也兼容。

Substitution · 变量

在 SKILL.md 里引用参数

常用变量

变量	含义
`$ARGUMENTS`	全部参数
`$0` · `$1`	第 N 个参数
`$name`	arguments 声明的具名参数
`${CLAUDE_SKILL_DIR}`	SKILL.md 所在目录

用法

# 在 frontmatter 声明具名参数
arguments: issue_number format

# 正文里引用
查看 issue $issue_number，
按 $format 格式输出。

# 未出现 $ARGUMENTS 时，参数会追加在末尾

参数靠 $ARGUMENTS / $N / 具名变量。正文没写 $ARGUMENTS 时，参数自动追加到末尾。

How it works · 核心机制

渐进式披露（Progressive Disclosure）

内容只在需要时加载——长参考资料几乎零成本，直到你真正用它。

🏷️

描述常驻

description 总在上下文

→

📖

调用加载

触发时才加载全文

→

📎

按需读附件

支持文件用时才读

→

💾

当轮常驻

加载后留在会话

三层加载：描述常驻、全文按调用、附件按需。这就是 Skill 比塞进 CLAUDE.md 省钱的根因。

Lifecycle · 留多久 / 谁能调

加载之后会发生什么

内容生命周期

调用后内容当轮常驻，后续轮次不再重读文件
压缩后保留每个最近调用前 5000 token
重挂技能共享 25000 token 预算，从最近往旧填
若 Skill 似乎失效，多半仍在上下文——强化 description 或重新调用

调用控制三态

设置	你	Claude
默认	✓	✓ 自动
`disable-model-invocation:true`	✓	✗
`user-invocable:false`	✗	✓

两点：加载后常驻+压缩有预算；调用控制三态决定谁能触发。

Control · 限制 Claude 能用哪些

三种控制 Claude Skill 访问的方式

🚫

全禁用

在 /permissions 拒绝 Skill 工具。

✅

允许/拒绝特定

权限规则如 Skill(commit) 或 Skill(deploy *)。

🙈

隐藏单个

frontmatter 加 disable-model-invocation: true。

另有 skillOverrides 设置：on / name-only / user-invocable-only / off 四态控制可见性。

三道闸：全局禁、按名授权、逐个隐藏。再加 skillOverrides 做可见性微调。

Section · 04

高级用法
与交付

动态注入 · 子代理 · 评估迭代 · 分享分发。

最后模块：高级用法与如何把 Skill 交付出去。

Advanced · 动态注入

让 Skill 自带实时数据

!`命令` 在发给 Claude 之前执行，输出替换占位符——Claude 只看到结果。

规则

行首或空白后的 ! 才识别
多行命令用 ```! 代码块
只替换一次，输出不再被扫描
关掉：disableSkillShellExecution: true
含 ultrathink 可请求更深推理

示例

## 当前改动

!`git diff HEAD`

## 多行命令
```!
git log --oneline -5
```

动态注入是预处理：Claude 看到的是命令输出而非命令本身。适合让 Skill 自带实时上下文。

Advanced · context: fork

在隔离子代理里跑 Skill

怎么用

frontmatter 加 context: fork
SKILL.md 正文成为驱动子代理的 prompt
子代理拿不到你的对话历史
agent 字段指定类型：Explore / Plan / general-purpose 或自定义

注意

⚠️ fork 只适合有明确任务的 Skill。若正文只是准则而无任务，子代理收到准则却无可执行指令。

---
description: 深度审查一个目录
context: fork
agent: Explore
---

fork = 隔离运行，正文当 prompt。只给有明确任务的 skill 用，纯准则的不适合。

Advanced · 工具 / 参数

免确认工具 & 传参

allowed / disallowed-tools

allowed-tools：激活时免确认可用（不限制可用集合）
disallowed-tools：从可用池移除（下条消息后恢复）
项目级 allowed-tools 在信任工作区后才生效

传参

# 声明具名参数
arguments: filename format

# 调用
$ /convert report.md pdf

# 正文引用
读 $filename，输出 $format。
未出现的 $ARGUMENTS 会追加末尾。

allowed-tools 免确认但不缩范围；disallowed-tools 临时移除。参数靠 $N / 具名变量。

Eval · 怎么知道写得好

基线对比 + 自动化评测

1

收 prompt

收集一批真实场景 prompt 与期望行为。

2

开/关对比

每个 prompt 在全新会话里分别开/关 Skill 跑一遍。

3

看差异

对比结果，定位 description 与指令的缺口。

4

自动化

用 skill-creator 插件跑评测、打分、做 A/B 版本对比。

/plugin install skill-creator@claude-plugins-official

核心是基线对比，且必须用全新会话——否则残留上下文会掩盖指令缺口。

Ship · 交付与心得

把 Skill 交付出去

三种分发范围

Project：提交 .claude/skills/ 到版本控制
Plugin：打包成插件分发安装
Personal：放 ~/.claude/skills/ 自用

四条最佳实践

description 写清「做什么 + 何时用」
正文说做什么，少讲为什么
长内容拆到支持文件，SKILL.md ≤500 行
用 disable-model-invocation 防误触发

交付三档：项目提交、插件分发、个人自用。实践上牢记 description + 精简 + 拆文件。

Takeaways · 带走这四点

一句话回顾

① Skill = 按需加载的指令

事实进 CLAUDE.md，流程沉淀成 Skill，渐进式披露省钱。

② 目录名即命令名

建目录、写 SKILL.md、测试，热更新当轮生效。

③ description 是灵魂

写清「做什么 + 何时用」，决定自动触发是否准。

④ 高级三件套

动态注入带数据、fork 隔离跑、基线对比迭代。

四句话收尾：按需加载、目录即命令、description 为魂、高级三件套。

Thanks

现在去写你的第一个 SKILL.md 吧。

📄 code.claude.com/docs/en/skills 🔌 agentskills.io 教学版 · tokyo-night

结束。鼓励大家动手写第一个 Skill，遇到问题查官方文档。

Claude Code Skills从零掌握

今天讲四件事

认识 Skills

创建你的第一个 Skill

SKILL.md 结构与原理

高级用法与交付

一个 SKILL.md，就是一项新能力

指令文件

随时调用

开放标准

CLAUDE.md vs Skills

📋 CLAUDE.md

⚙️ Skill

Claude Code 自带的 Skills

创建你的第一个 Skill

从零到一个可调用的 Skill

建目录

写 SKILL.md

测试

迭代

summarize-changes / SKILL.md

四层位置，作用范围不同

目录怎么被找到

① 向上发现

② 按需嵌套

③ 同名加前缀

④ 热更新

SKILL.md 是入口，其余按需

典型结构

三条原则

SKILL.md结构与原理

SKILL.md = 头 + 身

① YAML 头（frontmatter）

② Markdown 正文

Reference 还是 Task？

📖 Reference（参考）

⚡ Task（任务）

常用 frontmatter 字段

命令名 = 目录名（通常）

在 SKILL.md 里引用参数

常用变量

用法

渐进式披露（Progressive Disclosure）

描述常驻

调用加载

按需读附件

当轮常驻

加载之后会发生什么

内容生命周期

调用控制三态

三种控制 Claude Skill 访问的方式

全禁用

允许/拒绝特定

隐藏单个

高级用法与交付

让 Skill 自带实时数据

规则

示例

在隔离子代理里跑 Skill

怎么用

注意

免确认工具 & 传参

allowed / disallowed-tools

传参

基线对比 + 自动化评测

收 prompt

开/关对比

看差异

自动化

把 Skill 交付出去

三种分发范围

四条最佳实践

一句话回顾

① Skill = 按需加载的指令

② 目录名即命令名

③ description 是灵魂

④ 高级三件套

Thanks

Claude Code Skills
从零掌握

创建你的
第一个 Skill

SKILL.md
结构与原理

高级用法
与交付