【原文翻译搬运】Equipping agents for the real world with Agent Skills

原文地址：https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills

为现实世界打造智能体：Agent Skills 技能体系 | Anthropic

随着模型能力的提升，我们现在可以构建与完整计算环境交互的通用型智能体。例如Claude Code能通过本地代码执行和文件系统完成跨领域复杂任务。但当这些智能体变得更强大时，我们需要更模块化、可扩展且便携的方式为其赋予领域专业知识，这促使我们创建了Agent Skills（智能体技能）——一种包含指令、脚本和资源的结构化文件夹体系，智能体可动态发现并加载这些资源以更好完成特定任务。

Skills通过将您的专业知识打包为可组合资源来扩展Claude的能力，将通用智能体转化为符合您需求的专用智能体。构建智能体技能就像为新员工准备入职指南：无需为每个用例构建碎片化的定制智能体，现在任何人都可以通过捕获和共享流程知识，用可组合能力来专业化定制智能体。

技能的核心结构

一个技能就是一个包含SKILL.md文件的目录，内含提供额外能力的结构化指令、脚本和资源文件夹。以下是其解剖结构：

1. 基础层级（YAML前置元数据）

• SKILL.md文件必须以YAML前置内容开头，包含必需的元数据：name（名称）和description（描述）
• 启动时，智能体会将所有已安装技能的名称和描述预加载到系统提示中
• 这是渐进式披露的第一层：仅提供足够信息让Claude知道何时使用该技能，而无需将全部内容加载到上下文中

2. 详细层级（核心内容）

• 文件实际正文是第二层细节。如果Claude认为该技能与当前任务相关，会通过读取完整SKILL.md内容将其加载到上下文中

3. 扩展层级（关联文件）

• 当技能变得过于复杂或某些内容仅在特定场景相关时，技能可在目录中捆绑额外文件，并通过SKILL.md按名称引用
• 这些附加链接文件构成第三层（及更深）细节，Claude可根据需要选择性地导航和发现
• 示例：PDF技能中的SKILL.md引用了两个附加文件（reference.md和forms.md），将表单填写说明分离到独立文件，保持核心精简，Claude仅在填写表单时读取forms.md

渐进式披露是使Agent Skills灵活可扩展的核心设计原则。就像组织良好的手册从目录开始，再到具体章节，最后是详细附录，技能让Claude按需加载信息：具备文件系统和代码执行工具的智能体在处理特定任务时，无需将整个技能内容读入上下文窗口。这意味着技能中可捆绑的上下文量实际上是无限的。

技能与上下文窗口的协同

下图展示了用户消息触发技能时上下文窗口的变化过程：

1. 初始状态：上下文窗口包含核心系统提示、每个已安装技能的元数据以及用户初始消息
2. 触发阶段：Claude通过调用Bash工具读取pdf/SKILL.md内容来触发PDF技能
3. 深度加载：Claude选择读取技能捆绑的forms.md文件
4. 执行阶段：加载PDF技能的相关指令后，Claude继续处理用户任务

技能与代码执行的结合

技能还可包含供Claude酌情执行的代码作为工具：

• 大语言模型擅长许多任务，但某些操作更适合传统代码执行（例如通过令牌生成排序列表比直接运行排序算法成本高得多）
• 除效率外，许多应用需要代码才能提供的确定性可靠性
• 在PDF技能示例中，包含预写Python脚本用于读取PDF并提取所有表单字段。Claude无需将脚本或PDF加载到上下文中即可运行此脚本，且由于代码具有确定性，该工作流一致且可重复
• 根据任务性质，技能还可包含Claude酌情执行的代码工具

技能开发与评估指南

1. 从评估入手

• 通过在代表性任务上运行智能体，观察其薄弱环节或需要额外上下文的场景，识别能力缺口
• 针对性增量构建技能来解决这些不足

2. 面向扩展的结构设计

• 当SKILL.md文件变得臃肿时，拆分内容到独立文件并引用
• 若某些上下文互斥或很少共同使用，保持路径分离可减少token消耗
• 代码既可作为可执行工具，也可作为文档。需明确Claude应直接运行脚本还是将其作为参考读入上下文

3. 从Claude视角思考

