Skills 深入

如果说斜杠命令是你「亲手按下的开关」，那 Skills（技能）更像一排按需抽屉：平时只露出一行标签，等你真正需要里面的东西，抽屉才整个拉开。你不用记住所有抽屉里装了什么——Claude 会根据你正在做的事，自己判断该拉开哪一个。

这一篇把 Skills 的结构、加载原理、内置技能、调用控制和实战用法一次讲透。

SKILL.md 的完整结构

一个 Skill 就是一个文件夹，里面必须有 SKILL.md。位置可以是项目级 .claude/skills/<name>/SKILL.md，也可以是用户级 ~/.claude/skills/<name>/SKILL.md。

SKILL.md 由两部分组成：YAML frontmatter + Markdown 正文。

---
name: commit-messages
description: 当用户要求生成或改写 git commit message 时使用。读取 staged diff，按 Conventional Commits 规范生成中文 commit。
allowed-tools: Read, Bash
argument-hint: [可选：提交范围，如 HEAD~3]
disable-model-invocation: false
---

# Commit Messages 技能

## 何时触发
用户说「帮我写 commit」「生成提交信息」「这次改了啥」时触发。

## 步骤
1. 运行 `git diff --cached` 读取暂存区改动
2. 按改动类型判断 type：feat / fix / refactor / docs / test / chore
3. 生成一行简短摘要（不超过 50 字符）+ 空行 + 详细说明
4. 询问用户是否直接 `git commit`

## 规范
- 摘要用动宾结构：「修复登录页空指针」而非「关于登录页的修复」
- 详细说明每条改动占一行，以 `- ` 开头
- 涉及 issue 加尾注：`Closes #123`

frontmatter 字段逐个讲

字段	作用	是否必填
`name`	技能名，也是显式调用的命令名（`/commit-messages`）	必填
`description`	最关键字段。Claude 靠它判断何时自动触发	必填
`allowed-tools`	限制该技能能用哪些工具，逗号分隔	可选
`argument-hint`	给用户看的参数提示，显示在命令面板	可选
`disable-model-invocation`	设为 `true` 则禁止自动触发，只能 `/name` 显式调用	可选

经验之谈：description 写得好，技能才会被用起来。写「用于代码审查」太泛，Claude 会在不该触发时触发；写「当用户请求审查 Pull Request、查找安全漏洞或检查代码规范时使用」就精准得多。

渐进式披露：为什么 Skills 不会撑爆上下文

这是 Skills 设计上最聪明的地方。假设你装了 20 个技能，如果每个都把全部内容塞进上下文，光技能就能吃掉几万 token。

实际发生的是三级加载：

启动时        →  只加载每个技能的 name + description（约 100 token/个）
匹配时        →  加载匹配技能的完整 SKILL.md 正文
引用支持文件时 →  按需读取该文件夹下的脚本、文档

也就是说，20 个技能在启动时只占 ~2000 token。只有当 Claude 判断「现在需要这个技能」时，才把对应那一份完整拉进来。

支持文件：技能文件夹里的「弹药库」

SKILL.md 所在的文件夹里，你可以放任意辅助文件：

.claude/skills/pdf-processing/
├── SKILL.md
├── SECURITY.md          # 安全注意事项
├── PERFORMANCE.md       # 性能调优笔记
├── scripts/
│   ├── extract.py       # 提取脚本
│   └── compress.py      # 压缩脚本
└── templates/
    └── report.md

在 SKILL.md 正文里引用它们，Claude 会在需要时读取：

处理大文件时，先阅读 PERFORMANCE.md 中的优化建议。
涉及用户上传的 PDF，必须遵守 SECURITY.md 中的沙箱规则。

这就是动态上下文注入（dynamic context injection）：相关材料随用随取，不相关的不占地方。

内置技能：开箱即用的五件套

Claude Code 自带一批 bundled skills，无需配置即可使用。它们是基于提示编排的技能——不是硬编码逻辑，而是让模型按指令分步完成。

技能	触发场景	做什么
`/simplify`	代码太绕、想精简	找出冗余抽象，用更少代码达成同样效果
`/debug`	报错了、跑不通	系统化定位根因，给出最小修复方案
`/loop`	需要反复迭代	自动循环「执行→检查→修正」直到达标
`/batch`	批量同类操作	对一组文件/函数做相同改造
`/claude-api`	要调用 Claude API	生成符合最新 SDK 的调用代码

这些内置技能遵循同样的渐进式披露：平时不占上下文，用到才加载。

调用控制：自动 vs 显式

技能有两种触发方式：

模型自动调用（model invocation）：Claude 读到你的话，自己判断该用哪个技能。大多数技能默认走这条路。
显式调用：你在输入框敲 /skill-name，点名要用某个技能。

如果你有个技能只想被显式触发（比如一个会消耗较多 token 的大改造流程），把 disable-model-invocation 设为 true：

disable-model-invocation: true

这样 Claude 不会自作主张触发它，只能你手动 /big-refactor 调用。

在子代理中执行

技能还可以在 subagent（子代理）上下文中执行。这意味着一个复杂技能可以把重活外包给独立上下文的子代理，主会话保持清爽。子代理执行完，把摘要交还主代理。这种「委托-返回」模式在 Subagents 深入里展开讲。

Skills vs Commands：到底用哪个

官方文档给了一张对比表，这里转述要点：

维度	Slash Commands（斜杠命令）	Skills（技能）
触发方式	必须显式 `/command`	自动触发 + 可显式
上下文加载	调用时一次性加载	渐进式披露，按需加载
适合场景	你已知的固定流程	Claude 根据情境判断的专家能力
支持文件	命令文件即全部	可带一整个文件夹的支持材料
复用粒度	一个项目常用动作	跨项目可复用的专业能力

一句话记忆：Command 是「我喊一声它就干」，Skill 是「它自己看情况动手」。

什么时候用 Skill

能力会跨项目复用（如 commit message 规范、PDF 处理）
触发条件依赖上下文，Claude 自己能判断
需要附带脚本、模板等支持文件

什么时候用 Command

流程固定、步骤明确（如 /ship 打包发布）
你想每次都亲自触发，不交给模型判断
只是当前项目的一次性脚本

三个真实示例

1. commit-messages 技能

把团队提交规范固化下来，让每次 commit 都符合 Conventional Commits——上文已给完整示例。

2. code-review-standards 技能

---
name: code-review-standards
description: 当用户请求代码审查、检查 PR、或查找代码异味与安全问题时使用。按团队规范逐项检查。
allowed-tools: Read, Grep, Glob
---

注意 allowed-tools 限制了它只能读、不能改——审查员不该顺手改代码。

3. pdf-processing 技能

带脚本和文档的复合技能，处理 PDF 时调用文件夹里的 Python 脚本，并遵守同目录的安全与性能规范。

最佳实践速记

description 要写触发条件：不是「用于 X」，而是「当用户做 A/B/C 时使用」。
能限制工具就限制：审查类技能用 allowed-tools: Read, Grep, Glob。
重活外包给子代理：避免技能在主会话里堆积上下文。
支持文件命名清晰：SECURITY.md、PERFORMANCE.md 这种约定俗成的名字，Claude 一看就懂。
先 Command 验证流程，再沉淀成 Skill：流程没跑通别急着做技能。

Skills 的精髓在于让模型自己判断时机，把「专家能力」封装成按需加载的模块。下一篇看 Subagents 深入，了解复杂任务怎么拆给独立上下文的子代理。🚀