我见过太多人把大模型接到项目里最后却卡在同一个地方模型很聪明问什么都能答但让它去干一件具体的事它就愣住了。你说帮我把临时目录清理一下它能给你写出一篇三百字的《临时文件清理指南》但绝不会真的去动磁盘上的一个文件。问题不在于模型不够聪明而在于我们只给了它一个会说话的大脑没给它一双会干活的手。这双手就是今天要聊的agent-skills。这篇文章不是什么框架的官方文档解读而是我从实际项目中拆出来的、关于如何给智能体定义技能、打包技能、编排技能的一整套工程思路。不管你是做 AI 应用的开发者还是想在自己的业务系统里接入 Agent 能力的产品经理这篇文章能帮你把让 Agent 干活这件事从玄学变成工程。1. 为什么大模型干不了细活Agent Skills要解决的四个问题1.1 先看三个真实场景我在之前的项目里接过三个典型的诉求你可以对照感受一下。第一个诉求运营同学让 AI把下载文件夹整理一下。模型回复了一大段关于文件分类的建议还贴心地列出了十条最佳实践。可问题是运营同学想要的是下载文件夹真的被整理好而不是再收到一篇建议书。第二个诉求让 AI 每天早上抓取竞品官网的价格变动。第一天它做到了第二天它忘了第三天你再问它它礼貌地道歉并重新执行了一遍。它没有每天早上主动做的能力因为所有执行都依赖用户先发起对话模型本身没有挂钟和闹铃。第三个诉求让 AI 调用公司内部的订单查询接口。结果模型把接口文档里的字段名记混了把order_id写成了orderId而接口文档里明明写得清清楚楚。这件事很讽刺——模型不是不会查文档而是它在记忆文档内容这件事上天然不可靠。这三件事的共同点是什么它们都没难在语言理解而是难在模型没有和外部世界打交道的通道。模型只能输出文本文本不会自动变成文件操作、API 调用、定时任务。这就是第一个认知想让大模型干活必须先给模型接上外部世界的执行接口然后把怎么用这些接口封装成模型看得懂、调得动的单元。1.2 Agent Skills拆掉了哪四堵墙我在实际项目里反复踩坑之后把模型干不了活的问题归纳成四堵墙而 agent-skills 这类的技能机制恰好把四堵墙挨个拆掉了。第一堵墙是上下文窗口。一个稍微正式的流程从读取数据到清洗到写入如果把每一步的规则都写进系统提示词Prompt 能撑到上万字既浪费 token效果也不好。模型在长文本里容易迷失重点前面的规则到后面就记不住了。技能机制把流程拆分到独立单元每个单元只需要关注自己的输入输出上下文压力瞬间变小。第二堵墙是幻觉。让模型凭理解执行一个多步流程它很容易在中间某一步自由发挥编出一个不存在的函数名或者凭空捏造一个执行结果。但如果让模型先去匹配技能再把参数传给技能由技能里的确定性代码去执行模型插手的空间就被压缩到了参数抽取这一步幻觉的影响面大幅缩小。第三堵墙是缺执行通道。纯文本输出只能是建议技能可以捆绑真实代码Python 脚本、Shell 命令、HTTP 请求什么都能做。技能一旦触发执行的是真实代码产生的是真实结果。第四堵墙是不可复用。没有技能机制的时候每接一个新场景都要重写一堆 Prompt而且不同场景之间的能力无法共享。技能的本质是能力打包今天给 Agent 装上一个发邮件的技能明天另一个项目要用直接复用同一个技能包就行不需要从零再攒一套提示词。1.3 Skills与Tools、Function Calling、插件到底有什么区别很多人在概念上容易混淆我用自己的理解给你区分一下。Function Calling 是模型层面的能力指的是模型在输出时可以从预设的函数列表里挑一个函数并生成调用参数。它解决的只是模型如何表达要调用哪个函数函数本身是什么、怎么执行它不太管。Tools工具是一个更大的筐函数可以算工具API 也能算工具凡是 Agent 能调用的外部能力都能叫工具。但工具的粒度通常很细一个工具往往只对应一个动作。插件Plugin则侧重宿主程序加载的扩展模块通常还包含 UI 层面的东西比如用户在界面上看到一个新功能面板。Agent Skills 的粒度介于工具和完整应用之间它更强调完整的任务闭环一个技能不仅包含调用哪个函数还包含什么时候该触发参数怎么抽取执行失败怎么回退结果以什么格式返回。说人话就是工具是零件技能是组装好的组件给你一堆零件你未必能装出个东西但给你一个组件你直接往机器上一装就能用。提示如果你在团队里推动 Agent 落地建议统一采用技能这个粒度作为能力封装单位。它比裸函数更容易管理比完整应用更轻量是最适合复用和编排的中间层。2. 技能包的核心构成从识别意图到执行动作的完整闭环2.1 一个技能四块积木我在设计技能格式时参考了很多社区实践最后沉淀成四个核心组成部分触发条件、输入参数、执行逻辑、反馈输出。触发条件解决的问题是什么时候该用这个技能。对于模型来说触发条件就是技能描述description模型读到描述才知道当前用户请求是否匹配这个技能。输入参数解决的是干活需要哪些信息比如清理临时文件需要知道路径、时间阈值执行逻辑是真正干活的代码反馈输出决定干完活之后如何向模型/用户汇报结果。用一个生活化的类比技能就像公司里的岗位说明书。岗位说明书上写着岗位职责触发条件、任职要求输入参数、工作流程执行逻辑、汇报对象反馈输出。有了这份说明书一个新员工模型看到任务来了才知道该找谁、怎么干、干完跟谁说。2.2 最简技能长什么样先给你看一个最简单的技能定义功能是清理指定目录下的临时文件。这个技能用 YAML 描述元信息用 Python 写执行逻辑是最常见的方式。你可以把它当作 hello world 来理解。name: temp_cleaner description: 当用户要求清理临时文件、释放磁盘空间、删除指定目录下的缓存时使用。 适用于临时目录、缓存目录、下载目录中的过期文件清理。 如果用户没有明确目录和时间询问后再执行。 version: 1.0.0 params: - name: target_dir type: string description: 要清理的目标目录绝对路径 required: true - name: older_than_days type: integer description: 仅删除最后修改时间超过该天数的文件 required: false default: 3# main.py import os import time from pathlib import Path def run(params): target_dir Path(params[target_dir]) older_than_days params.get(older_than_days, 3) if not target_dir.exists(): return {status: failed, message: f目录不存在: {target_dir}} cutoff time.time() - older_than_days * 86400 removed 0 for item in target_dir.iterdir(): if item.is_file() and item.stat().st_mtime cutoff: item.unlink() removed 1 return {status: ok, removed: removed, target_dir: str(target_dir)}这个技能的逻辑很简单接收参数检查目录是否存在遍历文件把超过时间阈值的删掉最后返回一个结构化结果。注意我特意把结果做成了结构化 JSON而不是人类可读的句子。理由是模型拿到结构化结果之后可以根据上下文翻译成任何语气、任何语言的回复灵活性更高。2.3 技能描述是写给模型看的不是写给用户看的这是我在实际项目里踩得最狠的坑之一。很多开发者写技能描述时会下意识地站在人的角度写比如description: 清理临时文件的技能这种描述对搜索引擎没问题但对模型来说基本没用。大模型在匹配技能时依赖的是语义相似度它需要从描述里明确知道什么情况下该选我。我改成下面这样之后触发准确率立刻上了一个台阶description: 当用户抱怨磁盘空间不足、系统变慢或明确要求清理临时文件、清缓存、 删除下载目录中不再需要的文件时使用本技能。 不要用来删除用户主动指定的业务数据文件。这段描述里包含了三样东西触发场景的列举、动作的常见说法清理/清缓存/删除、负面约束不要用于哪些场景。别小看最后一条负面约束它能把很多误触发挡在门外。提示写完技能描述后你可以做一个自检——把描述给另一个同事看让他假装自己是模型问他看到什么用户请求时会触发这个技能。如果他回答的场景跟你预期不一致说明描述还得改。3. 从零定义并注册一个技能完整的实操路径3.1 第一步技能形态选型不是所有技能都要写代码。我在项目里把技能分成三种形态各有各的适用场景。第一种是纯提示词技能。不需要代码只靠一段精心设计的 Prompt 配合模型自有能力完成适合总结、改写、抽取、格式转换这类不依赖外部系统的任务。优点是零成本缺点是能力边界模糊同一个 Prompt 换一批输入可能表现漂移。第二种是代码技能。封装真实函数调用适合操作文件、请求 API、读写数据库、跑数据脚本。确定性最高可测试性最强是技能体系的主力。第三种是混合技能。先让代码做数据获取和处理再让模型基于结果做润色或总结。适合抓取数据并生成报告这类端到端任务。我给新项目的建议是优先用代码技能。因为代码技能的边界最清晰输入什么、输出什么、失败抛什么错都是可预测的测试起来也最简单。纯提示词技能虽然省事但出问题的时候排查成本很高因为你不确定模型会在哪一步灵机一动。提示如果你的 Agent 只在纯文本环境跑且任务简单稳定纯提示词技能够用只要涉及文件、网络、数据就老老实实上代码技能别图省事。3.2 第二步搭一个标准的技能包目录我习惯用一个统一目录结构来组织所有技能。这个结构不是某家公司的标准而是我在多个项目里磨合出来的你也可以改成适合自己的但核心思路值得借鉴。skills/ temp_cleaner/ SKILL.md main.py requirements.txt weather_query/ SKILL.md main.py requirements.txt report_generator/ SKILL.md main.py requirements.txt每个技能一个文件夹里面必须有一个SKILL.md作为技能说明书就是上一节那个 YAML 的完整版可以多写一些使用案例main.py是执行入口requirements.txt是依赖清单。这个目录有两个好处。第一技能按目录隔离依赖互不污染第二你可以通过 git 对每个技能单独做版本管理哪个技能出问题回滚就回滚那个目录不影响其他技能。3.3 第三步注册到 Agent 运行时注册方式取决于你用的 Agent 框架但思路大同小异让运行时扫描技能目录读取每个SKILL.md把技能的描述和参数 schema 注册到模型的工具列表或技能列表里。我常用的注册方式是这样几行代码示意如下from pathlib import Path def load_skills(skills_dir: Path): skills [] for skill_dir in skills_dir.iterdir(): skill_md skill_dir / SKILL.md main_py skill_dir / main.py if skill_md.exists() and main_py.exists(): skills.append({ dir: skill_dir, meta: parse_skill_md(skill_md), entry: main_py, }) return skills注册之后Agent 运行时在每一次请求进来时会把所有技能的 description 和参数 schema 提供给模型。模型根据用户请求和这些描述决定调哪个技能、填什么参数。整个过程是动态的你往技能目录里丢一个新技能包重启或热加载之后Agent 就自动获得了新能力。3.4 第四步用最少成本做端到端验证注册完不算完我每次加新技能都会强制跑三个测试。测试一直接调用技能入口绕过模型。传入构造好的参数看代码是否正常执行、返回结构是否符合预期。这一步能筛掉大部分代码层面的低级错误。测试二通过模型触发技能。给 Agent 一句自然语言指令比如把 /tmp/cache 目录下三天前的临时文件清理掉看模型能不能正确识别技能、抽取参数。这一步验证的是描述写得够不够清楚。测试三故意给模糊请求。比如只说帮我清理一下看模型是直接拿默认参数执行还是主动反问确认目录。我个人的预期是应该先问清楚因为删除操作不可逆鲁棒性比效率更重要。这三个测试跑下来一个技能能不能上线基本心里就有数了。4. 技能编排与组合单个技能是零件组合起来才是 Agent4.1 为什么单个技能不够用单个技能的能力边界必须小越小越不容易出错越好测试。但用户的实际需求通常是复合的比如每天早上给我一份竞品价格变动摘要。这个需求至少可以拆成三步抓取竞品页面数据爬虫技能、清洗提取价格信息数据处理技能、生成摘要并推送报告推送技能。如果把这些步骤全塞进一个大技能里那这个技能会越来越膨胀最终变成一团没人敢动的意大利面。正确的做法是保持每个技能单一职责然后用编排层把它们串起来。这是我在项目里反复体会到的技能负责正确地做事编排负责做正确的事。4.2 三种常用的编排模式我在实践中沉淀了三种编排模式覆盖了大多数场景。线性编排最直观一个接一个执行前一个的输出作为后一个的输入。比如查询订单状态 → 生成物流信息 → 推送给用户就是一条直线。适合流程固定、步骤明确的场景。条件分支编排要依赖某个技能的输出结果做判断比如先检查用户是否VIP是就走专属客服流程不是走默认流程。这种编排下技能之间不只是串联还有决策节点。并行聚合编排适合多个独立数据源同时拉取的场景。比如同时抓三个竞品网站各自抓完再汇总分析。并行能显著缩短耗时但要留意对数据源接口的并发压力。我用自己的项目举个例子。做一个竞品监控日报的复合能力编排长这样定时触发 - 并行执行 [抓取A站价格, 抓取B站价格, 抓取C站价格] - 数据清洗与比对找出变化超过5%的商品 - 生成日报摘要 - 推送到企业微信群每个环节对应一个独立技能任何一步出问题只需要替换或修复那一个技能整条链路其余部分不受影响。4.3 状态与回退编排里最容易翻车的环节把技能串起来之后你会发现真正难的不是调用而是失败处理和状态传递。技能之间的数据以什么格式传是第一个要定的规矩。我在项目里统一用 JSON 作为技能间通信格式。理由很简单JSON 有 schema 可以校验模型容易理解而且几乎所有语言都有成熟解析库。第二个是失败回退策略。我给每个技能都定了重试上限和失败降级方案。比如爬虫技能第一次超时重试两次每次间隔 5 秒如果还失败就从缓存里取上一次结果并在日报里打上数据可能滞后的标记。这样的降级策略比直接报错友好得多。下面是我常用的策略表你可以直接抄作业故障类型重试次数超时时间失败后的行为网络超时210秒使用缓存数据并标记滞后接口返回错误15秒跳过该数据源记录日志参数校验失败0-返回错误码交由编排层决策技能代码异常130秒捕获异常返回可读错误信息关键是一个技能失败不能把整条链路全部卡死。好的编排一定能做局部降级同时把哪里降级了、为什么降级明明白白地反馈给最终用户。5. 落地时最容易翻车的五个细节5.1 技能描述写得太文艺模型识别不准我在第三节已经立了一个样板这里补充一个反面案例。我见过有人把查天气技能描述写成感受窗外云卷云舒为你带来天空的讯息。这种描述在模型眼里跟诗词鉴赏差不多触发率极低。技能描述要的是精确、可枚举、可判断不是文采。动词开头、列出场景、写明边界这三条做到了描述就合格了。5.2 权限边界设得太宽出了事故难追溯Agent 技能如果直接拿到完整 Shell 权限或者数据库的 root 账号那等于给一个不可控的执行器开了无限通行证。我的原则是最小权限技能只拿到完成工作所需的最小目录/接口权限运行账号单独建不能复用管理员账号。比如清理文件的技能我在实际部署时给它限定只能操作/tmp下的目录通过白名单路径校验其他路径一律拒绝。权限不是说防模型而是防技能代码本身有 bug 导致误删——代码是人写的终究会出错权限边界是最后一道防线。5.3 状态丢失技能执行完Agent 就失忆了默认情况下Agent 是无状态的。技能执行完返回结果然后一切归零。但很多任务天然依赖状态比如对比昨天和今天的抓取结果如果昨天的结果没存下来今天的技能拿什么比解决思路有两类。一类是把状态持久化到外部存储技能执行前先去读历史状态执行后再把新状态写回去。另一类是让技能自己带幂等性执行结果只依赖当前入参不依赖历史。两者不冲突优先追求技能幂等幂等不了的场景再把状态外置。5.4 测试只测正常的路径一到边界就崩技能测试最忌讳只测 happy path。我给技能写测试时会刻意构造四类输入正常输入、边界输入、错误输入、无权限输入。表格可以快速列一下测试类型输入示例预期行为正常路径合法的目录路径、合理的时间阈值正常清理且返回 removed 数量边界输入空目录、0天阈值、超大路径字符串系统不崩溃返回合理提示错误输入目录不存在、参数缺失返回结构化错误信息无权限输入受保护目录、只读文件跳过或报错不得提权边界输入最容易暴露问题。比如空目录时遍历逻辑能不能直接返回 0超大路径字符串会不会撑爆日志这些看似无关紧要的细节往往决定了线上能不能扛住真实流量。5.5 日志与可观测性AI Agent 排查问题比传统应用难十倍传统后端排查问题链路是请求 → 服务 → 数据库每跳都有迹可循。Agent 技能栈的链路是用户请求 → 意图路由 → 技能匹配 → 参数生成 → 技能执行 → 结果反馈每一跳都可能出错而且中间还夹着模型的不确定性。所以日志记录得格外完整。我给每个技能调用都至少记录五样东西用户原始请求、匹配到的技能名称、模型生成的参数、技能执行的返回结果、整体耗时。这五样数据是事后排查事故的全部依据。提示有条件的话把技能的每次调用都落一份独立的调用日志别混在应用主日志里。技能调用的频次高、字段结构固定独立存储能让你快速做统计分析比如哪个技能触发最频繁哪个技能平均耗时最长哪个技能失败率最高这些数据直接决定下一步优化方向。我在实际项目里踩过最疼的一次坑是有一个技能在线上偶尔失败但复现概率极低。当时日志没记参数排查了三天都没头绪。后来补上了参数日志第二天就发现是某些用户传来的路径里包含中文而执行脚本没有处理编码问题。就这么简单的一个 bug因为日志缺失浪费了三天时间。从那以后我把参数全量落日志定成了所有技能的硬性要求。如果你正准备在自己的项目里引入 agent-skills 这套思路我的建议是从一个最小的闭环开始先做一个代码技能跑通注册、触发、执行、返回的完整链路再逐步叠加编排和回退策略。等你把第一个技能端到端跑顺后面扩展就是水到渠成的事。