概览
Agent Skills 是一种给 Agent 增加能力的开放格式。一个 Skill 通常是一个目录：必需文件是 SKILL.md，也可以带上参考资料、模板、图片、数据文件或可执行脚本。
skill-name/
├── SKILL.md # 必需：元数据 + 使用说明
├── scripts/ # 可选：可执行脚本
├── references/ # 可选：详细文档、检查清单、规范
├── assets/ # 可选：模板、图片、示例文件
└── ...SKILL.md 由 YAML frontmatter 和 Markdown 正文组成。frontmatter 至少包含 name 和 description；正文告诉 Agent 该怎样完成任务。
这个格式来自 Anthropic 的 Claude Skills。Anthropic 在 2025 年 10 月 16 日发布 Skills，让 Claude 可以在相关任务中加载一个目录里的指令、脚本和资源。2025 年 12 月 18 日，Anthropic 又把 Agent Skills 发布为开放标准，由 agentskills.io 维护，格式细节见 Agent Skills specification。
为什么叫 Skill
这里的 Skill 不是“一个提示词模板”，也不只是“一个工具”。它更接近一项可复用的任务能力：Agent 能发现它、加载它，并按其中的步骤完成一类工作。
一个好的 Skill 同时包含三类东西：
- 何时使用：通过
name和description让 Agent 判断当前任务是否相关； - 如何完成：用
SKILL.md写清步骤、约束、判断标准和失败处理； - 依赖什么：把脚本、模板、规范、示例文件放进同一个目录，任务需要时再加载或执行。
所以它被称为 Skill：它封装的不是一句话，而是一套可发现、可加载、可复用的工作方法。Prompt 更像一次性指令；Tool 更像外部动作接口；Skill 则把知识、流程和资源打包，让通用 Agent 在某类任务上表现得像有经验的执行者。
什么时候该写 Skill
Skills 适合承载那些“不是项目事实、也不是一次性提示”的知识：工作流、检查清单、写作风格、合规步骤、API 使用约定、模板填充方法、脚本运行方法。
你可以用三个信号判断是否该做成 Skill：
- 你总在粘贴同一段步骤。每次做代码审查、写周报、处理 PDF、生成投放文案，都要复制同一段 playbook。
- 系统提示词开始变胖。原本只该放身份、边界和项目事实的地方，逐渐塞进大量“遇到 X 就按 Y 流程做”的程序性内容。
- 同一套规则要给多个 Agent 或多个项目用。复制几份很快就会漂移，最后没人知道哪一份是最新规则。
做成 Skill 后，这些知识可以版本管理、跨项目复用，并且只在任务需要时加载。
Skill 与 Prompt 的区别
Skill 仍然会给模型提供文本指令，但它不是“把一堆 Markdown 拼进 system prompt”。关键差别在加载方式。
系统提示词是常驻的：不管任务需不需要，每次调用都带着。Skill 是按需的：Agent 先看到轻量的技能列表；判断某个 Skill 相关时，再加载完整说明；需要更细资料时，再读取对应文件。
这带来两个结果：
- 基线成本更低：常驻上下文只保留每个 Skill 的名字和描述。
- 能力可以更厚：详细规范、模板和脚本不必挤在主提示里，可以放在 Skill 目录里按需读取。
渐进式披露
Skills 的核心机制是渐进式披露（progressive disclosure）：先给 Agent 足够判断的信息，再按需加载更完整的内容。
| 层级 | 加载内容 | 何时加载 | 作用 |
|---|---|---|---|
| L1 | name 和 description | 启动时加载所有 Skill 的元数据 | 让 Agent 知道“有哪些能力可用” |
| L2 | SKILL.md 正文 | 任务匹配某个 Skill 时加载 | 给出工作流、步骤、约束和判断标准 |
| L3 | references/、assets/、scripts/ 等文件 | L2 指令要求时加载 | 提供详细资料、模板、示例或可执行能力 |
这就是 Skills 的杠杆：Agent 可以拥有很多能力，却不必在每一次上下文里携带所有能力的完整说明。
description 是触发器
description 是 Agent 判断是否加载 Skill 的主要依据。它不只是给人看的简介，更像搜索索引和触发条件。
好的描述要同时说清两件事：
- 这个 Skill 做什么；
- 用户说出哪些任务、文件、场景或关键词时应该使用它。
例如：
description: Extract text and tables from PDF files, fill PDF forms, and merge multiple PDFs. Use when working with PDFs, forms, scanned documents, or document extraction.差的描述通常太泛：
description: Helps with documents.前者能匹配 “PDF”“forms”“document extraction”；后者几乎不能帮助 Agent 判断是否该加载。
内容放在哪里
写 Skill 时，最重要的设计动作是分层：
| 内容 | 放在哪里 | 原因 |
|---|---|---|
| Skill 名称、用途、触发条件 | frontmatter | Agent 需要用它判断是否加载 |
| 主要步骤和约束 | SKILL.md 正文 | Skill 激活后必须立即可见 |
| 长篇规范、领域知识、案例 | references/ | 只有相关步骤需要时再读 |
| 输出模板、示例文件、图片 | assets/ | 只在生成或转换时需要 |
| 可复用执行逻辑 | scripts/ | 让 Agent 不必手写复杂、易错的操作 |
一个实用原则：主文件负责指挥，细节文件负责承载知识。如果 SKILL.md 越写越长，就把详细说明拆到 references/，并在正文里明确告诉 Agent 什么时候读取哪一个文件。
常见形态
Agent Skills 标准定义的是目录格式；在实际设计中，Skill 常见有几种形态：
| 形态 | 适合放什么 |
|---|---|
| 工具包装 | 告诉 Agent 何时使用某个工具、参数怎么填、失败怎么处理 |
| 生成器 | 生成固定类型的产物，如报告、邮件、页面、合同草案 |
| 审阅器 | 按检查清单审查代码、文档、设计或合规风险 |
| Inversion | 把用户已有材料反向提炼成结构化知识，例如从文档中整理团队规范 |
| Pipeline | 把多步工作串起来，例如收集资料、生成初稿、校验、导出 |
这些只是组织方式，不是规范的一部分。真正的判断标准仍然是：description 是否能触发、SKILL.md 是否足够简洁、细节是否按需加载、输出是否能验证。
还有一种特殊形态是 Meta Skill。它不直接完成业务任务，而是教 Agent 如何创建新的 Skill。Meta Skill 通常会引用规范、示例和命名约定，让 Agent 在遇到重复工作时生成新的 SKILL.md 草稿。
多 Skill 组合
当 Agent 能看到多个 Skill 的 L1 元数据时，它可以自己决定加载一个还是多个。
例如用户说：“帮我写一篇博客引言，并确保 SEO 友好。”如果 blog-writer 和 seo-checklist 的描述都写得清楚，Agent 可以同时加载两个 Skill：一个负责写作流程，一个负责 SEO 检查。
反过来，如果没有匹配的 Skill，好的系统应该让 Agent 说清“当前没有相关能力”，而不是假装有一套不存在的流程。
存储与复用
Skills 的价值会随着复用增长。常见存放位置有两类：
- 项目级：放在仓库内，例如
<project>/.agents/skills/，适合团队共享、随代码一起评审和发布。 - 用户级：放在用户目录，例如
~/.agents/skills/，适合个人跨项目复用。
因为 Skill 本质上是文件目录，它天然适合用 git 管理：可以 review、打 tag、回滚，也可以把稳定 Skill 收进团队库。外部 Skill 也应像依赖一样处理：先审查内容、许可证和脚本权限，再放进运行环境。