Agent开发完全实战指南(十一)Agent Skills

你给 Agent 攒了一身本事:一套 commit message 规范、一份周报模板、一段"处理 PDF 要先转版面再切块"的 SOP。问题是这些东西散落得到处都是——有的写在 CLAUDE.md 里,有的硬编码在 Go 代码里,有的干脆只在你脑子里。换个项目就得重抄一遍,工具一多上下文就爆,模型还经常"忘了"该按你的规矩来。

2025 年 10 月,Anthropic 推出 Agent Skills;同年 12 月它被开放成标准,OpenAI、Google、GitHub Copilot、Cursor 几周内相继跟进。这不是又一个框架,而是一个朴素到极致的约定:

一个 Skill,就是一个装着 SKILL.md 的文件夹。 把"怎么把这件事做对"打包成文件,让 Agent 需要时自己去读。

这一篇我们讲透 Skill 的本质和它最核心的设计——渐进式披露(progressive disclosure),然后用 Go 从零手搓一个 Skill 加载器,接到第 02 篇的 Agent 循环上,亲眼看它三级加载。


一、先说人话:Skill 到底是什么

一个 Skill 就是一个文件夹,长这样:

commit-message/
├── SKILL.md           # 必需:元数据(name + description)+ 操作说明
├── references/        # 可选:按需加载的深度资料
│   └── EXAMPLES.md
├── scripts/           # 可选:可执行脚本
└── assets/            # 可选:模板、样例文件

核心只有 SKILL.md,头部是 YAML frontmatter(name 和 description),下面是给模型看的操作说明。它装的不是"能力"本身,而是"程序性知识"——把一件事该怎么一步步做对,写成模型能读的说明书。

它和你已经会的两样东西是什么关系?一张表说清:

抽象 是什么 一句话
Tool(工具) 一个有类型输入输出的函数 做一个确定动作(读文件、发 HTTP)
MCP 连接外部系统的开放协议 提供访问(AI 世界的 USB-C 接口)
Skill 装着 SKILL.md 的文件夹 教模型把活儿做对的完整流程(步骤、格式、验收标准)

关键洞察:Tool 是"能做什么",MCP 是"能连到什么",Skill 是"该怎么做"。三者不是竞争,是三层。 一个 Slack 客服 Agent 往往三样都要:MCP 连上工单系统,Tool 执行创建工单,Skill 规定"什么样的问题该建单、回复用什么语气"。


二、核心机制:渐进式披露

Skill 真正的精髓不在文件夹,而在它怎么被加载。

先想清楚要解决的问题:上下文窗口是 Agent 的认知空间,塞满就退化(这就是第 04、06 篇反复出现的 lost-in-the-middle)。如果你有 100 个 Skill,把 100 份正文全塞进去,Agent 还没干活上下文就废了。

渐进式披露的答案是分三级、按需加载:

