第 7 章 · Skills —— 让 Agent 长本事

7.1 什么是 Skill

第 4 章讲的是工具——让 agent 能执行具体动作。这一章讲技能（Skill）——让 agent 知道"怎么干某类事"。

Anthropic 官方定义：

"Agent Skills are modular capabilities that extend Claude's functionality. Each Skill packages instructions, metadata, and optional resources (scripts, templates) that Claude uses automatically when relevant."
—— Agent Skills 文档

翻译：Skill 是模块化的能力包，里面有指令、元数据、可选资源（脚本、模板）。Claude 在相关场景下自动调用。

举个例子区分 Skill 和 Tool：

Tool：write_commit_message(diff) - 给定 diff，生成 commit message。每次都要 LLM 决定调。
Skill：/commit - 一整套"看 git status → 看 diff → 写 commit message → 提交"的流程指令。Claude 看到"提交代码"这种话，自动按这套流程走。

Tool 是单个动作，Skill 是一套方法论。Skill 里可以调多个 Tool。

7.2 Skill vs Tool vs Prompt 的边界

	Tool	Skill	Prompt
是什么	一个函数	一套指令 + 可选资源	一段文本
谁触发	LLM 自动调	LLM 自动 / 用户 `/skill-name` 触发	用户手写
粒度	单个动作	一套流程	任意
可复用性	单次调用	跨会话复用	一次性
例子	`read_file()`	`/commit` 提交代码	"帮我写 commit message"

Skill 处于 Tool 和 Prompt 之间——比 Tool 粒度大，比 Prompt 可复用性强。

7.3 Skill 文件结构

Skill 用文件系统组织，一个 Skill = 一个目录：

.claude/skills/
└── commit/
    ├── SKILL.md          # 主文件，必须
    └── templates/        # 可选资源
        └── commit-template.txt

SKILL.md 是核心，由两部分组成：YAML frontmatter + markdown 主体。

markdown

---
name: commit
description: 智能生成 commit message 并提交。当用户说"提交代码"、"commit"、"写 commit"时使用。
when_to_use: 用户想提交 git 代码时
allowed-tools:
  - Bash
  - Read
---

# Commit Skill

## 流程

1. 调 `Bash` 跑 `git status` 看变更
2. 调 `Bash` 跑 `git diff` 看具体改动
3. 根据改动写 commit message，格式：
   - 第一行：type: 简短描述（<50 字符）
   - 空行
   - 详细说明
   - type ∈ feat/fix/docs/refactor/test/chore
4. 调 `Bash` 执行 `git commit -m "..."`

## 注意

- 不要 commit 大文件
- 不要 commit .env / 密钥
- pre-commit hook 失败时不要 --no-verify

Frontmatter 关键字段：

name：技能名（slash command 名）
description：什么时候用——LLM 看这个决定要不要触发
when_to_use：补充描述
allowed-tools：这个 skill 能用哪些工具（权限缩小）

7.4 三层渐进式加载

Skill 系统有个聪明设计——渐进式加载（Progressive Disclosure），省 token：

层级	内容	加载时机	Token 成本
Level 1	Metadata（name + description）	始终加载	~100 tokens
Level 2	Instructions（SKILL.md 主体）	触发时加载	几百-几千 tokens
Level 3	Resources（脚本、模板）	按需加载	按需

LLM 平时只看到所有 skill 的 metadata（Level 1），知道"有哪些能力"。当某个 skill 被触发，才加载 SKILL.md 主体（Level 2）。主体里如果引用了 templates/xxx.txt，等到真要用时才加载这个文件（Level 3）。

好处：context 不会被一堆 skill 主体塞爆。100 个 skill 平时只占 1 万 tokens，触发哪个才加载哪个。

7.5 写一个自己的 Skill

实战：写一个"代码审查"skill。

步骤 1：建目录

bash

mkdir -p .claude/skills/code-review

步骤 2：写 SKILL.md

markdown

---
name: code-review
description: 审查当前 git diff 的代码，检查 bug、风格、安全、性能。当用户说"代码审查"、"review 代码"、"看看我的改动"时使用。
allowed-tools:
  - Bash
  - Read
---

# Code Review Skill

## 流程

