08 - Agent Skill：给 Agent 写一份“说明书“

这是"从 LLM 到 Agent Skill"系列的最后一篇。上一篇我们讲了 Agent 能自主干活儿——但它怎么知道在每个场景下该怎么干？比如，"做个 PPT"和"帮我修 Bug"是截然不同的任务，Agent 怎么切换工作模式？答案就是 Agent Skill。

一、Agent 的知识盲区

Agent 很强大，但它有一个根本问题：

Agent 不知道你具体要它怎么干活。

你说"帮我分析这份数据"，它可以分析。但——

• 你的分析习惯是什么？先画图还是先算统计量？

• 你期望的输出格式是什么？Excel？Markdown 表格？PPT？

• 有哪些坑它不应该踩？哪些错误是常见但可避免的？

这些"领域知识"不在模型参数里，也不能全写到 System Prompt 里（太长了，浪费 Token）。

你需要一个更精细的机制——Agent Skill。

二、Agent Skill 是什么？

Agent Skill（智能体技能）本质上是为 Agent 编写的一份 Markdown 说明书。它包含了特定场景下的工作步骤、规则约束、输出格式和示例。

一个 Agent Skill 包含两个层次：

┌─────────────────────────────┐ │ 元数据层（Metadata） │ │ │ │ - name: 技能名称 │ │ - description: 一句话描述 │ │ - 触发条件 / 适用场景 │ │ │ │ 作用：让系统知道"有这个技能" │ │ 以及"什么时候该用" │ ├─────────────────────────────┤ │ 指令层（Instructions） │ │ │ │ - 详细步骤（Step by Step） │ │ - 规则约束（Do / Don't） │ │ - 输出格式要求 │ │ - 示例（Examples） │ │ - 边界情况处理 │ │ │ │ 作用：Agent 真正干活时 │ │ 参照的"操作手册" │ └─────────────────────────────┘

三、一个具体例子："出门清单" Skill

假设你希望 Agent 在你说"明天要出门"时，自动帮你生成一份出门检查清单。你可以给 Agent 写这样一个 Skill：

--- name: going-out-checklist description: 当用户提到要出门、旅行、出差时，自动生成出门 前的物品检查清单 --- ​ # 出门清单生成技能 ​ ## 步骤 ​ 1. 询问用户的出门类型（日常出门 / 短途旅行 / 长途出差） 2. 询问目的地和预计时长 3. 查询目的地当天天气（调用天气工具） 4. 根据天气和出门类型，生成分类物品清单： - 必备类（手机、钥匙、钱包） - 天气类（雨伞 / 防晒 / 外套） - 行程类（充电宝、证件、换洗衣物） 5. 以 Markdown 复选框格式输出，方便用户核对 ​ ## 规则 ​ - 不要询问用户已经提到的信息 - 清单按类别分组，每类不超过 8 项 - 如果天气预报有雨，务必提醒带雨具 ​ ## 输出格式 ​ ### ☑️ 出门清单 - [ ] 手机 - [ ] 钥匙 - [ ] 钱包 ……

有了这个 Skill，下次你随口说"明天要出差去上海"，Agent 就会自动加载"出门清单"技能，按步骤引导你、查天气、生成清单。

你不需要每次重新告诉它该怎么做。

四、Agent Skill 和 System Prompt 有什么区别？

这是一个非常关键的区分：

用一句话总结：

System Prompt 定义了"你是谁"，Agent Skill 定义了"遇到这件事该怎么做"。

五、渐进式披露机制：为什么 Skill 能节省 Token？

这是 Agent Skill 最精妙的设计——渐进式披露（Progressive Disclosure）。

5.1 传统做法的问题

如果所有技能的完整内容都放在 System Prompt 里：

• 假设你有 50 个 Skill，每个 500 字

• System Prompt 膨胀 25,000 字

• 每次对话都要带上——无论你问的是"帮我写代码"还是"今晚吃什么"

大量 Token 被浪费在与当前任务无关的指令上。

5.2 Agent Skill 的做法

