前言

        随着大型语言模型能力的快速提升，如何让通用型 AI 代理更好地适应现实世界的复杂任务成为业界关注的焦点。2025 年 10 月 16 日，Anthropic 在其官方博客发布了 "Equipping agents for the real world with Agent Skills" 一文，正式推出了Agent Skills 技术架构。这一创新技术代表了 AI 代理从简单工具调用向专业化能力封装的重要范式转变。

        Agent Skills 的核心价值在于将复杂的程序性知识和组织上下文封装为标准化的文件夹结构，使通用型 AI 代理能够根据任务需求动态加载和使用特定领域的专业能力。与传统的 Prompt 工程或 API 调用相比，Agent Skills 提供了一种更高效、可复用、可治理的解决方案，能够显著提升 AI 代理在专业场景下的表现。

        本文将主要深入分析 Agent Skills 的技术实现细节、设计理念、应用场景，并与其他类似技术进行对比，通过对官方技术文档、GitHub 开源项目以及实际应用案例的综合分析，为读者提供全面的技术洞察和实践指导。

Skills 基本规格

        一个 Skill（技能）是一个独立的文件夹，其核心是一份带有特定“头信息”的说明文件，它规定了技能如何被AI识别和使用。

基本结构：一个文件夹

        一个技能就是一个文件夹，其最低要求是必须包含一个 SKILL.md 文件。目录结构大致如下：

你的技能名/
├── SKILL.md          # 【必需】技能的核心说明文件
├── scripts/          # 【可选】存放可执行脚本的目录
├── references/       # 【可选】存放参考文档的目录
└── assets/           # 【可选】存放模板、图片等静态资源的目录

核心文件：SKILL.md

SKILL.md 是技能的“身份证”和“说明书”，它必须包含两部分：

• YAML Frontmatter (头信息)： 位于文件顶部，用于定义技能的元数据。

• Markdown Body (正文)： 头信息之后的内容，用于编写具体的使用说明和步骤。

头信息（Frontmatter）是重点，它包含以下字段：

字段	是否必需	说明与约束
name	是	技能名称。必须与文件夹同名，只能包含小写字母、数字和连字符(-)，且不能以连字符开头或结尾。
description	是	技能描述（1-1024字符）。需清晰说明技能做什么以及何时使用，应包含帮助AI识别的关键词。
license	否	许可证信息（如 Apache-2.0）。
compatibility	否	兼容性说明（≤500字符）。仅当技能有特殊环境要求（如需要特定软件、网络）时才需要填写。
metadata	否	自定义的键值对，用于存放作者、版本等额外信息。
allowed-tools	否	（实验性功能）预授权可使用的工具列表。

头信息示例：

---
name: skill-creator
description: Guide for creating effective skills. This skill should be used when users want to create a new skill (or update an existing skill) that extends Claude's capabilities with specialized knowledge, workflows, or tool integrations.
license: Complete terms in LICENSE.txt
---

       正文（Body）部分则没有固定格式，你可以自由撰写步骤、示例、注意事项等，帮助AI有效地执行任务。

可选目录的用途

• scripts/： 存放AI可以运行的可执行脚本（如Python、Bash脚本）。

• references/： 存放详细的参考文档，当AI需要深入了解某些专业知识时会查阅。

• assets/： 存放静态资源，如模板文件、图片或数据文件。

核心设计理念：渐进式披露

基本规范

        这个规范强调高效利用AI的上下文（Context）：

1. 启动时加载： AI启动后，会立即读取所有技能的 name 和 description（约100个令牌）来建立索引。

2. 激活时加载： 当决定使用某个技能时，才会加载该技能 SKILL.md 的全部正文（建议少于5000令牌）。

3. 按需加载： scripts/、references/ 等目录下的具体文件，只在AI确实需要时才被读取。

        这种设计能有效节省宝贵的上下文空间。

渐进式披露机制的三层架构设计

        Agent Skills 的核心创新在于其渐进式披露（Progressive Disclosure）架构，这一设计彻底解决了传统 AI 代理在处理复杂任务时面临的上下文窗口限制问题。根据官方技术文档，Agent Skills 采用了精密的三层加载机制：

