Agent Skill 从使用到原理

前置阅读：从LLM到Agent Skill 里已经解释了 Skill 在整条 AI 技术栈中的位置。
这篇文章把视角拉近，只聊 Agent Skill 本身——它长什么样、怎么用、以及底层是怎么跑起来的。

一、先说结论：Skill 到底是什么

一句话版本：

Agent Skill 就是一个文件夹。 里面装着教 Agent"在某类任务里怎么干活"的说明书、脚本和资源。Agent 在需要时会自己翻这本说明书。

再展开一点：

• 它不是一个新模型，也不是一个插件系统。
• 它的载体就是一个普通的目录，核心文件叫 SKILL.md，是纯 Markdown。
• 它的"激活"完全由 Agent 自己根据任务判断，不需要你手动"打开"。

所以 Skill 的本质是：把领域知识和工作流，以 Agent 能读懂的方式打包起来。

二、为什么需要 Skill（一句话回顾）

简单说：

• Prompt 一变长就膨胀、互相干扰、费 token。
• MCP/Tool 解决了"动作"问题，但没解决"该怎么做"的问题。
• 我们需要一种按需加载、可复用、可组合的知识打包方式。

Skill 就是这个答案。

三、Skill 长什么样

一个典型的 Skill 目录大致是这样：

my-skill/
├── SKILL.md              # 必需，技能入口
├── reference.md          # 可选，详细参考
├── examples/             # 可选，示例
│   └── sample.py
├── scripts/              # 可选，可执行脚本
│   └── build.sh
└── assets/               # 可选，模板、图标等
    └── template.docx

SKILL.md 的结构

SKILL.md 开头是一段 YAML Frontmatter（元信息），后面是正文说明。大致如下：

---
name: pdf-form-filler
description: 用于读取、填写和导出 PDF 表单。当用户要求处理 .pdf 表单、发票、合同时使用。
---

# PDF Form Filler

## 什么时候用这个 Skill

- 用户上传 PDF 并要求填写、签署或导出字段时
- 用户询问"这个表单怎么填"时

## 工作流程

1. 使用 scripts/extract_fields.py 提取字段
2. 和用户确认每个字段的值
3. 使用 scripts/fill.py 回写 PDF
   ...

关键点：

• name 和 description 是"路标"——Agent 就是靠它们在一堆 Skill 里挑出相关那几个。
• 正文是"专家手册"——只有当 Skill 被选中后，正文才会被读进 Context。

四、怎么用（使用视角）

1. 在 Claude 客户端里用

在 Claude.ai / Claude Desktop 里打开 Skills 开关，它自带一些官方 Skill（PPT、Excel、Word、PDF 等）。聊天时你不需要说"请用 xxx Skill"，Agent 会自己判断。

你还可以把自己写的 Skill 扔到对应目录里，它会自动被发现。

2. 在 Claude Code / VS Code 插件里用

• 项目级：把 Skill 放在 .claude/skills/xxx/SKILL.md，团队通过 Git 共享。
• 用户级：放在 ~/.claude/skills/ 下，所有项目都能用。
• 市场级：通过 anthropics/skills 之类的 marketplace 以插件形式安装。

3. 在 API / SDK 里用

通过 Messages API 或 Claude Agent SDK 把 Skill 目录挂进去，通常需要配合 Code Execution Tool（代码执行沙箱），Skill 里的脚本才有地方跑。

4. 最简单的"写一个 Skill"流程

1. 新建一个文件夹。
2. 写一个 SKILL.md，顶部加 name 和 description。
3. 放进上面提到的某个目录。
4. 重启 Agent / 重新加载插件。
5. 发一条相关任务的消息，观察它有没有自动命中。

官方还提供了一个"skill-creator"Skill——你可以让 Claude 自己采访你、帮你生成 Skill 文件夹，完全不用手写 YAML。

五、底层原理：Skill 到底是怎么跑起来的

