Agent Skills 架构指南：构建可扩展 AI 代理能力

前言

本文按照由浅入深的逻辑组织内容，从基础认知到核心技术，再到实践应用与深度思考。无论您是 AI 技术爱好者、开发者还是企业决策者，都能从中获得有价值的 insights 和实用指南。

参考资料

Agent Skills 简介

Agent Skills 是一种轻量级、开放的格式，用于扩展 AI 代理能力，结合专业知识和工作流程。它是由 Anthropic 最初开发并作为开放标准发布的，现已被越来越多的代理产品采用。

核心价值

能力扩展
- 突破模型边界：通过结构化的专业知识注入，使 AI 代理能够处理超出其预训练知识范围的任务。
- 领域深耕：将特定领域的专业知识打包成可复用的技能，大幅提升 AI 在垂直领域的表现。
- 工具整合：无缝集成各种工具和服务，扩展 AI 代理的实际操作能力。
效率提升
- 标准化流程：将复杂的多步骤任务转化为可重复执行的标准作业程序（SOP）。
- 知识沉淀：将组织和个人的专业知识固化为可传播、可迭代的技能包。
- 快速部署：新团队成员或新代理可以立即获得全套专业能力，无需从零开始训练。
生态系统优势
- 开放标准：基于开放标准构建，支持跨平台、跨产品的互操作性。
- 社区驱动：拥有活跃的开源社区，持续丰富和改进技能库。
- 可扩展性：技能可以不断进化和组合，形成更复杂的能力网络。

功能概览

领域专长：将专业知识打包成可重复使用的指令，从法律审查流程到数据分析流程，让 AI 代理成为各个领域的专家助手。
新功能赋予：例如创建专业格式的演示文稿和报告、构建和配置 MCP 服务器、分析复杂的数据集并生成可视化结果。
可重复的工作流程：将多步骤任务转变为一致且可审计的工作流程，确保任务执行的标准化和可靠性。
互操作性：在不同技能兼容的代理产品中重复使用同一技能，实现知识和能力的跨平台共享。

Agent Skills 核心定义

Skill 的核心要素

Agent Skills 是一种标准化的能力扩展格式，它通过结构化的文件组织和内容定义，使 AI 代理能够获得特定领域的专业知识和工作流程执行能力。一个标准的 Skill 必须包含以下核心要素：

Skill = Metadata + Instructions (SOP) + Examples + Tools

Metadata (元数据)
- 作用：用于被系统索引和路由的标签，是技能的'身份证'和'导航坐标'。
- 核心字段：
  - name：技能唯一标识符，建议使用 snake_case 格式，确保全局唯一性。
  - description：技能功能的简明描述，是路由匹配的关键语义信息。
  - version：版本控制，便于技能的迭代和兼容性管理。
  - tags：可选的标签，用于更精细的分类和检索。
Instructions (指令)
- 作用：自然语言编写的算法或 SOP（标准作业程序），是技能的'大脑'和'操作手册'。
- 内容要求：明确的使用场景描述、详细的执行步骤、清晰的决策逻辑和分支处理、错误处理和边界情况应对策略。
Examples (示例)
- 作用：用于 Few-Shot Learning 的输入输出对，是技能的'学习样本'和'行为模板'。
- 格式要求：完整的对话流程（用户输入 → 助手思考 → 工具调用 → 工具响应 → 助手回复）。
Tools (依赖)
- 作用：该技能运行所需的底层原子能力，是技能的'手脚'和'工具库'。
- 类型：内置工具、外部工具、自定义脚本。

技能文件结构

技能的核心是一个包含文件的文件夹。该文件夹包含元数据、指令以及支持技能运行的各种资源。标准的技能文件结构如下：

my-skill/ # 技能根目录
├── SKILL.md # Required: 核心文件，包含元数据和指令
├── scripts/ # Optional: 可执行代码，如辅助脚本、工具函数
├── references/ # Optional: 参考资料，如 API 文档、技术规范
└── assets/ # Optional: 资源文件，如模板、配置文件、示例数据

SKILL.md 文件详解

SKILL.md 是承载业务逻辑的核心载体，是技能的'心脏'。它采用 Markdown + YAML Frontmatter 的混合格式，兼顾了结构化数据和自然语言表达的优势。

---
name: skill_name_id # [必填] 技能唯一标识符，建议使用 snake_case
description: A concise description of what this skill does. # [必填]
version: 1.0.0 # [选填]
tags:
  - data-analysis
  - report-generation