flowchart TD
    A["启动:扫描所有 skill
只读 name + description"] --> B{"来了个任务
有 skill 相关吗?"} B -->|"没有"| Z["直接回答,一个字节正文都不加载"] B -->|"有"| C["Activation:读那个 skill
的完整 SKILL.md 正文"] C --> D{"正文让我读
references 里的文件吗?"} D -->|"不需要"| E["按说明执行"] D -->|"需要"| F["Execution:只读用得上的
那个引用文件"] F --> E

三级各花多少钱,Anthropic 官方 17 个 skill 的实测很能说明问题:

级别 加载什么 上下文成本
Discovery(启动) 每个 skill 的 name + description 中位数约 80 token/skill(55–235)
Activation(命中) 那一个 skill 的 SKILL.md 正文 几百到上千 token,只在相关时
Execution(执行) 用得上的 references 文件 / 脚本输出 按需,其余永远躺在磁盘上 不花钱

关键洞察:这就是 Skill 能"装一屋子却不撑爆上下文"的原因——启动只装一份目录,正文和资料都等模型真正需要时才逐级取用。 打个比方:一个同事记得整本手册的目录,但没读任何一章;要用哪章时才翻到哪章。


三、Skill vs Tool vs MCP:到底该用哪个

Anthropic 官方用了个厨房比喻,很好记:MCP 给你一间专业厨房(接上食材和设备),Tool 是"切"这个动作,Skill 是这道菜的菜谱——告诉你在你这家店里该怎么做。

落到选型上:

你的问题是 用
要连一个外部系统(数据库 / GitHub / 内部 API),且跨会话、跨项目复用 MCP
要执行一个离散动作,一步就完 Tool
要让模型每次都用同样的高质量流程做一件需要判断的事 Skill
既要判断又要动作(绝大多数真实活儿) Skill 引用 Tool:Skill 给流程,Tool 给执行

一个决定性的技术差异是上下文占用方式:Tool 的声明每条消息都在上下文里(除非用动态工具搜索),而 Skill 靠渐进式披露,不相关时零占用。所以当你有大量领域知识要沉淀,又不想每次会话重讲一遍,Skill 是那个"装得多、平时不占地"的选择。


四、动手:用 Go 手搓一个渐进式 Skill 加载器

概念够了,动手。我们复用 第 02 篇 的 Agent 循环,把渐进式披露的三级做出来:Discovery 扫元数据注入系统提示,Activation / Execution 做成两个工具挂上去。完整代码在 code/11-skills/。

4.1 先看一个 Skill 长啥样

skills/commit-message/SKILL.md:

---
name: commit-message
description: 写规范的 Git commit message。当用户要提交代码、生成 commit 信息、整理本次改动说明时使用。
---

# 写一条规范的 Commit Message

按 Conventional Commits 规范产出,格式如下:
...
- 需要更多正反例时,读 `references/EXAMPLES.md`(只有需要时才读)。

注意最后那句——正文自己指路,把深度资料推迟到 Execution 级再加载。

4.2 第 1 级 Discovery:只读 frontmatter

启动时遍历 skills/,只解析 frontmatter,绝不读正文:

// 只解析 YAML frontmatter 的 name / description,正文一个字节都不读
func parseFrontmatter(path string) (name, desc string, ok bool) {
	raw, err := os.ReadFile(path)
	if err != nil {
		return "", "", false
	}
	text := string(raw)
	if !strings.HasPrefix(text, "---") {
		return "", "", false
	}
	rest := text[3:]
	end := strings.Index(rest, "\n---") // 第二道 --- 之前就是 frontmatter
	if end < 0 {
		return "", "", false
	}
	for _, line := range strings.Split(rest[:end], "\n") {
		k, v, found := strings.Cut(line, ":")
		if !found {
			continue
		}
		switch strings.TrimSpace(k) {
		case "name":
			name = strings.TrimSpace(v)
		case "description":
			desc = strings.TrimSpace(v)
		}
	}
	return name, desc, name != "" && desc != ""
}

把所有 name+description 拼成一份"目录",注入系统提示——这就是 Agent 启动时对 skill 的全部认知。

4.3 第 2、3 级:两个工具

Activation 和 Execution 各是一个工具,挂进第 02 篇那个 toolRegistry:

// Activation:读某个 skill 的完整正文
func loadSkill(args map[string]any) string {
	s := skillIndex[args["name"].(string)]
	body, _ := os.ReadFile(filepath.Join(s.Dir, "SKILL.md"))
	return string(body)
}

// Execution:读 skill 目录下的引用文件——注意挡住路径穿越
func readReference(args map[string]any) string {
	s := skillIndex[args["skill"].(string)]
	base, _ := filepath.Abs(s.Dir)
	target, _ := filepath.Abs(filepath.Join(s.Dir, args["path"].(string)))
	if !strings.HasPrefix(target, base+string(os.PathSeparator)) {
		return "错误:拒绝越界访问" // 挡掉 ../../etc/passwd
	}
	data, _ := os.ReadFile(target)
	return string(data)
}

模型在系统提示里看到目录,判断相关就调 load_skill 读正文,正文让它读引用它才调 read_reference。三级披露,全在这个循环里自然发生。

4.4 跑起来

cd code/11-skills
go run .

你会先看到 Discovery 的账本,再看到模型逐级取用:

发现 2 个 skill;目录占 280 字节,全部正文占 1728 字节——启动只装目录,省下 1448 字节的上下文。

可用 skills(注入系统提示的目录):
- commit-message: 写规范的 Git commit message。当用户要提交代码...
- weekly-report: 把零散的工作记录整理成结构化周报...

用户:帮我根据这次改动写一条 commit message:把 Qdrant 的 upsert 从 POST 改成了 PUT,修好了写入失败
  [调用] load_skill({"name":"commit-message"})
  [结果] # 写一条规范的 Commit Message  按 Conventional Commits…

Agent:
fix(qdrant): upsert 改用 PUT 而非 POST

POST /collections/{}/points 会命中「按 ids 删除」的处理器,导致写入失败。

看那行"省下 1448 字节"——skill 只有两个就省了 84%,真实场景几十个 skill 时,这就是"能不能装得下"的分水岭。 模型没有被灌一堆无关正文,而是自己判断、自己去读那一个相关的。


五、写好一个 Skill 的最佳实践

手搓完你就懂了,写 Skill 的功夫全在几个地方:

一句话记住:把 SKILL.md 正文当成"电梯演讲",把 references 当成"附录",让模型像查手册一样按需翻。


六、安全:Skill 是会被执行的代码

别被"就是几个 markdown 文件"骗了。Skill 的正文是模型会照着做的指令,scripts/ 是会被执行的代码——它同时是一条供应链和一个注入面。 这正是第 10 篇讲的攻击面在 Skill 形态下的延续。

三个必须守住的点:


七、决策指南与小结

什么时候该掏出 Skill?一张决策表收尾:

情况 怎么办
一句话就能说清、且每次都一样 直接写进 system prompt,别做 skill
一段需要判断的多步流程,要反复复用 做成 Skill
只是要一个确定动作 写个 Tool
要接外部系统、跨项目共享 起个 MCP server
既要流程判断又要执行动作 Skill 引用 Tool(覆盖绝大多数真实活儿)

这一篇的收获:

至此,从第 01 篇的"一次 API 调用"到这里的"把能力打包复用",你已经走完了 Agent 工程的主干。Skill 是这套主干上最新、也最能立刻上手的一块拼图——回到你自己的项目,挑一个你反复向模型交代的流程,把它写成第一个 SKILL.md 吧。


参考资料

资料 来源
Anthropic:Agent Skills 官方文档 docs.anthropic.com/en/docs/agents/skills
Anthropic:Equipping agents for the real world with Agent Skills anthropic.com/engineering
渐进式披露作为系统设计模式(含 token 实测) newsletter.swirlai.com/p/agent-skills-progressive-disclosure
Skills vs MCP vs Tools:该用哪个 towardsdatascience.com/what-is-agent-skills-beyond-claude
Agent Skills for LLMs:架构、获取与安全综述 arxiv.org/abs/2602.12430
Agent Skills 开放标准与生态 agentskills.io