· Agent Skills 实用指南

这篇笔记整理了 Agent Skills 的目录结构、加载方式和三个配置示例。可以先选一个重复任务，再用文中的 SKILL.md / reference.md 模板调整。
适合人群：会用 AI 写代码/写文档，但受够了「每次都要重新交代一遍要求」的开发者与团队。
预计阅读：15 分钟｜难度：入门

一、从一个真实的痛点说起#

你大概率经历过这个循环：

第 1 次让 AI 写会议纪要，你洋洋洒洒写了 800 字要求：「要有背景、决策、待办，待办要有负责人和截止时间……」，效果不错；
第 2 次，你翻聊天记录把那 800 字复制过来，改了改；
第 20 次，你已经懒得找了，随手打一句「帮我总结下这段会议」，于是 AI 又变回那个「聪明但随性的职场小白」，输出格式全靠心情。

问题不在于模型不够强，而在于：你的方法论没有被沉淀下来，它只存在于某一条聊天记录里。

Agent Skills 就是为了解决这件事而生的。

二、Agent Skills 是什么#

2025 年 10 月 16 日，Anthropic 正式推出 Agent Skills。最初它的定位相当克制——只是用来提升 Claude 在特定任务上的表现。但大家很快发现这套设计太好用了，国外主流 IDE 陆续跟进支持，于是 Anthropic 做出了一个重要决定：将 Agent Skills 发布为开放标准，支持跨平台、跨产品复用。

这意味着它已经超越单一产品的范畴，正在演变为 AI Agent 领域的一个通用设计模式。

一句话定义#

Agent Skills = 给 AI 配的一套「固定招式 / 标准操作流程（SOP）」。

每个技能都是一个模块化文件夹，包含三部分：

组成部分	作用	举例
元数据	让 AI 知道「有这个技能」以及「什么时候该用它」	YAML 里的 `name` / `description`
指令	具体的工作流程、规范、输出格式约束	`SKILL.md` 正文
资源（可选）	规则手册、模板、脚本等按需取用的材料	`reference.md`、脚本文件

官方给出的三大核心价值是：专精、减少重复、整合能力。

（图：Agent Skills 的价值 —— 原图待补）

Skill 和长 Prompt 的区别#

不是。每次都把一大段 prompt 塞给模型，有三个绕不开的成本：

重复成本：每次都要重写一遍「协作协议」；
稳定性成本：Prompt 越密，模型越容易忽略其中的关键约束；
Token 成本：尤其是你还要把示例、流程、模板全部塞进去的时候。

Agent Skills 用**「先触发，再加载」**的分层机制解决了这个三角难题。

三、核心机制：三级渐进式加载#

Skills 不需要预先把所有内容灌进上下文，而是按需、分阶段加载：

级别	加载时机	加载内容
L1 元数据	始终（启动时）	YAML 前置元数据中的 `name` 和 `description`
L2 指令	技能被触发时	`SKILL.md` 正文：流程、最佳实践、约束
L3 资源	按需（真正引用时）	同目录下的 `reference.md`、模板、脚本等

这个设计的关键收益是：你可以安装很多技能而不撑爆上下文，因为平时只有几十个字的 description 在上下文里；只有当用户请求与描述匹配时，完整指令才会被读取进来。

因此有一条铁律： description 写得越具体，Skill 越容易被正确触发。

四、模板 ①：SKILL.md 通用骨架#

一个 Skill 的最低要求只有两条：

一个目录（技能名）
目录里一个必须存在且大小写敏感的文件：SKILL.md

把下面这段存成 SKILL.md，就是一个可运行的 Skill 骨架：

1
---
2
name: 你的技能名称
3
description: 简要描述此技能的功能以及何时使用它
4
---
5

6
# 你的技能名称
7

8
## Input（缺一项先问）
9
- 必需输入 1：<说明>
10
- 必需输入 2：<说明>
11

12
## Output（固定结构）
13
- 模块 A：<字段要求>
14
- 模块 B：<字段要求>
15

16
## Procedure
17
1. 判断信息是否足够；不足先问 N 个最关键的问题（别猜）
18
2. <核心步骤>
19
3. <收尾步骤>
20

21
## Constraints
22
- <硬约束 1，例如：严禁臆测未覆盖的规则>
23
- <硬约束 2，例如：缺失字段标注 UNKNOWN>
24

25
## Acceptance
26
- <可验收标准，例如：输出可直接进项目文档库，无需二次整理>

写 description 的两个技巧：

不只写「是什么」，要写**「什么时候用」**：当用户提供会议聊天/记录并要求提供摘要时使用；
可以显式声明技能间的跳转关系：如果提到成本/费用/报销，请调用费用报销技能。

五、实战：在 CodeBuddy 中配置两个 Skill#

腾讯云代码助手 CodeBuddy 已支持 Agent Skills，下面用一个完整案例走一遍。

5.1 目录结构#