Agent 启动 │ ▼ 只加载所有 Skill 的【元数据层】（名称 + 一句话描述） │ ← 占用 Token 极少，几十个 Skill 不过千字 │ ▼ 用户提问："帮我写一份项目计划" │ ▼ Agent 扫描元数据 → 发现有一个 "project-planning" Skill 可能相关 │ ▼ Agent 读取该 Skill 的【指令层】→ 按步骤执行 │ ← 其他 49 个 Skill 的指令层压根没加载

这就是渐进式披露：

不需要的时候，Skill 只是一个名字（元数据）。需要的时候，才展开完整的"说明书"（指令层）。

这解决了 System Prompt 无法解决的核心矛盾：既想给模型足够多的场景知识，又不想让 Context 被无关信息撑爆。

六、Agent Skill 的工程实现

以 Claude Code 为例，Agent Skill 需要遵循特定的规范：

6.1 目录结构

skills/ ├── going-out-checklist/ │ └── skill.md ← 必须叫 skill.md │ ├── project-planning/ │ └── skill.md │ └── daily-report/ └── skill.md

6.2 skill.md 的文件规范

--- name: my-skill-name description: 一句话说明这个技能做什么、何时触发 --- ​ 具体指令内容……

关键约束：

• 文件名必须是skill.md

• 每个 Skill 一个独立文件夹

• 必须有 frontmatter 元数据（name和description）

• 元数据以下的部分是具体指令，按需加载

七、Agent Skill 的价值

7.1 对用户

• 可复用：写好一次，每次自动生效

• 可共享：社区可以互相分享 Skill（就像分享代码）

• 可组合：多个 Skill 配合使用，覆盖更复杂场景

7.2 对开发者

• 可维护：每个场景独立一个文件，增删改不影响其他 Skill

• 可测试：每个 Skill 可以单独验证效果

• Token 高效：渐进式披露保证了 Token 消耗的可控

7.3 对生态

Agent Skill 正在催生一种新的生态模式：Skill 市场。

就像 VS Code 的插件市场一样，未来可能会有 AI 的 Agent Skill 市场——你不是在安装软件，而是在安装"AI 的工作方法"。

八、总结

1. Agent Skill 是为 Agent 编写的 Markdown 说明书，包含元数据层（名称/描述）和指令层（步骤/规则/示例）。

2. Agent Skill 和 System Prompt 的核心区别：System Prompt 全局通用且每次全量加载，Agent Skill 按场景拆分且按需加载。

3. 渐进式披露是 Agent Skill 最精妙的设计——不需要时不占 Token，需要时再展开。

4. Agent Skill 让 AI 从"通用助手"进化为"可编程的专业工具"。

九、全系列回顾

至此，"从 LLM 到 Agent Skill"八篇系列全部完结。回顾一下这条知识链：

LLM（文字接龙引擎） ↓ 需要把文字翻译成数字 Token + Tokenizer（文本最小单元） ↓ 需要让模型"记住"对话 Context + Context Window（临时记忆体） ↓ 需要给模型下指令 Prompt（System + User） ↓ 需要让模型连接外部世界 Tool（函数调用） ↓ 需要统一工具接入标准 MCP（Type-C 协议） ↓ 需要让模型自主干活 Agent（Think → Act → Observe 循环） ↓ 需要给模型写场景化说明书 Agent Skill（渐进式按需加载）

每一层都是为上一层"补短板"：

• LLM 只会接龙 → Tokenizer 让它读得懂文字

• 模型没有记忆 → Context 给它"纸条"

• 指令太粗糙 → Prompt 体系分层控制

• 模型不了解外部世界 → Tool 给它感官

• 工具标准不统一 → MCP 统一接口

• 问答太被动 → Agent 赋予自主性

• 场景知识太庞大 → Agent Skill 实现按需加载

希望这个系列能帮你建立起对 AI 技术栈的系统性认知。

本系列文章：

1. LLM 大语言模型

2. Token 与 Tokenizer

3. Context 与 Context Window

4. Prompt 提示词

5. Tool 工具调用

6. MCP 模型上下文协议

7. Agent 智能体

8. Agent Skill← 你在这里（全系列完结）