第一层：元数据层（Metadata，始终加载）

        元数据层包含技能的基本信息，通过 YAML frontmatter 格式定义，主要包括两个必需字段：

• name：技能名称，限制为 64 个字符以内，只能包含小写字母、数字和连字符

• description：技能描述，限制为 1024 个字符以内，必须描述技能的功能和使用时机

        这一层的设计极其轻量级，每个技能仅消耗约 100 个 tokens。这种设计使得系统可以安装数百个技能而不会造成显著的上下文开销。元数据在系统启动时被预加载到 Agent 的系统提示中，为技能发现和调用提供基础信息。

第二层：指令层（Instructions，触发时加载）

        指令层包含技能的核心执行逻辑，存储在 [SKILL.md](SKILL.md) 文件的主体部分。这一层只有在 Agent 判断该技能与当前任务相关时才会被加载，通常不超过 5000 个 tokens。

        指令层的内容设计遵循不同的自由度级别：

• 高自由度（文本指令）：适用于多种方法都有效的场景，如代码审查流程

• 中等自由度（带参数的伪代码或脚本）：适用于存在首选模式但允许一定变化的场景

• 低自由度（特定脚本，很少或没有参数）：适用于操作易出错、一致性要求极高的场景，如数据库迁移

第三层：资源和代码层（Resources and code，按需加载）

        第三层包含额外的支持文件，如脚本、参考文档、数据模板等，这些内容仅在需要时加载，理论上无 token 限制。这一层的设计使得技能可以包含任意复杂的资源，而不会在启动时造成负担。

        渐进式披露机制的核心优势在于，它将原本一次性交付的大上下文拆解为 "决策 — 反馈 — 再决策" 的多轮循环，每一步只提供与当前决策相关的最小信息集。这种设计不仅减少了噪音干扰，还让整个执行过程更加可控。

工具调用流程与执行机制

Agent Skills 功能执行流程

        Agent Skills 的执行机制基于 Claude 的代码执行环境，该环境提供了完整的文件系统访问、bash 命令执行和代码执行能力。整个执行流程体现了 "环境感知与知识集成" 的范式转变 。

技能触发与加载流程：

1. 系统启动阶段：Agent 预加载所有技能的元数据（name 和 description）到系统提示中

2. 任务匹配阶段：当用户提出任务请求时，Agent 基于技能描述判断是否需要调用特定技能

3. 技能激活阶段：通过 bash 工具读取技能的 [SKILL.md](SKILL.md) 文件内容

4. 资源加载阶段：根据指令需要，选择性加载额外的参考文件或执行脚本

5. 任务执行阶段：使用加载的指令和资源完成具体任务

        在 PDF 处理技能的实际案例中，这一流程表现为：

• 启动时系统提示包含 "PDF Processing - Extract text and tables from PDF files, fill forms, merge documents"

• 用户请求 "Extract the text from this PDF and summarize it"

• Claude 调用 bash: read pdf-skill/[SKILL.md](SKILL.md) → 指令加载到上下文

• Claude 判断不需要表单填充，因此不读取 [FORMS.md](FORMS.md)

• Claude 使用 [SKILL.md](SKILL.md) 中的指令完成任务

代码执行的高效性机制：

        技能中的代码执行具有独特的优化机制。当 Agent 执行脚本时，只有脚本的输出结果被载入上下文，而脚本的代码本身不会占用上下文窗口的 tokens。这种设计通过将知识检索和脚本执行从核心上下文窗口中解耦出来，实现了高效的 Token 管理和上下文隔离。

        例如，在 PDF 技能中包含一个预编写的 Python 脚本，用于读取 PDF 并提取所有表单字段。Claude 可以运行这个脚本而无需将脚本或 PDF 加载到上下文中。由于代码是确定性的，这种工作流程具有一致性和可重复性。

工作流设计模式

        技能的工作流设计遵循清晰的步骤化原则。以 PDF 表单填充工作流为例：

\## PDF form filling workflow

Copy this checklist and check off items as you complete them:

\[ ] Step 1: Analyze the form (run analyze\_form.py)

\[ ] Step 2: Create field mapping (edit fields.json)

\[ ] Step 3: Validate mapping (run validate\_fields.py)