1
.codebuddy/skills/
2
  meeting-minutes/          # 负责把会议对话变成结构化纪要
3
    SKILL.md
4
  expense-reimbursement/    # 负责把「报销标准/流程」固化成可复用规则
5
    SKILL.md
6
    reference.md

（图：目录结构 —— 原图待补）

5.2 模板 ②：会议纪要 Skill（项目文档版）#

输出结构按「能直接贴进飞书 / Confluence / 语雀」的标准设计。

.codebuddy/skills/meeting-minutes/SKILL.md：

1
---
2
name: meeting-minutes
3
description: 将会议记录总结成项目风格的会议纪要文档（背景、决策、行动项目、风险）。当用户提供会议聊天/记录并要求提供摘要时使用。如果提到成本/费用/报销，请调用费用报销技能。
4
---
5

6
# Meeting Minutes（项目会议纪要）
7

8
## Input（缺一项先问）
9
- 会议文本：聊天记录/录音转写/要点
10
- 背景：项目名、参与方、会议目标（可选）
11
- 输出偏好：中文/英文
12

13
## Output（固定结构｜项目文档版）
14
- 背景与目标（Background & Goals）
15
- 结论摘要（Executive Summary，≤10 行）
16
- 决策（Decisions：事项 | 结论 | 影响范围）
17
- 待办（Action Items：事项 | Owner | Deadline | 风险/依赖）
18
- 未决问题（Open Questions）
19
- 风险与依赖（Risks & Dependencies）
20
- 费用/报销（若涉及）：费用项 | 是否可报 | 标准/上限 | 需要材料 | 下一步
21

22
## Procedure
23
1. 判断信息是否足够；不足先问 3 个最关键问题（别猜）
24
2. 生成纪要（按 Output 结构）
25
3. 检测是否出现费用/报销/预算相关内容
26
4. 若出现：调用 expense-reimbursement，并把结果写入「费用/报销」小节
27

28
## Acceptance
29
- 纪要可以直接进项目文档库（不用二次整理）
30
- 待办必须包含 Owner 与 Deadline；缺失则标注 UNKNOWN 并在末尾列出追问清单

5.3 模板 ③：报销规则 Skill（SKILL.md + reference.md）#

这一类 Skill 的精髓是：把「规则」从「指令」里剥离出去。

SKILL.md 只负责流程与输出格式（永远加载的部分）；
reference.md 存放具体规则细节（命中后才读取，改制度不用动流程）。

这正是 L3 级资源加载的典型用法。

.codebuddy/skills/expense-reimbursement/SKILL.md：

1
---
2
name: expense-reimbursement
3
description: 从 `reference.md` 提供可执行的报销规则与工作流程。当用户询问报销标准、所需材料、审批步骤，或会议纪要提及费用/预算/报销时使用。
4
---
5

6
# Expense Reimbursement（报销流程与标准｜可执行版）
7

8
## Input（缺一项先问）
9
- 费用类型：差旅/餐饮/采购/招待/其他
10
- 金额：<数字 + 币种>（如果用户没给，必须追问）
11
- 发生时间：<日期区间>（可选，但影响票据/时限规则）
12
- 是否预审批：有/无/不确定
13
- 当前目的：问标准 / 走流程 / 补材料 / 解释被驳回原因
14

15
## Reference
16
- 必须读取并遵循同目录下 `reference.md`（公司/组织的可执行规则）
17

18
## Output（必须可执行）
19
- 是否可报销：YES/NO/NEED_MORE_INFO
20
- 适用标准：上限/比例/例外条件（引用 `reference.md` 的条目）
21
- 审批链：谁发起 → 谁审批 → 谁归档（按金额/类型分支）
22
- 材料清单：发票/行程单/支付截图/对账单/会议纪要等（按类型分支）
23
- 常见驳回原因：与规避建议（对应规则条目）
24

25
## Constraints
26
- 严禁臆测政策：`reference.md` 未覆盖时输出 NEED_MORE_INFO，并列出需要补充的规则来源/字段
27
- 输出里必须标注引用到的规则段落标题/编号（如果你在 `reference.md` 里提供了）

.codebuddy/skills/expense-reimbursement/reference.md（模板，把占位符替换成你所在组织的真实规则）：

1
# Reimbursement Policy Reference（示例模板）
2

3
> 说明：以下为演示用占位规则，不代表任何真实公司的制度。
4

5
## 全局规则
6
- 报销时限：自发生日起 <= D 天内提交（D = <填数字>）
7
- 发票要求：<电子/纸质>；抬头/税号要求：<填>
8

9
## 费用类型与标准
10
### 差旅
11
- 交通：<可报/不可报>；舱位/席别限制：<填>
12
- 住宿：上限 = <金额或 T1> / 晚；城市等级差异：<填>
13
- 餐补：<填>
14

15
### 餐饮
16
- 人均上限 = <金额或 T2>
17
- 必备材料：发票 + <用餐人员/事由> 说明
18