1. `Bash: git diff HEAD` 获取未提交改动
2. `Bash: git diff --cached` 获取已暂存改动
3. 按以下维度审查：
   - **正确性**：逻辑 bug、边界条件、null 处理
   - **安全**：注入、XSS、密钥泄漏、不安全反序列化
   - **性能**：N+1 查询、不必要的循环、大对象拷贝
   - **可维护性**：命名、复杂度、注释
4. 输出格式：
   - 严重程度：🔴 阻塞 / 🟡 建议 / 🟢 优化
   - 文件:行号
   - 问题描述
   - 修复建议

## 注意

- 不要审查自动生成的代码
- 不要审查 vendor/ 目录
- 严重问题优先，轻微问题合并

步骤 3：用

在 Claude Code 里说"审查我的代码"——Claude 会自动触发这个 skill。

或者显式触发：/code-review。

7.6 Skill 生态

Claude Code 内置 skill

Claude Code 自带一些 skill，比如 /commit、/review-pr。可以参考它们的设计。

社区 skill 市场

ClawHub（OpenClaw 的 skill 市场）：跨平台 skill 共享，已有 5000+ skill。
awesome-claude-skills：GitHub 上的清单仓库。
oh-my-claudecode：Claude Code 的 skill 增强包。

跨平台兼容

Claude Code 的 skill 格式遵循 Anthropic Agent Skills 开放标准。同一个 skill 可以在：

claude.ai
Claude API
Claude Platform on AWS
Microsoft Foundry
Claude Code

里用。写一次到处跑。

7.7 Skill 设计的经验法则

description 写"什么时候用"：和 Tool 一样，LLM 全靠这个判断。
allowed-tools 收紧：skill 默认继承会话所有工具，但限制工具能降低误用风险。比如 /commit 不需要 WebSearch。
流程要具体：不要写"分析代码"这种空话，写"先跑 git diff，再看 N+1 查询"。
大 skill 拆小：一个 skill 处理一个场景。/code-review 和 /security-review 分开，不要混在一起。
用 resources 装大资源：检查清单、模板、规则文件放 templates/，按需加载，别塞 SKILL.md。

前人智慧 / Prior Art

本章讲了 Skills 的工程细节。Skills 是 2025 年 Agent 工程的重要新增--它解决"做事方法不能复用"的问题，这是 Prompt Engineering 和 MCP 都没覆盖的维度。

Anthropic Skills 的发布定位

Anthropic Agent Skills 文档把 Skills 定位为"模块化能力包"。这个定位的工程价值在：

"Each Skill packages instructions, metadata, and optional resources (scripts, templates) that Claude uses automatically when relevant."

关键短语 "uses automatically when relevant"--Skill 不是用户手动调，是模型根据 context 自动触发。这和 Custom GPT / Prompt Template 形成对比：

	Custom GPT	Prompt Template	Skill
触发	用户选 GPT	用户填模板	模型自动
复用	单会话	一次性	跨会话
资源	不带	不带	带 scripts / templates

Skills 的差异化在"自动触发 + 跨会话 + 带资源"。这三条组合让它成为 Agent 时代的"方法沉淀"机制。

渐进式加载的 Context Engineering 意义

本章 7.4 节讲的渐进式加载（Level 1 metadata / Level 2 SKILL.md / Level 3 resources）是 Context Engineering 的范本应用。

Anthropic Context Engineering 博客的核心命题："用最小高信号 token 集最大化期望结果"。Skills 的渐进式加载是这条命题的直接实现：

平时只加载 metadata（~100 tokens / skill）--最小常驻
触发时加载 SKILL.md（几百-几千 tokens）--按需加载
用到资源时才加载 templates（按需）--最深加载

100 个 skill 平时只占 1 万 tokens。如果把所有 SKILL.md 都常驻，会占 10-30 万 tokens，context 直接爆。渐进式加载让 Skills 系统可扩展。

Cursor rules 的演化启示

Cursor 的规则系统经历过一次大改：

旧版（2023）：.cursorrules 单文件
新版（2024+）：.cursor/rules/ 目录，每个文件带 frontmatter，可指定 globs 触发条件

新版的关键创新：按文件类型按需加载。编辑 *.tsx 才加载 React 规则，编辑 *.py 才加载 Python 规则。这和 Skills 的渐进式加载是同一个思路。

这种"按需加载"思路的工程根源是 Context Rot--规则越多，context 越满，模型表现越差。Cursor 通过按需加载把 context 控制在最小集。

