🏠 总目录 📚 资料库智能体技能

用 Agent Skills 装备现实世界的 Agent

⏱ 12 分钟 | 🎒 三层渐进式披露

🎯 一句话

Skill 的核心机制是三层渐进式披露:先给一行描述、需要时展开说明、真正用到才加载资源。⭐ 这让上下文只为「当下真正用得上的东西」付费。

本页先解决:技能简介、正文与附件分别何时加载?

Claude 博客资料库 · 智能体技能

技能简介、正文与附件分别何时加载?

技能包里有什么,与当前轮次加载了什么是两回事;先看三层披露的触发条件。

读完可以:辨认技能简介、正文和附件的加载触发与执行风险。

加载由需要触发

  1. 先读元数据名称与描述帮助判断技能是否相关
  2. 适用时读正文选中后加载 SKILL.md 核心说明
  3. 需要时读附件只取当前任务需要的参考文件或资源

脚本执行与参考资料读取分开:代码能力仍须来源审查与权限边界。

原三层披露机制的概念图,不表示必须把整个技能包逐层读完,也不表示所有被引用代码都应自动运行。
📄 来自 Claude 官方博客
原文标题
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 格式与渐进式披露

结构

SKILL.md 以 YAML frontmatter 开头,至少包含 name 和 description。

三层信息架构

  1. 第一层(系统提示词): 仅预载技能元数据(名称+描述),让 Claude 能识别何时相关,而不加载全文
  2. 第二层(核心内容): Claude 判断技能适用时才加载 SKILL.md 正文
  3. 第三层及以上(补充文件): SKILL.md 中引用的其他文件(如 reference.md、forms.md)只在具体需要时加载

PDF 技能示例

Claude 理解 PDF 概念但缺乏直接操作能力。PDF 技能捆绑:核心 SKILL.md(表单填写概览)+ forms.md(详细填表指令)+ reference.md(通用 PDF 操作)+ 用于确定性提取表单字段的 Python 脚本。核心保持精简,按场景定向加载。

为什么渐进式披露是核心设计原则

像一本组织良好的手册(目录、章节、附录),Claude「只在需要时加载信息」。具备文件系统和代码执行能力的 Agent 不需要把整个技能装进上下文——技能包可大于单个上下文窗口,但每次读取仍受窗口、检索质量与执行预算限制。

读取参考资料与执行脚本职责不同;不要把整个技能包都视为提示词文本。

上下文窗口的工作机制

  1. 初始上下文:系统提示词 + 所有技能元数据 + 用户消息
  2. Claude 用 Bash 工具读取 pdf/SKILL.md 触发技能
  3. 按需选择性读取捆绑文件(如 forms.md)
  4. 用加载的技能指令执行用户任务

技能与代码执行

技能可捆绑可执行代码,Claude 自行决定何时使用:

技能增加能力也增加攻击面,开发评估与来源、依赖检查要一起做。

开发最佳实践

  1. 从评估出发: 在代表性任务上运行 Agent 找能力缺口,增量构建技能补短板
  2. 为规模化组织结构: 臃肿的 SKILL.md 拆分为独立引用文档;互斥或很少一起用的上下文分开存放
  3. 从 Claude 的视角思考: 监控真实使用并迭代;特别注意技能名称和描述——它们决定 Claude 是否触发该技能
  4. 与 Claude 一起迭代: 让 Claude 自我反思失败原因,把成功方法沉淀为可复用组件——这个过程能揭示 Claude 真正需要什么上下文

安全考量

技能通过指令和代码引入新能力,也就引入攻击面:

现状与未来

结论

Agent Skills 用简单格式解决通用 AI 能力与领域现实需求之间的落差:把程序性知识打包成可发现、可组合、智能加载的模块。渐进式披露减少了一次性预载的上下文压力,开放标准的发布则预示更广泛的生态采纳。


✅ 检查点

  1. 三层渐进式披露分别是哪三层?
  2. 这个设计解决了什么问题?
  3. 写 Skill 描述时最关键的是什么?
👀 答案
  1. ①名称+一句话描述(常驻,极短)②完整说明文档(判断相关后才载入)③附带的脚本、模板、数据文件(真正执行时才读)。
  2. ⭐ 解决「能力越多、上下文越挤」这个矛盾。如果所有 Skill 的完整内容都常驻,挂十个就把上下文占满了;分层之后,常驻成本只有每个 Skill 一行描述,于是可以挂几十上百个。
  3. ⭐ 描述要写清「什么时候该用它」,而不是「它能做什么」。因为第一层是模型发现和初步匹配技能的重要依据,用户显式调用及当前任务上下文也会影响选择——它靠这一行决定要不要展开。写成「处理 PDF 的工具」不如写成「当需要从 PDF 提取表格或填写 PDF 表单时使用」。

本节回顾

先记住这几件事

  • 简介帮助发现相关技能,正文和附件按需要展开。
  • 把触发场景写得贴近用户实际表达。
  • 技能不仅提供资料,还应说明执行步骤、边界和结果验收。