本书作者：测试开发刚哥，文章版权归个人所有，未经授权请勿转载。
Agent Skills 的发展简史
Agent Skills 的出现，其实是 AI 能力组织方式自然演进的结果。
早期的大模型应用主要靠提示词工程，把任务规则、流程说明、输出格式全部写进 System Prompt。这种方式简单直接，但提示词越写越长，上下文窗口被大量占用，关键指令容易被淹没，而且很难在不同项目之间复用。
随后 Function Calling 和工具调用逐渐普及，模型开始能够调用搜索、代码执行、数据库查询等外部能力。但这更多解决的是"能不能调用工具"的问题，还没有很好地回答"应该按什么流程、遵循什么标准、产出什么格式"的问题。
2025 年 10 月，Anthropic 在 Claude Code 中首次推出 Agent Skills 能力，把可复用的任务流程封装成以 SKILL.md 为核心的文件夹结构。 同年 12 月 18 日，Anthropic 将 Agent Skills 规范作为开放标准发布，并开源官方技能库，随后 OpenAI Codex、GitHub Copilot、VS Code、Cursor 等产品陆续跟进支持。 到 2026 年，Agent Skills 已经从单一产品的功能扩展为跨平台的能力封装格式，公开可用的 Skills 数量逼近百万级，累计安装约 2.8 亿次。
从技术演进看，Agent Skills 标志着 AI 应用开发从"手搓提示词"走向"标准化技能工程"。它把专业知识、执行流程、脚本工具和验收标准打包在一起，让 Agent 不再只是会聊天，而是能稳定完成具体工作。
一个 Skill 长什么样
最简单的 Skill 只需要一个文件：
my-skill/
└── SKILL.md
完整结构可以包含这些目录：
my-skill/
├── SKILL.md # 必需：元数据 + 指令
├── scripts/ # 可选：可执行脚本
├── references/ # 可选：参考文档
├── assets/ # 可选：模板、资源
└── ...
核心文件 SKILL.md 的结构
SKILL.md 由两部分组成：YAML Frontmatter（元数据） 和 Markdown 正文（指令），用 --- 分隔。
Frontmatter 元数据
官方规范只允许 6 个字段，其中 2 个必填：
| 字段 | 必填 | 说明 |
|---|---|---|
| name | ✅ | 唯一标识，1-64 字符，仅小写字母/数字/连字符，必须与目录名一致 |
| description | ✅ | 触发核心描述，1-1024 字符，Agent 据此决定是否加载 |
| license | ❌ | 许可证，如 Apache-2.0 |
| compatibility | ❌ | 环境要求，最多 500 字符 |
| metadata | ❌ | 自定义键值对（作者、版本等放这里） |
| allowed-tools | ❌ | 允许使用的工具列表（实验性） |
注意：author、version 等字段不能直接写在 frontmatter 顶层，必须放在 metadata 里，否则验证失败。
Markdown 正文
正文是给 Agent 的执行指令，建议控制在 500 行 / 5000 tokens 以内，超出部分拆分到 references/。 应包含：
- 何时使用：帮助 Agent 判断触发时机
- 分步指令：用祈使句写清楚每一步做什么
- 输出规范：规定结果格式
- 示例：输入输出对，降低理解成本
动手：写第一个 Skill
我们以 “数据周报生成器” 为例。很多测试或开发人员每周都要从数据库拉数据、做图表、写报告，这个流程完全可以交给 AI 自动完成。
第一步：创建目录
mkdir -p .agents/skills/weekly-report
第二步：编写 SKILL.md
---
name: weekly-report
description: >
自动生成数据分析周报。当用户需要分析销售数据、制作图表并生成周报时使用。
支持连接数据库查询、Python 数据处理和 Markdown 报告输出。
license: MIT
metadata:
author: gang
version: "1.0"
---
# 数据周报生成技能
## 何时使用本技能
当用户提出以下请求时触发本技能：
- "帮我生成上周的销售周报"
- "分析一下最近的数据，出个报告"
- "把上周的测试结果汇总一下"
- "做个数据分析周报"
## 执行流程
1. **数据获取**：使用 `scripts/query_db.py` 连接数据库，执行 SQL 查询，获取指定时间段的数据。
2. **数据分析与绘图**：使用 `scripts/analyze.py` 对数据进行同比/环比分析，并生成柱状图和趋势图，图片保存到 `./output/` 目录。
3. **报告生成**：根据 `assets/report_template.md` 模板，填充分析结果和图表，生成 Markdown 格式的周报。
4. **结果输出**：将生成的报告展示给用户，并告知图表存放路径。
## 注意事项
- 数据库连接信息需在 `.env` 文件中配置，脚本会自动读取。
- 如果数据查询为空，应生成"本周无数据"的提示报告，而不是报错。
- 生成的图表统一保存在 `./output/` 目录下，文件名包含日期。
## 输出格式
报告必须包含以下三个部分：
1. **数据概览**：关键指标汇总（表格形式）
2. **趋势分析**：同比/环比变化，配图表
3. **结论与建议**：用简短的 bullet points 列出
第三步：配套脚本（可选）
weekly-report/
├── SKILL.md
├── scripts/
│ ├── query_db.py # 数据库查询脚本
│ └── analyze.py # 数据分析与绘图脚本
├── references/
│ └── db_schema.md # 数据库表结构说明
└── assets/
└── report_template.md # 报告模板
第四步：测试。在支持 Skills 的客户端（如 Claude Code、Cursor）中打开项目，输入"帮我生成上周的销售周报"，Agent 会自动识别并加载你的 Skill，按步骤执行。
渐进式加载机制
Agent 不会一次性加载所有内容，而是分三层：
- 发现层：启动时只读取每个 Skill 的
name+description（约 100 tokens） - 激活层：任务匹配时加载完整
SKILL.md正文 - 执行层：按需读取
scripts/、references/、assets/中的文件
这就是为什么 description 写得准不准，直接决定了 Skill 能不能被触发。
编写高质量 Skill 的要点
- description 要具体：包含功能、场景、触发关键词。“处理数据"太模糊，“分析 CSV 文件，计算统计摘要并生成图表"更精准。
- 单一职责：一个 Skill 只做一件事，复杂任务靠组合多个 Skill。
- 关键校验用脚本：确定性逻辑写在
scripts/里，比让模型用自然语言判断更可靠。 - 指令前置：最重要的步骤放在正文开头，必要时重复强调。
- 命名用动名词：如
analyzing-sales-data、generating-unit-tests，见名知意。
用 skill-creator 自动生成 Skill
https://github.com/anthropics/skills/tree/main/skills/skill-creator
如果你不想从零手写 SKILL.md，可以直接使用 Anthropic 官方提供的 skill-creator。它是一个“元技能”，也就是专门用来帮你创建、校验、测试和优化其他 Skill 的工具，源码在 GitHub 的 anthropics/skills 仓库中。
安装方式大致有两种：
- Claude Code 中安装：先添加官方插件市场，再安装示例技能包：
/plugin marketplace add anthropics/skills /plugin install example-skills@anthropic-agent-skills - 手动安装：从 GitHub 仓库下载 skill-creator 目录，放到本地技能目录，例如 ~/.claude/skills/skill-creator。
安装完成后，在对话里输入：
使用 skill-creator 帮我创建一个新的 Claude Skill。
目标是：自动生成数据分析周报，读取数据库或 CSV 数据，生成图表，并输出 Markdown 报告。
skill-creator 会追问你几个问题：技能名称、触发场景、输入输出、允许使用的工具、边界条件等。回答完后，它会自动生成标准目录结构，包括 SKILL.md、scripts/、assets/、references/ 等文件。
它还能帮你做几件比较工程化的事：
- 校验格式：检查 SKILL.md 的 frontmatter、字段、权限配置是否合规；
- 跑测试用例：对比“带 Skill”和“不带 Skill”的输出差异；
- 迭代优化：根据测试结果调整 description 和正文指令；
- 打包分发：把技能打包成可分享的 .skill 文件。
如果你只是想快速试手，用 skill-creator 会比手写更省事；但如果你想彻底理解 Agent Skill 的结构，还是建议先照着前面的步骤手动写一遍。
进阶：评估你的 Skill
写完后别只靠“感觉还行”来判断。Agent Skill 的评估，核心思路其实和写单元测试很像：定义好输入和预期输出，反复跑，看它是不是稳定达标。
一个测试用例怎么设计
每个测试用例只需要三样东西：
- Prompt：真实用户会怎么问，比如“生成上周的销售周报”
- Expected：好的输出应该长什么样，比如“报告必须包含数据概览、趋势分析、结论与建议三个部分”
- Input files（可选）：测试需要的输入文件，比如一份示例 CSV
把这些用例集中放在 evals/evals.json 里，就构成了你的测试集。
配对评测：装上和关掉各跑一遍
最关键的一步是对比运行：同一个测试用例，装上 Skill 跑一遍，关掉 Skill 再跑一遍。
这样你才能回答两个问题：
- 这个 Skill 真的有用吗？ 如果关掉 Skill 模型也能做得一样好，没必要保留。
- 它带来了什么增量？ 装上之后，输出更完整了？更准确了？还是反而更慢了、更贵了？
看什么指标
跑完一轮测试后，重点关注这几个维度：
- 通过率（Pass Rate）：测试用例中有多少比例达到了预期
- 耗时（Latency）：装上 Skill 后响应变快还是变慢了
- Token 消耗（Cost）：每次执行花了多少 token，增量是否值得
如果装上 Skill 后通过率大幅提升、耗时和成本可控，说明这个 Skill 是有价值的。反之，如果结果差不多，那就要考虑简化或移除它。
自动化评估
如果你不想手工跑对比，官方提供的 skill-creator 内置了一套评估流水线，可以自动完成以下工作：
- Grader：逐条检查输出是否满足预期
- Comparator：盲测对比“有 Skill”和“无 Skill”的输出，客观打分
- Analyzer：分析胜者为什么赢，给出改进建议
- Benchmark：批量跑测试集，输出通过率、耗时、token 用量等汇总指标
这些工具把评估从“凭感觉”变成了“看数据”，让你在每次修改 Skill 后都能量化验证效果。
一句话总结，评估的本质就是：定义好“什么算成功”，然后反复跑，用数据证明你的 Skill 确实比裸模型做得更好。
小结
Agent Skills 的核心思想就一句话：教一次，永久受益。 把你知道的工作流程、团队规范、脚本工具打包进一个文件夹，AI 就能在需要时自动加载并精准执行。从 weekly-report 开始动手试试吧。