19
### 采购
20
- 单笔金额阈值：T1/T2/T3（你自行定义）
21
- 是否需要比价/合同：<填>
22

23
## 审批链（示例分支）
24
- 金额 <= T1：发起人 → 直属主管 → 财务
25
- T1 < 金额 <= T2：发起人 → 直属主管 → 部门负责人 → 财务
26
- 金额 > T2：发起人 → 直属主管 → 部门负责人 → 负责人/VP → 财务
27

28
## 材料清单
29
- 通用：发票、支付凭证、事由说明
30
- 差旅：行程单/登机牌/酒店订单/出差审批（如需）
31
- 采购：报价单/合同/验收单（如需）
32

33
## 常见驳回原因
34
- 发票信息不合规
35
- 缺少审批或审批链不完整
36
- 超标且无例外说明

写 reference.md 的四条硬要求（否则它会退化成「建议」而不是「规则」）：

费用类型 → 标准 / 上限 / 不可报情况

金额阈值 → 审批链分支

材料清单（按类型）

例外与常见驳回原因（这部分最能减少来回追问）

担心敏感信息？把金额阈值写成区间占位符（如 T1/T2/T3）即可，但要保证逻辑分支完整。

5.4 验证 Skill 是否生效#

在 CodeBuddy 对话框中输入：

1
list skills

预期：能看到可用 skills 列表，其中至少包含你刚配置的两个技能。

5.5 跑一次完整触发#

把下面这段直接丢进对话框（含一段模拟会议聊天）：

1
请把下面的会议聊天整理成项目会议纪要，输出需包含：背景与目标、结论摘要、决策、待办（含 Owner/Deadline）、风险与依赖。
2

3
老张：好，会议现在开始，我们这次会议主要是商量下办公室环境调整的事。
4
小王：老张，咱们休息区那台咖啡机最近老出毛病，是不是得找人修修？
5
老张：那个我已经报修了，师傅明天下午过来，大家先克服一下。
6
大李：还有个事，咱们门口那几盆发财树好像快枯了，谁负责浇水啊？
7
小王：哎呦，最近太忙给忘了，以后我每周一和周四固定去浇一下吧。
8
大李：行，那这事儿就交给你了。另外，咱们这学期的团建是不是该准备了？
9
老张：对，大家有什么想法吗？
10
小王：我想去玩剧本杀，最近新开了一家店口碑不错。
11
大李：剧本杀太烧脑了，我建议去郊区搞个露营烧烤，大家能彻底放松下。
12
老张：露营听起来不错。但这周天气预报说有雨，咱们先待定吧。
13
老张：小王你先去调研下剧本杀和露营的具体地点，咱们下周一再定最终方案。
14
大李：没问题，那今天就先这样。

怎么确认 Skill 被加载了？ 优先查看工具的加载提示或调用记录。输出里出现「决策 / 待办 / 风险与依赖」等栏目，只能说明格式符合预期，不能单凭这一点确认触发成功。

六、Agent Skills 与 MCP 的区别#

一句话讲清楚：

Skills 管「怎么做」（流程 / 规范 / 模板），MCP 管「用什么做」（外部工具 / 数据的接入与调用）。

维度	Agent Skills	MCP
本质	工作流 / 规则 / 模板（行为规范）	工具与数据接入协议（能力接口）
重点	让输出「按你想要的方式」稳定产出	让模型「拿到数据、用上工具」
没有它会怎样	AI 每次写法不一、口径飘、难复用	AI 只能凭已有上下文「猜」，无法实时查 / 调
典型产物	`SKILL.md` 里的触发条件、约束、步骤、输出格式	一组可调用的 tools（查询、检索、执行动作等）

什么时候用哪个#

你想要「每次都按这个格式写、按这个流程做」→ 用 Skills
你需要「去某个系统 / 知识库拿数据、调用某个工具」→ 用 MCP
最强组合：Skills 负责指挥流程，MCP 负责提供手和眼睛

例如「报销技能」规定：先问清字段 → 再用 MCP 去查制度 / 单据状态 → 最后按模板输出可执行清单。

七、让 Skill 更稳定的 6 条工程建议#

踩过坑之后总结的 checklist，写新 Skill 时逐条对照：

description 写「何时用」而非只写「是什么」——它是唯一的常驻上下文，决定触发率。
输入缺项先问，而不是猜——在 Input 里明确列出「必问项」（如报销必须追问金额），比事后返工便宜得多。
输出结构要固定到字段级——不要只写「待办」，要写「待办：事项 | Owner | Deadline | 风险/依赖」。
缺失信息显式标注 UNKNOWN——并在文末附「追问清单」，避免模型编造同时保留可推进性。
规则外置到 reference.md，并写明「严禁臆测」——reference.md 未覆盖时输出 NEED_MORE_INFO，这是规则类 Skill 可信度的底线。
敏感数值用占位符——T1/T2/T3 这类区间占位符既保护敏感信息，又能保留完整逻辑分支。

音乐