---

正文结构

Usage (使用场景)：明确描述在什么情况下应该激活此技能。这有助于模型进行自我反思和意图确认。
Steps (执行步骤)：这是 Skill 的灵魂。使用自然语言编写的算法逻辑（SOP）。
Examples (示例)：展示典型场景的覆盖和边缘情况的处理。
Considerations (注意事项)：数据安全、错误处理、性能优化等。
Tools Required (所需工具)：列出技能依赖的工具，确保 Agent 能够正确准备执行环境。

辅助文件夹说明

scripts/：存放可执行代码，是技能的'工具箱'。建议将复杂的业务逻辑封装为脚本，保持 SKILL.md 的简洁性（厚工具，薄指令原则）。
references/：存放参考资料，如 API 文档、技术规范。在 SKILL.md 中通过相对路径引用。
assets/：存放资源文件，如报告模板、配置文件、示例数据。需保持资源文件的版本控制。

架构核心：三层渐进式加载机制 (Progressive Disclosure)

为了在有限的 Token 预算内实现无限的能力扩展，Anthropic 提出了一套'渐进式披露' (Progressive Disclosure) 的加载机制。这是一种精密的上下文工程方案，旨在平衡 Token 效率与信息完备性。

三层架构详解

层级	触发时机	加载内容	存储位置	核心作用
Level 1: 索引层	System Init	Skill 元数据 (Metadata)	常驻 System Prompt	建立'能力目录'，让 Agent 知道'能做什么'
Level 2: 指令层	On Demand	SKILL.md 完整正文 (SOP + Examples)	动态注入 Current Context	JIT 知识注入，让 Agent 真正'学会'业务逻辑
Level 3: 执行层	Execution	原子工具调用参数、外部资源	物理执行环境	调用 API、运行脚本、查询数据库

工作流程

初始化阶段：系统加载所有技能的元数据，建立索引目录。
任务接收阶段：Agent 分析用户请求，通过索引目录匹配最合适的技能。
技能加载阶段：按需读取并注入匹配技能的完整指令内容。
执行阶段：Agent 根据技能指令执行具体操作，调用必要的工具和资源。
清理阶段：任务完成后，清理上下文，释放 Token 资源。

技术优势

Token 效率最大化：索引轻量化，仅在需要时加载完整技能内容，避免上下文窗口溢出。
能力扩展无边界：横向扩展可无限添加新技能，纵向深化每个技能包含详细领域知识。
系统稳定性保障：避免因上下文过于庞大导致的注意力稀疏，单个技能的问题不会影响整个系统的稳定性。

FC VS MCP VS AS：AI 代理能力扩展技术对比

核心概念对比

维度	Function Calling (函数调用)	MCP (模型上下文协议)	Agent Skills (智能体技能)
核心定义	代码级接口，定义 AI 可调用的函数及其参数	通讯协议标准，规范 Agent 与外部系统的交互	业务逻辑封装 (SOP)，将专业知识和工作流程标准化
开发语言	JSON Schema + Python/Node.js	TypeScript/Python SDK	Markdown / 自然语言
实现难度	高	中	极低
灵活性	僵化	较强	极强
适用人群	后端工程师	全栈工程师	所有人 (含非技术人员)

角色定位

Function Calling：底层的'零件'。本质是代码级接口，是给机器看的。提供具体的原子操作能力。
MCP：连接的'管道'。本质是通讯协议标准，是给系统用的。规范 Agent 与外部系统的交互方式。
Agent Skills：智能的'说明书'。本质是业务逻辑封装，是给 AI 大脑看的。将专业知识和工作流程转化为可复用的技能。

选型建议

选择 Function Calling：当需要 AI 执行具体、精确的操作，且对操作结果有严格的数据格式要求时。
选择 MCP：当需要 AI 与多个外部系统进行标准化集成，且对系统间通信的可靠性和一致性有较高要求时。
选择 Agent Skills：当需要 AI 运用专业知识完成复杂任务，希望将业务流程标准化和可复用，且团队中包含非技术人员时。

在实际应用中，最佳实践是将三者结合使用：使用 Function Calling 作为底层操作引擎，使用 MCP 作为系统集成桥梁，使用 Agent Skills 作为业务逻辑大脑。

复杂 Agent Skill 示例：docx 技能详解