• 监控Claude在实际场景中使用技能的情况并基于观察迭代：注意意外轨迹或对某些上下文的过度依赖
• 特别关注技能的名称和描述——Claude将根据这些决定当前任务是否触发该技能

4. 与Claude协同迭代

• 与Claude协作完成任务时，要求其将成功方法和常见错误捕获为技能内可复用的上下文和代码
• 若使用技能完成任务时偏离轨道，要求其自我反思问题所在
• 此过程有助于发现Claude实际需要的上下文，而非预先猜测

使用技能的安全考量

技能通过指令和代码为Claude提供新能力，这也意味着恶意技能可能在所用环境中引入漏洞，或引导Claude窃取数据并采取非预期行动。建议：

• 仅从可信来源安装技能
• 从低信任来源安装时，使用前彻底审计：阅读技能捆绑文件内容，重点关注代码依赖项和图像/脚本等捆绑资源
• 注意技能中指示Claude连接潜在不可信外部网络源的指令或代码

技能的未来发展

目前Agent Skills已支持Claude.ai、Claude Code、Claude Agent SDK和Claude开发者平台。未来几周将持续新增功能，支持技能创建、编辑、发现、共享和使用的完整生命周期，特别期待：

• 技能助力组织和个人与Claude共享上下文和工作流
• 探索技能如何通过教授涉及外部工具和软件的复杂工作流来补充模型上下文协议(MCP)服务器
• 长期目标：使智能体能自主创建、编辑和评估技能，将其自身行为模式固化为可复用能力

技能概念简单且格式对应简洁，这使得组织、开发者和终端用户更易构建定制化智能体并赋予新能力。让我们期待技能带来的无限可能！

落地实现扩展

方案 1：直接由大模型（LLM）读取并判断技能内容（当前 Agent Skills 的主流做法）

1. 技能文件（如 SKILL.md 及其关联文件）直接以文件形式存放在技能目录中；
2. 当用户发起请求时，智能体（或系统提示）会将所有已安装技能的元数据（如名称、描述）先加载到上下文中，让大模型判断哪些技能可能相关；
3. 如果某个技能看起来相关，智能体将进一步读取该技能的 SKILL.md 主体甚至关联文件内容，并基于此做出决策；
4. 智能体也可能直接执行技能中包含的代码工具（如 Python 脚本），而无需将代码加载进上下文，而是通过工具调用机制运行。

🔧 适用场景：

• 技能数量可控（几十到几百个）
• 每个技能的结构清晰、标准化（如都有 SKILL.md + 可选附加文件）
• 希望利用大模型自身的理解与推理能力，动态判断技能相关性并加载内容

✅ 优点：

• 实现相对简单，无需额外向量检索系统
• 大模型可以综合任务描述、技能描述、上下文线索，做出更灵活、更智能的判断
• 符合 Anthropic 官方 Agent Skills 的设计思路

⚠️潜在挑战：

• 如果技能数量极大（上千个），仅靠模型读取元数据也可能面临效率或筛选准确率问题
• 需要良好的技能命名、描述与元数据设计，以帮助模型判断

方案 2：将技能元数据或摘要放入 RAG 向量数据库，辅助大模型检索合适的技能

1. 把完整的技能内容（如 SKILL.md 或代码脚本）放进向量库；
2. 当用户输入一个问题时，先通过RAG检索找出最相关的一个或多个技能；
3. 将这些技能的完整内容（如 SKILL.md 或代码）加载到上下文中，或直接让智能体基于检索结果调用对应技能。

🔧 适用场景：

• 技能数量较多（几百几千个），希望提高检索效率与精准度
• 希望引入技能分类、标签体系、语义搜索等更高级的匹配机制

✅ 优点：

• 检索更高效，尤其适合大规模技能库
• 可结合向量语义相似度 + 关键词匹配 + 分类标签，提升技能推荐的精准度
• 可扩展为“技能市场”、“智能推荐技能”等高级功能

⚠️潜在挑战：

• 需要额外维护技能的元数据质量与向量索引
• 依然需要大模型最终判断如何使用该技能、是否加载详细内容或调用工具
• 系统复杂度更高，涉及 RAG 检索 + 技能加载 + 上下文管理 + 工具调用等多个模块