\[ ] Step 4: Fill the form (run fill\_form.py)

\[ ] Step 5: Verify output (run verify\_output.py)

        这种清单式工作流设计确保了执行的完整性和可追溯性，避免了 Agent 跳过关键验证步骤的风险。每个步骤都有明确的输入输出定义，形成了闭环的执行体系。

安全性与权限控制机制

        随着 Agent Skills 赋予 AI 更强的行动能力，安全风险也呈指数级上升。Agent Skills 的安全架构采用了多重防御机制来确保系统的安全性和可靠性。

核心安全威胁识别：

        主要安全威胁包括：

1. 指令注入（Prompt Injection）：恶意指令可能植入到技能描述或内部文件中，劫持 Agent 行为

2. 远程代码执行（RCE）风险：由于技能允许执行代码，可能包含挖矿脚本或窃密代码

3. "糊涂代理人" 问题：智能体拥有代表用户执行操作的权限，可能被间接提示注入攻击利用

多层次安全防护体系：

• 沙盒隔离机制：

  • 技能代码必须在安全的沙盒容器（如 Docker 或 WASM）中运行

  • 实施严格的网络访问控制，默认无网络访问或限制在白名单内

  • 使用容器、用户模式内核或轻量级虚拟机实现环境隔离

• 权限最小化原则：

  • 技能和运行它的 AI 智能体不应拥有超出其完成任务所需的最小权限

  • 采用细粒度的权限控制，为不同技能分配不同的访问级别

  • 实施 "默认拒绝" 策略，只有明确授权的操作才能执行

• 来源验证与审计：

  • 仅安装来自可信来源的技能

  • 使用前仔细阅读技能中的所有文件，特别是脚本依赖和外部资源链接

  • 建立完整的操作日志审计机制，记录所有技能调用和文件访问

• 人机回环（HITL）机制：

  • 对于敏感操作（如转账、删除数据），强制要求人类审批节点

  • 建立关键操作的双重验证机制

  • 确保 AI 无法在未经授权的情况下执行高风险操作

Agent Skills 设计原则

"可治理性" 设计原则

        Agent Skills 的可治理性设计原则体现在模块化、标准化和可审计性三个核心维度，为企业级应用提供了可靠的管理基础。

模块化封装的治理优势：

        每个技能都是独立的模块化单元，具有清晰的边界和接口。这种设计带来了多重治理优势：

• 单一职责原则：每个技能专注于一个特定任务，避免功能混杂

• 版本控制支持：技能可以像传统软件一样进行版本管理和变更追踪

• 权限分离机制：不同技能可以配置不同的访问权限，实现最小权限原则

标准化格式的互操作性：

        Agent Skills 采用了标准化的文件格式和目录结构，这种标准化设计带来了显著的互操作性优势：

• 跨平台兼容性：基于开源标准，无需为不同工具单独适配

• 社区生态支持：标准化格式促进了技能的共享和复用

• 工具链集成：支持与各种开发工具、版本控制系统的无缝集成

可审计性的技术实现：

        可审计性是企业级应用的关键需求。Agent Skills 通过以下机制实现了完整的审计能力：

• 操作日志记录：所有技能调用和文件访问都有详细记录

• 执行流程追踪：技能的执行步骤可以被完整追溯

• 变更管理机制：技能的修改历史可以被记录和审查

"安全性" 设计原则

        安全架构在 Agent Skills 中不是 "锦上添花"，而是系统架构的基石。每一个技能执行都必须经过身份验证、权限控制和行为约束。

On-Behalf-Of（OBO）执行模式：

        所有技能的执行行为都被严格建模为 On-Behalf-Of 模式，这意味着技能执行的所有操作都代表授权用户的身份。这种模式要求在架构层面进行风险分级建模，确保每个操作都有明确的责任归属。

风险分级管理机制：

        技能的安全管理采用分级策略：

• 高风险操作：如数据库修改、文件删除等，需要额外的安全验证

• 中风险操作：如文件读取、数据查询等，需要常规权限检查

• 低风险操作：如文档生成、格式转换等，采用默认安全策略

沙盒执行环境的技术实现：

        技能代码的执行必须在严格的沙盒环境中进行，这一要求通过多种技术手段实现：