本章节将通过详细分析 Anthropic 官方仓库中的 docx 技能案例，展示如何构建复杂的 Agent Skills。

技能概览

Anthropic 官方仓库中的 skills/docx 案例展示了如何让 Agent 操控 Word 文档的创建、读取、编辑和渲染。这不仅是一个功能演示，更是一个全栈开发的范例。

技能目标：创建专业格式的 Word 文档（含表格、目录、页眉）、提取带修订模式的内容、将文档转换为 PDF/图片。
多语言混合：同时使用了 Python（文件解包/打包）、Node.js（文档生成）、Bash（工具调用）。
状态管理：引入了'解压 → 编辑 XML → 重打包'的复杂工作流。

设计洞察：这里体现了复杂 Skill 的重要原则——'厚工具，薄指令'。为了避免在 System Prompt 中塞入冗长的 Python 代码，开发者将复杂的文件操作封装成独立的 .py 脚本，放在 scripts/ 目录下。

文件结构解剖

skills/docx/
├── SKILL.md # 核心大脑：SOP 与知识库
└── scripts/
    └── office/
        ├── unpack.py # 工具：将 .docx 解压为 XML 目录
        ├── pack.py # 工具：将 XML 目录重打包为 .docx
        └── soffice.py # 工具：调用 LibreOffice 转换 PDF

SKILL.md 深度解析

元数据与触发器

name: docx
description: Create, read, edit, and manipulate Word documents (.docx). Use when user mentions "Word doc","report", or needs professional formatting.

命名清晰：使用简洁明了的名称 docx。
描述精确：明确指出技能的适用场景，便于路由系统匹配。

核心指令：双模态工作流

文档中定义了两套截然不同的 SOP，分别对应'创建'和'编辑'模式。

模式一：从零创建 (Creation Mode)
- 核心逻辑：编写并执行 Node.js 脚本，使用 docx 库生成文档。
- 技术价值：Agent 不再简单调用 create_doc(text)，而是编写完整的 JavaScript 代码，利用 docx-js 库的强大能力进行排版编程。
模式二：手术刀式编辑 (Surgical Editing Mode)
- Step 1：运行 python scripts/office/unpack.py doc.docx output_dir 解压 XML。
- Step 2：直接读取并修改 word/document.xml。实现'外科手术'般的编辑能力——直接修改底层 XML，实现 API 无法做到的精细修改。
- Step 3：运行 python scripts/office/pack.py output_dir new_doc.docx 重打包。

原子能力层

为了支撑上述复杂逻辑，docx 技能挂载了几个关键的'硬原子'工具：

工具	功能	使用场景
Pandoc	文档格式转换	读取：将 Word 转译为 Markdown，方便 Agent 理解
Unpack/Pack 脚本	ZIP 解包/打包	状态转换：`.docx` ↔ XML 文件夹的互转
LibreOffice (Headless)	文档渲染	转换：后台启动无界面 LibreOffice，将 `.docx` 转为 PDF
Code Interpreter	代码执行	生成：编写并执行 Node.js 代码生成文档

总结：复杂 Skill 的设计原则

docx 技能向我们展示了 Agent Skills 的上限，其设计原则包括：

代码生成 > 工具调用：对于复杂任务，直接让 Agent 编写并运行临时脚本，比预定义大量 API 函数更灵活。
工具链编排：Agent 成为指挥官，指挥多个工具协同工作，形成完整的自动化流水线。
知识封装：将专业知识（如 XML 操作、docx-js 使用）封装在 SKILL.md 中。
分层设计：将业务逻辑（SKILL.md）与执行代码（scripts）分离。

Agent Skills 系统设计核心要素

设计理念

从工程视角来看，Agent Skills 并非简单的文档堆砌，而是一种'高内聚、低耦合'的系统架构设计。要构建一个企业级可用的 Agent Skills 系统，需要从系统工程的角度，重新审视 Agent（宿主环境）与 Skill（业务逻辑）之间的交互协议。

核心要素详解

架构依赖：运行时与业务逻辑的解耦

Skill：静态的业务逻辑定义，本质上是一组'未被执行的代码'或'待处理的 SOP'。
Agent：动态的执行运行时，提供推理引擎（LLM）、记忆模块（Memory）和工具接口（Interfaces）。

设计核心是构建一个能够标准化解析、加载并执行这些静态逻辑的'Agent Runtime'。

核心机制：动态上下文加载

