技能 Skills

技能 Skills

想象你有一个工具柜，每个抽屉里装着一类工具。平时抽屉是关着的，只在外面贴一张小标签写着「这个抽屉装什么」。你需要用到某类工具时，才把对应抽屉拉开。

这就是 Skills 的工作方式。它和命令不一样——命令是你主动敲 /xxx 触发，而 Skill 是 Claude 自己判断要不要用，按需展开。

SKILL.md：技能的载体

一个 Skill 就是一个目录，里面放一个 SKILL.md 文件。目录结构：

.claude/skills/
  react-hooks-guard/
    SKILL.md
  api-design/
    SKILL.md
  git-conflict-resolver/
    SKILL.md
    examples/
      rebase.md

SKILL.md 的开头是 YAML frontmatter，声明这个技能叫什么、做什么：

---
name: react-hooks-guard
description: 检查 React Hooks 的使用是否符合规则，避免违反 hooks 法则
---

# React Hooks 守护

当用户编写或修改 React 组件时，检查以下规则：

1. Hooks 只能在函数组件顶层调用，不能在循环、条件、嵌套函数里
2. 自定义 Hook 必须以 use 开头
3. 依赖数组必须完整

发现违反时，指出问题并给出修复建议。

name 和 description 是必填的。description 特别重要——它是那张「抽屉外的小标签」。

渐进式披露：为什么省 token

这是 Skill 设计最精妙的地方。

如果每次会话都把所有技能的完整内容塞进上下文，10 个技能可能就吃掉几万 token。所以 Skills 用了渐进式披露（progressive disclosure）：

阶段	进上下文的内容	大约 token
预加载	每个技能的 name + description	约 100 token/个
展开	Claude 判断需要时，才读完整 SKILL.md	按需

也就是说，平时只有「标签」进上下文。Claude 看到所有标签，知道有哪些抽屉可用，但抽屉里的东西不占地方。只有当它判断「这个任务需要用 react-hooks-guard 技能」时，才把那个 SKILL.md 的完整内容读进来。

打个比方：图书馆的目录卡占不了多少地方，但你要查某本书时，才去架上取下来翻。目录常驻，内容按需——这就是渐进式披露省 token 的原理。

对比一下 Skills 和 CLAUDE.md 的开销：

• CLAUDE.md：每次全量进上下文，所以写长了费 token。
• Skills：只有标签进上下文，写多长都行，用到才读。

所以一个原则是：稳定的、每次都要遵守的规矩写进 CLAUDE.md；特定场景才用的能力写成 Skill。

自动发现：不用注册

Skills 不需要你手动「注册」或「声明」。Claude Code 启动会话时，会自动扫描几个目录，发现里面的 SKILL.md：

位置	作用域
.claude/skills/	项目级，随仓库走
~/.claude/skills/	用户级，跨项目

放进去，下次会话就能用——这就是自动发现。你不用在某个配置文件里列出技能清单，放对位置就行。

内置技能

Claude Code 自带一些内置技能，常用的有：

技能	作用
/simplify	简化当前代码，去冗余
/debug	系统化调试当前问题
/loop	循环改进直到目标达成
/batch	批量处理同类任务
/claude-api	用 Claude API 写代码时参考

这些是官方写好、随 Claude Code 一起发布的，不用你配置。和自定义 Skill 一样，它们也走渐进式披露。

调用控制：谁决定用哪个技能

这里有个微妙的点：Skill 既可以被 Claude 自动调用，也可以被你手动触发。

• 自动调用：Claude 看到 description 觉得「这个任务匹配」，主动读进来用。比如你写 React 组件，它自动拉出 react-hooks-guard。
• 手动调用：你明确说「用 xxx 技能」或者通过命令触发。

你可以通过 frontmatter 的字段控制调用行为，比如限制某个技能只在特定工具场景下才被自动展开，避免它在不该出现的时候跳出来。

Skill 和 Commands 的关系

这是最容易混的一对。再用一次抽屉的比喻：

维度	命令 Commands	技能 Skills
触发	你主动敲 /xxx	Claude 自己判断要不要用
载入	调用时才读	标签常驻，内容按需展开
适合	特定动作（提交、推送、建 PR）	通用能力（审查、规范、检查）
文件	.claude/commands/x.md	.claude/skills/x/SKILL.md
上下文开销	调用时一次性进入	平时只占约 100 token

一句话：要你按下才动，用命令；要 Claude 自己想起来，用技能。

两者底层都是 markdown，但触发逻辑完全不同。命令像「按钮」，技能像「条件反射」。

它们怎么配合

实战中，Skills 和 Commands 经常配合用。举个例子：

• 写一个 code-review Skill，描述「审查代码时该看哪些点」。Claude 每次 /review 时自动拉出来参考。
• 再写一个 /pr 命令，封装「跑测试 → 提交 → 推送 → 用 code-review 技能审查 → 生成 PR 描述」的流程。

技能管「怎么审」，命令管「什么时候审」。一软一硬，配合起来既灵活又可控。

一个实战：把团队规范变成技能

假设你的团队有一套 API 设计规范。别写在 CLAUDE.md 里（每次进上下文太重），写成 Skill：

.claude/skills/api-design/SKILL.md

---
name: api-design
description: 设计 REST API 时遵循团队规范，包括命名、版本、错误处理、分页
---

# API 设计规范

## 命名
- 路径用复数名词：/users 而非 /user
- 用小写连字符：/user-profiles 而非 /userProfiles

## 版本
- URL 版本：/v1/users
- 破坏性变更才升大版本

## 错误
- 统一用 RFC 7807 的 problem+json 格式
- 状态码 + title + detail

## 分页
- 游标分页，不用 offset
- 返回 next_cursor

之后只要你在设计 API，Claude 自动会把这套规范拉出来用——你不用每次提醒。团队把 .claude/skills/ 提交进 git，规范就跟着仓库走。

一句话总结

Skills 是按需展开的抽屉：SKILL.md 写能力，frontmatter 贴标签，渐进式披露让标签常驻、内容按需，自动发现放对位置就能用。和命令的区别是——命令你按才动，技能 Claude 自己想起来。

---

下一站，去 子代理 Subagents 看看怎么把活外包给「独立上下文的外聘顾问」。🚀