Claude Code 学习站
v2.1.201

Skills

Skill 是一份带触发条件的指令包。Claude 在合适场景自动加载,把领域知识、工作流标准化。

Skill 是什么

Skill = 触发描述 + 一组指令(可选 + 资源文件)。

跟 agent 的区别:

| 维度 | Agent | Skill | | --- | --- | --- | | 触发 | 你显式调用 | Claude 根据描述自动判断是否加载 | | 作用域 | 起一个独立上下文 | 在主上下文里执行 | | 用途 | 长任务、研究、并行 | 工作流标准化、领域知识 |

举例:你写了一个 git-commit skill,描述是「写 git commit message 时使用」。每次你说"帮我 commit",Claude 自动加载这个 skill,按你定义的规范写 message。

怎么创建

放在 ~/.claude/skills/<name>/SKILL.md 或项目 .claude/skills/<name>/SKILL.md。

最小例子:

---
name: tdd-loop
description: 用 TDD 流程实现一个新功能时使用。先写测试,跑红,写实现,跑绿,重构。
---
 
# TDD Loop
 
按以下顺序操作:
 
1. 跟用户确认需求,把功能拆成可测试的小单位
2. 在合适的测试文件里加一个 **失败** 的测试
3. 运行测试,确认它失败(红)
4. 写最少代码让测试通过(绿)
5. 重构,跑测试确认还是绿
6. 重复直到所有小单位完成
 
不要批量写测试再批量写实现 —— 严格一个一个来。

description 字段非常关键 —— Claude 用它来决定何时加载这个 skill。要写得具体且包含触发词。

实战示例

示例 1:统一的 PR 描述模板

~/.claude/skills/pr-description/SKILL.md:

---
name: pr-description
description: 创建 GitHub PR 时使用,自动生成符合团队规范的描述
---
 
PR 描述固定四段:
 
## 背景
为什么改这个,关联什么 issue。
 
## 改动
按文件分组,简明列出做了什么。
 
## 测试
- [ ] 单元测试覆盖
- [ ] 手动验证场景
- [ ] CI 通过
 
## 风险
潜在影响和回滚方式。

之后你说 创建 PR 时,Claude 会按这个模板写。

示例 2:封装领域知识

~/.claude/skills/our-api/SKILL.md:

---
name: our-api
description: 调用公司内部 API 时使用,包含鉴权、分页、错误码约定
---
 
我们的 API:
 
- **base url**: 内部 `https://api.internal.example.com`
- **鉴权**: header `X-Internal-Token`,从环境变量 `INTERNAL_TOKEN` 取
- **分页**: query `?cursor=xxx`,响应 `nextCursor` 为 null 时结束
- **错误码**:
  - 4001: 鉴权失败
  - 4002: 参数缺失
  - 4003: 资源不存在
  - 5001: 上游超时,可重试

之后涉及内部 API 的代码,Claude 会自动按这些约定写。

示例 3:带资源文件的 skill

skill 目录可以放其他文件,Claude 按需读取:

~/.claude/skills/
└── our-deployment/
    ├── SKILL.md            # 触发条件 + 入口指令
    ├── checklist.md        # 上线前 checklist
    └── rollback.md         # 回滚步骤

SKILL.md 里写「上线相关问题时,先读 checklist.md;回滚时读 rollback.md」。这样主上下文不会被一次性占满。

实用技巧

1. description 决定加载效果

  • ❌ 模糊:description: 关于 git 的
  • ✅ 具体:description: 写 git commit message 时使用,提交前清理 diff 时也用

2. skill 可以 "调用" agent

skill 指令里可以写"用 general-purpose agent 调研 X",形成组合拳。

3. 用 /skill 命令查看

> /skills

列出当前会话能用的所有 skill 和它们的描述,方便排查。

官方技能库与规范

Anthropic 开源了官方技能库 anthropics/skills:17 个可直接安装的 skill(docx / pdf / pptx / xlsx 文档处理、mcp-builder、webapp-testing、skill-creator 等),外加 spec/(Agent Skills 规范)和 template/(起步模板)。

装来用

官方库以 plugin marketplace 形式分发,在 Claude Code 里先注册再安装:

> /plugin marketplace add anthropics/skills
> /plugin install document-skills@anthropic-agent-skills
> /plugin install example-skills@anthropic-agent-skills

document-skills 是四个文档技能(docx / pdf / pptx / xlsx),example-skills 是其余示例。装完用自然语言即可触发,例如「用 PDF skill 提取 report.pdf 的表单字段」。

不想装插件也可以 clone 仓库,把单个 skill 目录拷进 ~/.claude/skills/ —— 格式和你手写的完全一样。

SKILL.md 规范要点

spec/ 定义了正式规范,frontmatter 核心几条:

| 字段 | 必填 | 约束 | | --- | --- | --- | | name | 是 | ≤64 字符,小写字母/数字/连字符,须与目录名一致 | | description | 是 | ≤1024 字符,写清「做什么 + 何时用」 | | license / compatibility / metadata / allowed-tools | 否 | 许可证、环境要求、自定义元数据、预授权工具 |

规范的灵魂是渐进披露(progressive disclosure),三层加载:

  1. 启动时只加载 name + description(约 100 token)
  2. 触发后才加载 SKILL.md 正文(建议 5000 token 以内,500 行以内)
  3. scripts/、references/、assets/ 里的文件按需读取

所以长内容要拆到引用文件里,别都塞进 SKILL.md —— 前面「示例 3」那种目录结构,正是官方推荐的写法。

官方内部实践的三条建议

Anthropic 在 lessons 一文里把内部 skill 归成九类(其中「产品验证」类收益最高),最值得抄的三条:

  1. 别写 Claude 本来就会的:官方原话是「复述默认行为的 skill,只增加上下文不增加价值」。skill 应该只装 Claude 靠自己推不出来的知识,也别把步骤写死到没有发挥空间。
  2. 维护一个 gotchas 段落:信号密度最高的内容 —— 每次 Claude 踩坑就补一条,skill 会越用越准。
  3. description 写给模型看,不写给人看:围绕「什么时候该触发」措辞。这与上面实用技巧第 1 条同源,官方给了背书。

分发上:小团队直接把 skill 提交进仓库 .claude/skills/;规模上去了再建内部 plugin marketplace,按需安装。

延伸阅读:

下一篇:Hooks →