技术挑战在于 Token 效率与信息完备性的平衡。解决方案是采用索引 - 按需加载策略：

索引层：在 System Message 中仅保留极简的元数据索引。
加载机制：利用 Function Calling (read_file) 作为触发器，实现 Skill 内容的 Just-in-Time (JIT) 注入。
生命周期管理：在任务结束后，及时清理上下文，防止 Token 堆积。

能力分层：编排层 vs. 执行层

编排层 (Skill)：负责指导，定义任务的 SOP（标准作业程序）、决策树和数据处理逻辑。
执行层 (Agent)：负责落地，执行具体的工具调用和操作。

协议对齐：双向接口规范

Agent 端规范：具备工具反思能力，提供标准化沙箱，统一接口。
Skills 端规范：工具集匹配，格式标准，意图清晰。

系统架构设计

整体架构包含三个主要部分：

Agent Runtime：路由系统、上下文管理、执行引擎。
Skill Repository：技能索引、技能存储。
Tool Registry：内置工具、外部工具。

实现挑战与最佳实践

技能发现与路由：使用 LLM 进行语义匹配，建立多级标签体系。
技能冲突与优先级：设置优先级级别，识别可能的技能冲突。
执行安全与监控：在隔离环境中执行技能指令，记录所有工具调用。

未来发展方向

智能技能组合：自动组合多个简单技能，形成复杂能力。
自适应学习：根据使用反馈，自动优化技能执行逻辑。
跨平台兼容：实现技能在不同 Agent 平台间的无缝迁移。

专业垂直 Agent VS Agent Skills

两种路线对比

解决垂直领域的 AI 应用问题，主要有两种技术路线：

重型路线：构建高度专业化的垂直领域 Agent，针对特定领域进行深度优化。
轻量路线：基于通用大模型（Base Model），通过添加特定技能包（Agent Skills）来适配垂直领域。

核心差异

维度	专业垂直 Agent	通用 Agent + Skills
开发成本	高	低
开发周期	长	短
迭代速度	慢	快
领域深度	深	中等
通用性	差	强

应用场景划分

通用 Agent + Skills 适用场景（约 80%）

标准化专业任务：常规法律文件审查、标准化财务报表分析。
知识密集型任务：技术文档生成、市场研究分析。
流程化操作：客户服务流程、招聘筛选流程。

专业垂直 Agent 适用场景（约 20%）

高风险领域：医疗诊断与治疗建议、金融投资决策。
高度专业领域：药物研发、尖端科研。
数据密集型领域：高频交易算法、基因组分析。

融合趋势

未来的发展趋势是将两种路线融合，形成混合架构：

底层：通用大模型提供基础智能和泛化能力。
中层：Agent Skills 提供专业知识和工作流程。
顶层：针对特定领域的深度优化模块。

选型建议

何时选择专业垂直 Agent：核心业务场景、高风险场景、数据丰富场景、长期投入场景。
何时选择通用 Agent + Skills：快速部署场景、多领域场景、预算有限场景、标准化场景。

结论

专业垂直 Agent 和通用 Agent + Skills 并非互斥关系，而是互补关系。在实际应用中，应根据具体需求和资源情况，选择合适的技术路线，或采用混合架构。

总结与展望

核心要点回顾

Agent Skills 的价值：轻量级、开放的格式，用于扩展 AI 代理能力。
核心组成要素：Metadata、Instructions、Examples、Tools。
架构设计：三层渐进式加载机制，实现 Token 效率与信息完备性的平衡。
技术对比：相比 Function Calling 和 MCP，具有更低的实现难度和更强的灵活性。
实践应用：通过 docx 技能示例，展示了指导 Agent 编写和执行代码来完成复杂任务的能力。
路线选择：根据具体需求和资源情况选择合适的技术路线。

未来发展趋势

生态系统繁荣：Agent Skills 生态将迎来爆发式增长。
技术标准化：技能包格式和接口将更加标准化。
开发工具链成熟：专业的技能开发工具、测试框架和部署平台将不断涌现。
智能化演进：技能包将具备自我学习和进化能力。

Agent Skills 是 AI 技术发展的重要方向，它通过将专业知识和工作流程标准化，为 AI 代理赋予了无限的能力扩展空间。无论是个人开发者还是企业组织，都可以通过 Agent Skills 技术，快速构建和部署专业的 AI 应用，推动 AI 在各行业的深度应用。