这部分是"原理"视角，核心就一个关键词：渐进式披露（Progressive Disclosure）。

Skill 的加载不是一次性把整个文件夹塞给模型，而是分三层按需展开：

Level 1：元信息层（总是加载）

Agent 启动时，所有可用 Skill 的 name + description 会作为一份"目录索引"拼进 System Prompt。

• 成本极低：一个 Skill 也就几十个 token。
• 它让模型"知道有这回事"，但还没读正文。

Level 2：正文层（按需加载）

当模型在某轮推理中判断"这个任务命中了某个 Skill"，它会发出一个类似"读文件"的动作，把对应的 SKILL.md 正文读进 Context。

• 此时 Skill 的工作流、注意事项才真正进入模型视野。
• 多个 Skill 可以同时命中并叠加。

Level 3：资源层（显式调用）

Skill 目录里的脚本、模板、参考文档等，只有当 SKILL.md 明确指示"去读 reference.md"或者"执行 scripts/xxx.py"时，才会被加载或执行。

• 脚本通过 Code Execution Tool 在沙箱里跑。
• 这一层是 Skill 比纯 Prompt 强得多的原因：能调用代码，就能做确定性强的事（比如精确计算、文件格式转换）。

为什么这么设计

对比一下"把所有知识塞 System Prompt"的做法：

维度	传统 System Prompt	Agent Skill
Token 消耗	一直占用，高	按需加载，低
注意力聚焦	容易被无关内容稀释	只在相关任务出现时引入
可组合性	需要手工拼接	多个 Skill 自动叠加
可复用	要复制粘贴	一个文件夹到处可用
能执行代码	不行	可以（通过 scripts/）

一句话：渐进式披露 = 用"索引 + 按需读取 + 代码执行"模仿人类"查手册"的方式。

六、Skill 与 Tool / MCP 的关系

很多人容易把 Skill、Tool、MCP 混在一起，其实三者在不同层。

抽象层	关注	举例
Tool	一个原子动作	read_file、http_get
MCP	一组工具/资源/提示词的接入协议	一个 MCP Server 暴露若干 Tool
Skill	一类任务的做法与知识	“如何按公司品牌规范做 PPT”

再直白点：

• MCP 告诉 Agent"你有哪些手脚可用"。
• Skill 告诉 Agent"遇到这类活该怎么动手"。

一个 Skill 内部完全可以调用 MCP 提供的 Tool；反过来，MCP 也可能会以资源的形式暴露 Skill。二者是互补关系，不是替代。

七、写好一个 Skill 的几个经验

1. description 要写得像搜索引擎关键词：直接点明"什么时候该用我"，最好带上典型触发语。Agent 命中与否，几乎全靠它。
2. SKILL.md 正文要"薄"：正文只写"决策、流程、注意事项"，细节塞到 reference.md；能用脚本就别让模型自己算。
3. 拆而不是合：与其写一个大而全的 Skill，不如拆成多个小 Skill，让 Agent 按需组合。
4. 把确定性的事交给代码：凡是能写脚本做的（正则、解析、计算、格式转换），都通过 scripts/ 跑，不要让模型推理。
5. 写清楚"不要做什么"：Skill 不仅告诉 Agent 怎么做，也要划红线——哪些步骤必须人工确认、哪些动作不可逆。

八、小结

从使用到原理，一条线串起来：

1. 形式：Skill 就是一个带 SKILL.md 的文件夹。
2. 分发：通过项目目录、用户目录、marketplace、API 都能用。
3. 激活：Agent 根据 description 自动命中，不需要手动开启。
4. 加载：采用渐进式披露——先索引，再读正文，最后执行脚本。
5. 定位：Skill 关心的是"怎么做这类任务"，与 Tool / MCP 的"能做什么动作"互补。
6. 未来：随着 Agent 越来越长寿、越做越复杂，Skill 几乎注定会成为 Agent 侧的"包管理器"——像 npm、pip 一样把能力沉淀下来、共享出去。