用 Agent Skills 装备现实世界的 Agent
🎯 一句话
Skill 的核心机制是三层渐进式披露:先给一行描述、需要时展开说明、真正用到才加载资源。⭐ 这让上下文只为「当下真正用得上的东西」付费。
本页先解决:技能简介、正文与附件分别何时加载?
Claude 博客资料库 · 智能体技能
技能简介、正文与附件分别何时加载?
技能包里有什么,与当前轮次加载了什么是两回事;先看三层披露的触发条件。
读完可以:辨认技能简介、正文和附件的加载触发与执行风险。
加载由需要触发
- 先读元数据名称与描述帮助判断技能是否相关
- 适用时读正文选中后加载 SKILL.md 核心说明
- 需要时读附件只取当前任务需要的参考文件或资源
脚本执行与参考资料读取分开:代码能力仍须来源审查与权限边界。
- 原文标题
- Equipping Agents for the Real World with Agent Skills(用 Agent Skills 装备现实世界的 Agent)
- 原文链接
- https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills
- 作者
- Barry Zhang、Keith Lazuka、Mahesh Murag(Anthropic)
- 发布日期
- 2025-10-16(2025-12-18 更新:发布为开放标准)
Claude 能力强大但对现实工作而言并不完整——组织需要具备领域专长、程序性知识和组织上下文的专门化 Agent。Agent Skills 提供了一个可组合、可扩展的框架:用有组织的指令、脚本和资源包来扩展 Agent 能力,类似「给新员工准备一份入职指南」。
技能包里有什么,与当前轮次加载了什么是两回事;先看三层披露的触发条件。
什么是 Agent Skills
- 一个包含
SKILL.md文件的目录,捆绑指令、脚本和资源 - 不必为每个用例重建定制 Agent,而是通过打包程序性知识来专门化通用 Agent
SKILL.md 格式与渐进式披露
结构
SKILL.md 以 YAML frontmatter 开头,至少包含 name 和 description。
三层信息架构
- 第一层(系统提示词): 仅预载技能元数据(名称+描述),让 Claude 能识别何时相关,而不加载全文
- 第二层(核心内容): Claude 判断技能适用时才加载
SKILL.md正文 - 第三层及以上(补充文件):
SKILL.md中引用的其他文件(如reference.md、forms.md)只在具体需要时加载
PDF 技能示例
Claude 理解 PDF 概念但缺乏直接操作能力。PDF 技能捆绑:核心 SKILL.md(表单填写概览)+ forms.md(详细填表指令)+ reference.md(通用 PDF 操作)+ 用于确定性提取表单字段的 Python 脚本。核心保持精简,按场景定向加载。
为什么渐进式披露是核心设计原则
像一本组织良好的手册(目录、章节、附录),Claude「只在需要时加载信息」。具备文件系统和代码执行能力的 Agent 不需要把整个技能装进上下文——技能包可大于单个上下文窗口,但每次读取仍受窗口、检索质量与执行预算限制。
读取参考资料与执行脚本职责不同;不要把整个技能包都视为提示词文本。
上下文窗口的工作机制
- 初始上下文:系统提示词 + 所有技能元数据 + 用户消息
- Claude 用 Bash 工具读取
pdf/SKILL.md触发技能 - 按需选择性读取捆绑文件(如
forms.md) - 用加载的技能指令执行用户任务
技能与代码执行
技能可捆绑可执行代码,Claude 自行决定何时使用:
- 效率: 确定性排序用代码跑比逐 token 生成强
- 可靠性: 确定性代码保证一致可重复的流程
- 分离: 代码可以在不加载其本身或相关数据进上下文的情况下执行(如不加载 PDF 就提取表单字段)
- 要区分「Claude 应该直接执行的脚本」和「Claude 应该读进上下文的参考资料」
技能增加能力也增加攻击面,开发评估与来源、依赖检查要一起做。
开发最佳实践
- 从评估出发: 在代表性任务上运行 Agent 找能力缺口,增量构建技能补短板
- 为规模化组织结构: 臃肿的 SKILL.md 拆分为独立引用文档;互斥或很少一起用的上下文分开存放
- 从 Claude 的视角思考: 监控真实使用并迭代;特别注意技能名称和描述——它们决定 Claude 是否触发该技能
- 与 Claude 一起迭代: 让 Claude 自我反思失败原因,把成功方法沉淀为可复用组件——这个过程能揭示 Claude 真正需要什么上下文
安全考量
技能通过指令和代码引入新能力,也就引入攻击面:
- 只安装可信来源的技能;对不够可信的先彻底审计
- 读完所有捆绑文件、审查代码依赖和资源引用
- 警惕引导 Claude 连接不可信外部网络源的指令
现状与未来
- 已支持:Claude.ai、Claude Code、Claude Agent SDK、Claude Developer Platform
- 规划中:技能生命周期管理(创建/编辑/发现/分享)、与 MCP server 互补集成、Agent 自主创建和评估技能——让 Agent「把自己的行为模式沉淀为可复用能力」
结论
Agent Skills 用简单格式解决通用 AI 能力与领域现实需求之间的落差:把程序性知识打包成可发现、可组合、智能加载的模块。渐进式披露减少了一次性预载的上下文压力,开放标准的发布则预示更广泛的生态采纳。
✅ 检查点
- 三层渐进式披露分别是哪三层?
- 这个设计解决了什么问题?
- 写 Skill 描述时最关键的是什么?
👀 答案
- ①名称+一句话描述(常驻,极短)②完整说明文档(判断相关后才载入)③附带的脚本、模板、数据文件(真正执行时才读)。
- ⭐ 解决「能力越多、上下文越挤」这个矛盾。如果所有 Skill 的完整内容都常驻,挂十个就把上下文占满了;分层之后,常驻成本只有每个 Skill 一行描述,于是可以挂几十上百个。
- ⭐ 描述要写清「什么时候该用它」,而不是「它能做什么」。因为第一层是模型发现和初步匹配技能的重要依据,用户显式调用及当前任务上下文也会影响选择——它靠这一行决定要不要展开。写成「处理 PDF 的工具」不如写成「当需要从 PDF 提取表格或填写 PDF 表单时使用」。
本节回顾
先记住这几件事
- 简介帮助发现相关技能,正文和附件按需要展开。
- 把触发场景写得贴近用户实际表达。
- 技能不仅提供资料,还应说明执行步骤、边界和结果验收。