• 容器化部署：使用 Docker 等容器技术实现环境隔离

• 资源限制：限制 CPU、内存、网络等资源的使用

• 文件系统隔离：技能只能访问其目录下的文件，无法访问系统敏感区域

"可组合性" 与 "模块化" 设计原则

        Agent Skills 的可组合性和模块化设计思想体现在技能之间的灵活协作和能力的无限扩展上。

"大脑、手与皮层" 的生物学隐喻：

        为了更深入地理解 Agent Skills 在智能体架构中的位置，业界广泛采用了生物学类比：

• 大脑（Brain）：由大语言模型（LLM）充当，负责推理、规划、意图识别与决策

• 手（Hands）：由具体的执行工具（Tools/APIs）构成，负责与外部世界交互

• 皮层（Cortex/Skill Layer）：这是 Agent Skills 所在的层次，存储了 "如何使用手完成特定任务" 的过程性记忆

        这种架构设计的核心价值在于，它将抽象的任务目标转化为具体的执行动作序列，使得复杂的业务流程可以被分解和重组。

模块化封装的技术优势：

        模块化设计带来了多重技术优势：

• 一次编写，终身复用：彻底告别重复指令，尤其适合团队协作中统一 AI 使用规范

• 跨平台兼容：基于开源标准，无需为不同工具单独适配，大幅降低技能维护成本

• 渐进式开发：可以从简单技能开始，逐步构建复杂的技能体系

• 故障隔离：单个技能的问题不会影响整个系统的运行

"用户友好性" 与 "可发现性" 设计原则

        Agent Skills 在用户体验设计上遵循简洁性和可发现性的原则，使得技能的创建、管理和使用都变得简单高效。

极简的技能创建流程：

        技能的创建门槛极低，仅需 Markdown 基础，无需复杂开发技能。创建一个基本技能只需要：

1. 创建一个目录

2. 在目录中创建 [SKILL.md](SKILL.md) 文件

3. 编写 YAML frontmatter（name 和 description）

4. 编写技能指令内容

        这种设计使得普通使用者也能快速搭建专属技能，大大降低了 AI 应用的技术门槛。

智能的技能发现机制：

        技能的发现机制基于自然语言理解，通过技能描述中的关键词匹配来实现：

• 描述的重要性：描述必须包含技能的功能和使用时机

• 关键词设计：使用具体的触发词帮助 Agent 识别相关任务

• 第三人称规范：描述必须使用第三人称，确保格式一致性

        例如，一个优秀的描述应该是："Extracts text and tables from PDF files, fills PDF forms, and merges multiple PDFs. Use when working with PDF documents or when the user mentions PDFs, forms, or document extraction."

与传统 AI 代理架构的差异化设计理念

        Agent Skills 代表了 AI 代理架构从 "工具调用" 向 "环境感知与知识集成" 的范式转变。这种转变体现在多个关键维度上。

从 "工具" 到 "技能" 的语义进化：

        传统的工具调用方式将 AI 代理视为简单的函数调用器，而 Agent Skills 则将其视为具有专业知识的智能体。工具通常被定义为原子化的操作 —— 如同 "锤子" 或 "螺丝刀"，对应单一的 API 端点；而技能则是对能力的更高阶封装 —— 如同 "木匠的工艺"，它不仅包含了工具本身，还包含了何时使用工具、如何处理异常、以及多步决策的隐性知识。

渐进式披露 vs 静态加载：

        传统的 AI 代理通常需要在启动时加载所有可能需要的工具描述和上下文信息，这在面对复杂任务时会迅速耗尽资源。而 Agent Skills 通过渐进式披露机制，实现了 "按需加载" 的智能资源管理 ，使得系统可以处理无限复杂的任务而不会受到上下文限制。

知识封装 vs 函数调用：

        传统方法将知识分散在不同的函数调用中，缺乏系统性和一致性。Agent Skills 则将相关的知识、技能和工具封装在一个统一的包中，形成了完整的知识单元。这种设计不仅提高了知识的复用性，还确保了执行的一致性和可预测性。

参考文献

https://agentskills.io/home

https://claude.com/blog/equipping-agents-for-the-real-world-with-agent-skills