Skills vs Custom GPT 的本质差异

Custom GPT（OpenAI 2023 推出）和 Skills 都叫"能力包"，但本质不同：

	Custom GPT	Skills
载体	OpenAI 平台账号	文件系统（git 可版本化）
触发	用户选 GPT	模型自动
资源	上传文件	scripts / templates 目录
跨平台	仅 OpenAI	跨 host（claude.ai / API / Claude Code / Foundry）
可审计	不能	能（进 git）

Custom GPT 是"产品功能"，Skills 是"开放标准"。这种差异决定了 Skills 更适合工程团队--可版本化、可审计、可跨平台。

SKILL.md 的 frontmatter 设计

本章 7.3 节的 SKILL.md frontmatter（name / description / when_to_use / allowed-tools）不是任意字段，每个都有工程意义：

name：slash command 名 + 触发关键词
description：模型决定何时触发的依据（最重要）
when_to_use：补充描述，给模型更多上下文
allowed-tools：权限收紧（skill 默认继承会话所有工具，但要限制）

这套字段设计和 Tool Schema 的字段（name / description / input_schema）是同源--都强调 description 决定"何时用"。这是 LLM 工程的一个普适原则：模型靠 description 决策，description 是核心信号。

allowed-tools 收紧的权限意义

本章 7.7 节法则 2"allowed-tools 收紧"是 Skill 安全的核心。默认情况下，skill 继承会话所有工具，但这会带来风险：

/commit skill 不需要 WebSearch -- 如果不收紧，模型可能在 commit 时乱搜网
/code-review skill 不需要 Bash 的 rm -- 如果不收紧，可能误删

allowed-tools 收紧的工程智慧：最小权限原则在 Skill 层的应用。和第 9 章 Runtime & Sandbox 的权限分级是同一个原则的不同层次实现。

Claude Code 内置 skill 的设计参考

本章 7.6 节提到 Claude Code 自带 /commit / /review-pr 等 skill。这些内置 skill 是 SKILL.md 设计的范本：

流程具体（"先 git status，再 git diff"）
allowed-tools 收紧（只 Bash + Read）
输出格式明确（type: 描述格式）
注意事项列明（不 commit .env）

写自己的 SKILL.md 时，参考这些内置 skill 的结构能少走弯路。

跨平台复用的开放标准价值

本章 7.6 节提到 Skills 跨平台（claude.ai / API / Claude Code / Foundry）。这种"写一次到处跑"的开放标准价值：

写一份 SKILL.md，多个 host 都能用
团队共享：进 git，所有人 clone 即用
社区市场：ClawHub 等 skill 市场能复用

这和 MCP 的"USB-C for tools"是同一个开放标准哲学。Anthropic 在 2024-2025 推的两个开放标准（MCP + Skills）共同构成了 Agent 工程的标准化基础设施。

Skill 是模块化能力包，比 Tool 粒度大，比 Prompt 可复用。
Skill = 一个目录 + SKILL.md（frontmatter + 主体）+ 可选资源。
渐进式加载省 token：metadata 始终加载，主体触发时加载，资源按需加载。
Skill 跨平台复用（claude.ai / API / Claude Code / Foundry）。
设计 5 法则：description 写场景、allowed-tools 收紧、流程具体、大 skill 拆小、大资源进 templates/。

下一章讲 Agent 评估与安全——怎么控制 agent 风险。

第 7 章 · Skills —— 让 Agent 长本事 ​

7.1 什么是 Skill ​

7.2 Skill vs Tool vs Prompt 的边界 ​

7.3 Skill 文件结构 ​

7.4 三层渐进式加载 ​

7.5 写一个自己的 Skill ​

7.6 Skill 生态 ​

Claude Code 内置 skill ​

社区 skill 市场 ​

跨平台兼容 ​

7.7 Skill 设计的经验法则 ​

前人智慧 / Prior Art ​

Anthropic Skills 的发布定位 ​

渐进式加载的 Context Engineering 意义 ​

Cursor rules 的演化启示 ​

Skills vs Custom GPT 的本质差异 ​

SKILL.md 的 frontmatter 设计 ​

allowed-tools 收紧的权限意义 ​

Claude Code 内置 skill 的设计参考 ​

跨平台复用的开放标准价值 ​