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

1. Metadata (元数据)

   • 作用：用于被系统索引和路由的标签，是技能的'身份证'和'导航坐标'。
   • 核心字段：
     • name：技能唯一标识符，建议使用 snake_case 格式，确保全局唯一性。
     • description：技能功能的简明描述，是路由匹配的关键语义信息。
     • version：版本控制，便于技能的迭代和兼容性管理。
     • tags：可选的标签，用于更精细的分类和检索。

2. Instructions (指令)

   • 作用：自然语言编写的算法或 SOP（标准作业程序），是技能的'大脑'和'操作手册'。
   • 内容要求：明确的使用场景描述、详细的执行步骤、清晰的决策逻辑和分支处理、错误处理和边界情况应对策略。

3. Examples (示例)

   • 作用：用于 Few-Shot Learning 的输入输出对，是技能的'学习样本'和'行为模板'。
   • 格式要求：完整的对话流程（用户输入 → 助手思考 → 工具调用 → 工具响应 → 助手回复）。

4. 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 效率与信息完备性。

三层架构详解

工作流程

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

技术优势

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

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

核心概念对比

角色定位

• 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，分别对应'创建'和'编辑'模式。

1. 模式一：从零创建 (Creation Mode)

   • 核心逻辑：编写并执行 Node.js 脚本，使用 docx 库生成文档。
   • 技术价值：Agent 不再简单调用 create_doc(text)，而是编写完整的 JavaScript 代码，利用 docx-js 库的强大能力进行排版编程。

2. 模式二：手术刀式编辑 (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 技能挂载了几个关键的'硬原子'工具：

总结：复杂 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 端规范：工具集匹配，格式标准，意图清晰。

系统架构设计

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

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

实现挑战与最佳实践

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

未来发展方向

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

专业垂直 Agent VS Agent Skills

两种路线对比

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

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

核心差异

应用场景划分

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

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

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

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

融合趋势

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

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

选型建议

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

结论

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

总结与展望

核心要点回顾

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

未来发展趋势

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

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