想让大模型在真实业务里真正干活而不是只会吐文案就得给它配一套可执行的工具。最近圈里讨论比较多的“Agent Skills”就是 Anthropic 专门为 AI 智能体设计的一套轻量级技能封装方案核心思路是把现实世界里的具体操作比如查数据库、处理表格、调用命令行、操作某个内部系统打包成标准化的技能目录让 Claude 在需要的时候自动发现、加载并调用。这和我之前折腾过的普通工具调用不太一样它更像是在教模型“分门别类地掌握技能”而不是临时塞给它一堆函数定义。这篇文章不会只堆概念我会结合自己实际调试过的案例把 Skills 的目录结构、加载机制、接口参数、多步骤推理模式以及工程化落地时容易踩的坑全部拆开讲清楚。无论你是刚开始接触 AI Agent 开发还是已经在做复杂的智能体编排这篇都能给你一些可以直接落地的参考。1. Agent Skills到底是什么从“会聊天”到“会做事的拐点1.1 传统工具调用为什么撑不起复杂任务先聊聊痛点。最早给大模型接工具大家的第一反应都是函数调用Function Calling / Tool Use比如定义几个 Python 函数把函数名、参数说明塞进请求里模型在对话中决定调哪个。这个模式本身没问题但一放到真实业务里就会发现两个麻烦第一工具越多请求体越大上下文里的 token 消耗直线上升而且模型在大量不相关的工具定义里选错函数的概率也在增加第二工具和工具之间是“平级”的没有组织关系模型不知道“先做数据清洗再做统计分析”这种流程只能靠开发者在外层硬编码流程逻辑。我最早做某个数据看板项目时给模型塞了二十多个工具定义结果模型经常把“查询用户表”和“查询订单表”搞混甚至在不需要排序的时候也强行调排序函数。后来我不得不把所有工具的说明塞进 system prompt 里做“提示压缩”效果依然不稳定。这是典型的“工具爆炸”问题——模型不是不会用工具而是工具太多、边界模糊它根本没能力在每一轮都做出精准选择。1.2 Skills如何改变组织和发现方式Agent Skills 的思路完全不同。它不再把工具定义为平铺的函数列表而是把一组相关的脚本、提示词、资源文件打包成一个带有“技能描述”的独立目录。每个技能只暴露一句话描述给模型真正的使用说明和脚本代码藏在目录内部。模型的决策流程变成了先扫描所有技能的描述确认当前任务需要哪个技能再把那个技能的完整定义加载进上下文。举一个我实测过的例子。假设我要给 Claude 配一个处理 CSV 文件的技能传统方式是把 read_csv、clean_csv、merge_csv、plot_csv 四个函数全部暴露出来模型每次都在四个函数里挑。换成 Skills 之后我只暴露一个“CSV 文件处理助手”的描述模型判定“这个任务需要处理 CSV”然后才加载完整的操作说明和脚本。这种“按需加载”的方式既减少了上下文里的噪声又让模型面对的是一个完整的工作流程而不是散装函数。提示把 Skills 理解为“模型世界的职业技能证书”更贴切。证书本身只有一句话技能描述但一旦被选中背后整套知识库、脚本、注意事项都会展开。表面上看Skills 只是把工具调用包装了一层但真正的转折点是“可组合性”。以前工具是死的函数返回什么就是什么工具之间谁先谁后完全靠开发者写死而 Skills 是一组有输入输出接口的原子模块模型可以像搭积木一样把几个技能串成一个多步骤工作流。这个能力直接决定了 Agent 能不能处理“需要多个环节配合”的现实任务而不只是单次问答。2. 核心工作原理上下文揭示机制如何让模型学会调技能2.1 先看三个关键概念技能描述、技能定义、技能使用官方文档里反复提到三个层级我一开始也觉得绕后来实际调通之后才明白它们各自的作用。理解这三个层级基本就理解了 Skills 的骨架。技能描述Skill Description一段极简的自然语言比如“帮助用户做 CSV 文件清洗与统计分析”只占据几十个 token在每次请求时都会被发送给模型。模型靠它做全局识别判断当前任务要不要用这个技能。技能定义Skill DefinitionSKILL.md 文件里的核心内容包括这个技能的完整说明、使用步骤、参数含义、输入输出格式、注意事项甚至内联的 prompt 模板。这段内容只在模型确认需要该技能后才会被加载。技能使用Skill Use模型真正调用技能定义里给出的脚本或指令。它可能是一次 Bash 命令也可能是触发技能目录下的 Python 或 JavaScript 脚本由模型根据技能的说明自主决策。我在调试过程中遇到过一种很典型的情况技能描述写得太“大”什么都能干。比如我最初把技能描述写成“处理各种格式的数据文件”结果模型在遇到图片识别任务时也尝试加载这个技能加载之后发现定义里根本没有图片处理逻辑于是不断报错。后来我把描述改成“处理 CSV、JSON、Excel 表格数据的清洗、合并与统计分析”误触率才降下来。2.2 渐进披露为什么“藏起来”反而更高效“按需加载”在官方语境里叫渐进披露Progressive Disclosure这个机制的收益在长对话里尤其明显。当上下文里挂着几十个完整工具定义时每次模型生成前都要对全部定义做注意力计算前缀填充prompt processing时间会明显变慢而 Skills 模式下模型只需要处理几十个技能描述只有在真正需要时才展开个别技能。我自己做了一个简单的统计对比。同一个任务用传统工具调用方式接 30 个工具定义模型首轮响应前平均需要 6-7 秒的思考时间改用 Skills 后相同任务只需要加载 2-3 个相关技能首轮响应时间缩短到 2-3 秒。更关键的是判断准确率明显提升模型不再纠结于“该不该调用某个无关工具”。对比项传统工具调用Agent Skills上下文中的完整定义数量全部工具常驻仅技能描述常驻定义按需加载模型首轮决策压力高容易选错低先粗筛再细选工具之间协作由外部代码编排模型可自主组合多技能token 占用随工具数量线性增长固定为技能描述的轻量开销2.3 Skills的生命周期从发现到执行的完整链路我用一个流程图式的语言来描述整个链路这样你脑子里会有一个清晰的时序用户提出任务后Claude 根据当前对话上下文和全局技能描述列表做“技能匹配”命中后系统把 SKILL.md 的完整内容注入上下文Claude 阅读使用说明并决定调用哪个脚本或命令脚本执行后把结果返回给模型模型基于结果继续对话或发起下一轮动作。这个过程中每一轮技能使用的结果都会被保留在上下文里所以模型可以即时调整策略。我特别想强调“模型阅读使用说明”这个环节。很多开发者以为模型拿到 SKILL.md 就会直接用其实模型是真的会“读”这个文件的。这意味着你的 SKILL.md 写得够不够细致、步骤够不够清晰会直接决定技能执行的成功率。有一次我在技能定义里写了一句话“如果需要清洗数据请使用 clean_data.py”但没说清洗规则是什么结果模型在遇到缺失值时自作主张填了 0整个分析结果全偏了。后来我在定义里明确写了“缺失值处理原则数值列用均值填充分类列用众数填充”情况立刻好转。3. 标准Skills目录与关键参数拆解3.1 目录结构长什么样一个标准的技能目录包含 SKILL.md 和若干配套文件。官方推荐的目录结构通常是这样的skills/ csv-toolkit/ SKILL.md scripts/ clean_data.py analyze_data.py assets/ output_template.md example_config.jsonSKILL.md 是技能的“门面”里面必须有 YAML frontmatter 和正文。frontmatter 里的字段不多但每个都会影响模型的行为。我实际用过的关键字段包括 name技能名称、description技能描述会被模型全局读取、license许可证、allowed-tools允许该技能调用的工具白名单等。正文部分则用自然语言写清楚“什么时候用、怎么用、有哪些注意点”。3.2 SKILL.md内容格式与字段含义下面是一个我会实际挂到项目里的 SKILL.md 示例骨架--- name: csv-toolkit description: 用于处理 CSV 表格数据的清洗、合并与统计分析。当你需要读取或处理 CSV 文件时使用此技能。 license: MIT allowed-tools: - Bash - Read - Write --- # CSV 数据工具箱 ## 适用场景 - 用户提供 CSV 文件需要清洗、筛选、合并或做统计计算 - 需要把多个表格横向合并或纵向拼接 - 需要输出结构化分析报告 ## 工作流程 1. 用 Bash 检查文件是否存在确认文件编码UTF-8 无 BOM 优先 2. 使用 scripts/clean_data.py 清洗缺失值和异常值缺失值处理规则数值列填均值分类列填众数 3. 使用 scripts/analyze_data.py 做分组统计输出结果到 output/ 4. 根据 assets/output_template.md 的格式汇总结果返回给用户 ## 注意 - 不要修改源文件所有清洗后的数据统一写到 output/ 目录 - 如果 CSV 文件超过 50MB先做抽样再处理我特别想说一下allowed-tools这个字段。它限制了技能内部可以调用的工具类型比如“Bash”“Read”“Write”“Edit”。这个字段的意义在于做权限收敛。我在某次测试中让一个联网抓取技能拥有了“Read 任意路径”的权限结果它在执行时去读了本机 SSH 私钥文件虽然不至于泄露但说明权限边界不清会导致模型过度调用。现在我的所有技能默认只给最小工具集能跑脚本的就不用 Write能用 Read 的就不开 Edit。3.3 脚本语言选择Shell、Python还是JavaScript官方文档里提到Claude 对四种语言特别熟练Bash、Python、JavaScript 和 Ruby。我的体会是Python 处理数据类技能最顺手Bash 适合做文件和系统操作JavaScript 适合跑在浏览器或 Node 环境里。有人喜欢全用 Bash 一行命令搞定但对复杂逻辑来说Bash 的排错体验比较差我一般把核心逻辑放在 Python 脚本里Bash 只做入口调用。举例来说清洗数据的技能内部我会写一个clean_data.py接受命令行参数而不是把逻辑都堆在 SKILL.md 里。这样做的另一个好处是脚本可以被外部直接调用技能的“核心逻辑”不依赖模型生成代码的稳定性执行结果也更可控。4. 从目录到生产Skills的编写、挂载与调用实操4.1 手写一个可用的技能文件哈希校验工具为了让你能完整走通我举个自己实际写过的例子一个本地文件哈希校验技能file-integrity-checker用于计算文件的 MD5、SHA-256并和用户提供的期望值比对判断文件是否完整。这个技能很简单但足够展示完整的编写流程。先建目录和脚本mkdir -p skills/file-integrity-checker/scripts写一个 Python 脚本scripts/hash_file.py#!/usr/bin/env python3 import argparse import hashlib from pathlib import Path def compute_hash(file_path: str, algorithm: str sha256) - str: path Path(file_path) if not path.exists(): raise FileNotFoundError(f文件不存在: {file_path}) h hashlib.new(algorithm) with path.open(rb) as f: for chunk in iter(lambda: f.read(8192), b): h.update(chunk) return h.hexdigest() def main(): parser argparse.ArgumentParser(description计算文件哈希值) parser.add_argument(file, typestr, help待计算的文件路径) parser.add_argument(--algorithm, typestr, defaultsha256, choices[md5, sha1, sha256, sha512]) parser.add_argument(--expected, typestr, default, help期望的哈希值) args parser.parse_args() actual compute_hash(args.file, args.algorithm) print(f{args.algorithm.upper()} ({args.file}): {actual}) if args.expected: if actual.lower() args.expected.lower(): print(校验结果: 匹配) else: print(f校验结果: 不匹配期望 {args.expected.lower()}) if __name__ __main__: main()再写 SKILL.md--- name: file-integrity-checker description: 计算本地文件的 MD5、SHA-256 等哈希值并与期望值比对以验证文件完整性。当用户需要校验下载文件是否损坏、或确认文件未被篡改时使用。 allowed-tools: - Bash - Run --- # 文件哈希校验工具 ## 适用场景 - 用户提供文件路径和期望哈希值希望验证文件是否损坏 - 需要快速计算文件的哈希值用于审计记录 ## 使用方法 1. 先用 ls -l file 确认文件存在且用户有权限访问 2. 调用脚本python3 scripts/hash_file.py file --algorithm sha256 --expected 期望值 3. 如果用户未给定期望值只输出哈希结果即可 4. 如果文件不存在向用户说明并提供正确的路径建议 ## 注意事项 - 不要修改目标文件内容 - 大文件超过 1GB比较慢时可以提示用户该算法需要流式读取 - 默认使用 sha256除非用户明确要求其他算法这样技能就写好了。把skills/目录放进项目根目录然后检查目录名和 name 字段是否一致即可。4.2 Agent SDK挂载与调用参数详解在 Anthropic 的 Agent SDK比如 Claude Agent SDK中挂载技能并让模型调用一般是在定义 Agent 时把skills参数传入。我习惯用 Python 来做集成演示from claude_agent_sdk import AnthropicAgent, SkillsProvider # 这里使用本地技能目录作为技能来源 skills SkillsProvider.from_directory(skills) agent AnthropicAgent( modelclaude-sonnet-4-5, name文件校验助手, skillsskills, system_prompt你是一个文件安全校验助手根据用户请求调用技能完成任务。, ) response agent.run(请帮我校验 ~/Downloads/setup.exe 的 SHA256期望值是 abc123...) print(response.text)这段代码里最关键的是SkillsProvider.from_directory。它会把skills/目录下所有技能扫描、解析成可供模型调用的格式。agent.run之后模型会自动决定要不要加载并执行file-integrity-checker技能。通过代码集成你会发现开发者不需要手动指定模型“用哪个技能”模型会依据描述自行判断这正是 Skills 设计的核心意图把“选择技能”这件事交给模型自主决策。提示SDK 还支持把技能来源配置成远程目录或挂载只读文件系统便于团队统一维护技能库。开发阶段我建议先用本地目录方便调试和迭代。我在 dev 环境实测时遇到过技能目录权限设置不正确导致 Bash 无法读取脚本的情况报错信息又不直观。排查半天才发现是用户权限问题。所以如果你遇到“技能已加载但无法执行”的问题除了看日志先检查技能目录的复制权限和脚本的可执行权限这个坑最常见也最隐蔽。4.3 模型如何决定何时使用技能很多人会问“模型为什么知道这时候该用哈希校验技能”答案就在那一行description里。模型在每轮对话开始时都会拿到所有技能的 description它会判断当前用户意图和哪个 description 匹配度最高。我这里有个小技巧description 里不要写“怎么做”只要写“什么时候用”。比如上文的描述是“当用户需要校验下载文件是否损坏或确认文件未被篡改时使用”而不是“本技能用 Python 脚本计算文件的哈希值”。前者的触发语义更接近用户的真实意图后者则在诱导模型去执行“计算哈希”这个动作而不是解决问题。5. 多步骤推理模式从“找零钱”到“拆分任务”的实测体验5.1 为什么多步骤推理对 Agent 至关重要Agent 真正复杂的任务往往不是“单次调用一个工具”而是“在多个工具之间来回切换、不断修正计划”。比如处理一个财务表格需要先读取工作表清洗数据计算汇总值再画图最后生成一段分析结论。传统工具调用模式下这些步骤之间只要任何一步失败整个流程就断了因为编排逻辑常常写在外部代码里脚本之间没有状态传递。Skills 的多步骤推理模式multi-turn reasoning让模型能够在上下文里记录“我已经做到哪一步、下一步该做什么”模型的推理结果会成为上下文的一部分继续引导下一步操作。Claude 的推理机制配合 Agent Skills形成了“计划-执行-观察-调整”的闭环。5.2 零售找零案例多个Skills如何协同用一个零售项目的真实案例来展示多技能协同。当时我做一个“自动计算找零方案”的功能用户输入购买金额和支付金额系统需要输出至少 8 种不同面额组合的找零方案比如纸币和硬币怎么搭配最合理。我把这个任务拆成几个技能汇率换算处理外币、税务计算处理不同税率下的实付金额、促销判断识别满减规则、找零优化计算面额组合。一次性把所有技能都塞给 Agent然后观察它如何组链执行。第一次实测还挺惊喜的模型读取用户消息后先调汇率换算技能确认币种再调用税务计算技能得出应付金额随后调促销判断技能确认是否有满减最后才调找零优化技能给出方案。整个过程完全自主没有外部流程编排模型内部先规划再一步步执行。这让我真正感觉到Agent 不再是“单一问答机器人”而是能像一个人一样把问题拆解成子问题再逐个击破。注意这个效果并非所有模型都能稳定复现。模型推理能力不够强时很容易在链条中途“跳步”或“忘掉”前面的结果。所以如果你要用 Skills 搭建复杂流程模型选型非常重要搭配具有较强推理能力的模型系列会稳得多。5.3 预测性执行提前开始下一步的机制在做上面的案例时我还注意到一个细节模型在推理链条较长的情况下会表现得“好像提前知道下一步要做什么”。这个能力来自 Claude 的预测性执行predictive executionPE机制——部分最新模型在推理时会并行猜测后续步骤并提前执行而不是严格等上一步结果返回后再思考下一步。我实测中最明显的体感是长链条任务里整个 Agent 的响应速度明显快于“一步一步同步执行”的版本。但这带来一个新的工程挑战如果提前执行的步骤假设错了结果需要回滚。所以如果你在生产环境里用 PE建议给每个技能的脚本设计成“无副作用或可回滚”的类型至少不要在早期步骤里写数据库或发邮件否则会很难收拾。我自己就把所有“写入型”操作都安排在链条最后一步或者额外加一个确认机制避免模型提前执行了不该执行的操作。6. 权限、版本与组织管理Skills的工程化落地6.1 技能能否调用其他技能或完整工具集这是我在技术社区里被问得最多的问题。官方设计里技能默认不能直接调用其他技能但可以通过 allowed-tools 列表访问底层工具集比如 Bash、Read、Write。也就是说“技能调用技能”不是自动的需要开发者显式地在技能体内写清楚“如果需要其他处理能力请使用 Bash 调用某某脚本”。这其实是个刻意的安全设计——防止技能之间形成不可控的级联调用。我见过有人试图写一个“万能技能”让模型基于它的说明再自动组合其他技能结果它的上下文被塞进一大堆脚本逻辑行为变得不可预测。更稳妥的做法是让每个技能保持单一职责多个技能之间的协作交给模型在对话层面的推理链条去完成而不是在技能内部互相调用。如果有强依赖关系就把依赖逻辑写成一个脚本放进技能内部的 scripts 目录比“技能调用技能”靠谱得多。6.2 许可协议与供应商锁定风险官方仓库里的技能大多带有 MIT 或其他开源许可证你在二次开发时需要保留原始许可证信息尤其在把技能重新打包或发布时。这个和普通开源代码的合规要求一样但容易因为“技能”这个概念太新而被忽略。我见过一个团队直接复制了别人的技能目录到内部项目SKILL.md 里的 license 字段还是 MIT但公司内部合规要求是 Apache 2.0最后只能逐个人工排查替换。再有一个和“锁定”相关的问题技能目录本身虽然是开放的但不同的模型服务商对“如何加载技能、技能内部可调用哪些工具”都有自己的一套接口约束。目前 Anthropic 的 Agent Skills 定义已经逐渐成为一种事实上的目录结构标准如果你在某个平台上开发的技能想要迁移到另一个平台大概率需要重写 SKILL.md 的 frontmatter 和脚本调用方式。我会建议在团队内部维护一个“技能兼容层”把脚本逻辑和模型交互部分分开这样即使换模型服务商核心逻辑也能复用。6.3 版本管理当技能逻辑和模型行为同时变化技能迭代中最麻烦的问题在于技能的脚本逻辑由你控制但“模型如何使用技能”取决于模型版本。同一个 SKILL.md在旧模型下运行得很稳换到新模型之后可能行为完全不同——比如新模型更激进地尝试并行调用多个脚本导致输出顺序不稳定。我的处理方式是给 SKILL.md 加一个version字段并在正文里标注“本技能依赖的 Claude 版本要求”。同时建议在 CI 里加一条自动化每次模型升级时跑一遍既有的技能回归用例集。我在团队里维护了一个“技能回归矩阵”用固定的输入和期望输出做断言模型升级后跑一遍全量能快速发现技能兼容性变化。这个方法听起来朴素但在生产环境里特别管用。6.4 直面比拼Agent Skills与直接SDK工具调用的定位差异很多人会纠结“我到底该用 Agent Skills 还是直接在 SDK 里传 tools”。两者不是替代关系而是不同抽象层级。直接传 tools 适合场景简单、工具数少、交互固定的小型 AgentAgent Skills 适合工具数量多、需要组合、需要上下文友好的大型项目。最理想的做法是两者结合把 Skills 作为“技能模板”把直接工具调用作为“原子操作”。我在团队里的标准是少于 5 个工具、工具之间几乎不互相依赖就直接传 tools工具数量超过 10 个或存在明显工作流就立即切换到 Agent Skills。场景直接传 toolsAgent Skills工具数量 5推荐可不用工具数量 10上下文拥挤不推荐推荐需要模型自主编排流程困难天然支持需要精细控制每一步参数容易需要描述清晰多环境复用同一套能力需要重复定义目录级复用7. Skills会如何重塑AI应用生态横向对比与趋势7.1 与MCP边界的思考谁负责连接谁负责干活MCPModel Context Protocol和 Agent Skills 很容易被搞混。我个人的理解是MCP 解决的是“Agent 如何连接外部世界”提供的是标准化的工具服务接口和上下文传输协议Agent Skills 解决的是“Agent 如何组织自身能力”提供的是技能的定义、发现和加载机制。两者可以共生——MCP 服务器把一个内部系统暴露成工具Agent Skills 把一组工具的使用方法封装成一份模型能直接阅读的说明书。实际项目里它们的边界会变得比较模糊。比如一个带数据库查询能力的技能它内部通过 MCP 连接器访问数据库技术上完全可行。但从组织视角看我会建议 MCP 层收敛为“数据访问层”Skills 层收敛为“任务执行层”。这样权限控制更清晰调试也更快。7.2 与OpenAI类功能调用的对比思考OpenAI 的功能调用走了另一条路线开发者定义结构化 JSON schema 的工具列表模型在输出中指名调用某个 tool。这条路线的优点是参数结构强约束适合需要严格入参的业务逻辑缺点是上下文随工具数量线性膨胀且必须由开发者预先写好所有可能的调用路径。Anthropic 的 Agent Skills 更强调“自由解释与渐进披露”。模型读到的是自然语言说明它可以在技能边界内先规划再执行。这带来更高的灵活性和更强的容错性但也意味着“结果可预测性”下降。我的判断是如果你的业务场景是高度结构化的比如支付回调、订单状态机优先用强约束的功能调用如果你的场景偏探索型比如数据分析、自动化运维Agent Skills 更合适。7.3 技能生态从闭门工具到开放市场技术社区已经开始出现“技能市场”的苗头开发者在公开仓库里分享自己做好的技能目录比如 Git 仓库、打包下载、一键导入到 Agent 环境。我个人的看法是技能生态能不能火起来取决于两个因素一是技能描述的质量是否稳定描述质量直接决定模型触发准确率二是技能之间是否形成可组合的标准接口。生态很早期但方向是对的。站在开发者的角度现在入场积累几个高质量技能相当于早期做 WordPress 插件——先吃螃蟹的人会有明显的红利。7.4 什么时候不该用Agent Skills最后说点反常识的。Agent Skills 也不是灵丹妙药。我踩过的坑包括为一个本来 30 行代码就能解决的简单工具写了完整的 SKILL.md结果模型每次都要先“读说明”再执行延迟反而更高又或者技能描述写得太宽泛模型频繁误触发导致非预期行为。如果任务本身很单一、输入输出非常固定直接写一个普通工具定义或函数调用就好别为了“架构好看”而过度设计。我现在的选择标准很简单技能至少包含两个以上操作步骤或者需要多轮任务规划时才值得做成 Skill。回到文章最开始的问题——为什么 Agent Skills 是 Agent 从“会聊天”到“会做事”的拐点因为它把“能力描述”和“能力实现”分离了。模型只需要知道“这是什么、什么时候用”具体怎么实现藏在技能目录里按需展开。这个设计看似简单却解决了工具爆炸、上下文膨胀、流程编排方式陈旧这几个长期卡住 Agent 落地的老问题。最后再分享一个实操上的小建议不要一上来就追求庞大的技能库。挑一个你日常业务里最频繁、最模式化的任务比如“处理上传文件”“生成周报”“校验配置”先做成一个技能跑通全流程再逐步扩展。你会发现当模型手里有一套趁手的“工具组合”它处理复杂任务的稳定性和效率会远超你的预期。