近两年只要在搞大模型应用基本绕不开一个词Agent。而我在本地搭建并维护了一个叫agent-skills的项目之后最大的感受是----大家平时聊 Agent 时都喜欢强调模型推理、记忆、规划但真正让 Agent 从“聊天机器人”变成“能干活的人”靠的反而是那些不起眼的“技能”。项目本身不复杂核心就一件事把大模型代理能够执行的操作封装成一套结构化的、可复用、可测试的“技能包”。这些技能包不是传统意义上的 API 封装也不是简单写一段 Python 函数给模型调用而是把“触发条件 操作手册 工具脚本 验证方式”打包在一起让代理在遇到任务时像人一样翻说明书、调工具、完成任务。这篇文章会把这套技能体系的设计思路、文件结构、实操写法、踩坑记录和排查经验完整拆开适合正在做 Agent 应用、被 Prompt 越写越长折磨、或者刚准备把工具调用体系化沉淀下来的同学参考。1. 先从“工具”聊到“技能”一次认知上的转向1.1 工具调用的粒度困局做 Agent 的第一阶段大家都会引入 Function Calling或者给模型注册一堆 Tools。注册一个搜索引擎、一个计算器、一个查天气的接口模型可以根据用户问题去选择。但这套方案用一段时间就会撞墙墙的名字叫“粒度”。举个例子。你要让 Agent 帮你整理一周的周报如果按工具思维拆得拆出“读取员工排期”“读取本周提交记录”“读取项目进度”“生成 Markdown 文档”“发送到指定频道”五六个工具。模型不仅要学会在什么时候调哪个还得记住每个工具的参数格式Prompt 里稍不留神就写进一堆工具描述token 占用上去了模型还经常选错工具。这就是典型的“工具粒度太碎”问题。人的工作方式是老板说“整理周报”你不需要从“打开文件”“选中所有行”“复制”这种操作粒度开始思考你脑子里直接涌现的是一套完整动作。技能就是为了复刻这个“涌现”过程而生的。1.2 技能是一次完整的“行为封装”在agent-skills项目里一个技能被定义成三样东西的组合一个清晰的触发场景、一份写给模型看的操作说明、一组负责执行的具体脚本或命令。还是周报的例子我不再提供五个分散工具而是提供一个名为weekly_report的技能包。模型看到用户说“汇总下周报”会直接选择这个技能。技能内部自己知道先从数据库里取排期再从 Git 提交记录里提取本周 commit再按项目维度聚合最后输出格式化的 Markdown再调用 Webhook 发到通知群。对模型来说它不需要关心技能内部的实现细节只需要理解什么场景该调用、调用后能得到什么结果。这大大降低了模型的决策负担也减少了因为多工具组合带来的中间状态判断失误。技能本质上把“多次工具选择”变成“一次技能选择 内部确定性流程”把不确定性往模块内部压把确定性暴露给模型。1.3 技能体系的适用与不适用这套方式并不适合所有场景。如果你的任务是一次性的、没有复用价值写技能就是过度设计。真正适合沉淀成技能的是那些频率高、流程稳定、输入输出边界相对清晰的任务。判断标准也很简单问自己三个问题这个任务过去两周遇到过几次每次处理步骤是否高度相似能否用文本说明写出一个陌生人也能照做的流程三个问题都是“是”那就该把它从 Prompt 里的一段描述升级成一个正式技能。这套体系最合适的用户是把 Agent 从“试用阶段”推向“生产阶段”的开发者以及要在团队中维护标准化 Agent 能力的团队。相反如果你每次任务都是全新的、开放式的探索那么直接让模型自由调用工具反而更合适。2. 拆开一个技能包内部结构到底是什么2.1 说明书是技能的灵魂SKILL.md整个技能包最重要的文件不是代码而是一份SKILL.md。这份文件是写给模型读的说明书。很多项目不重视它把大量篇幅花在代码实现上结果模型压根不知道你这个技能是干嘛的自然也不会触发。连“用不起来”这关都过不了代码写得再好都是零。SKILL.md在我看来至少要包含四个段落技能名称与一句话简介让模型在工具列表里一眼明白这是什么。触发场景When to Use这段特别关键要告诉模型什么用户意图下应该使用本技能。写具体一点宁可啰嗦也别抽象。工作流程Workflow执行时按什么顺序做哪几步每一步大概做什么。输入输出格式需要什么参数执行完会返回什么结构。写这份文件的核心原则是把模型当成一个“聪明但没见过世面的实习生”。它很聪明但确实不知道你们公司内部说的“周报”包含哪些字段不知道“排期紧张”在数据上意味着什么。这些场景知识必须通过说明书显式传递。2.2 真正干活的引擎脚本与命令技能的执行主体是一段或几段可执行命令。在agent-skills项目中我默认以 Python 为主因为生态全、黏合各种系统方便但这并不意味着只能用 Python。Shell 脚本、Node 脚本、甚至一个可执行 Jar只要能在被调用的机器上稳定运行都能作为技能引擎。这里有个设计原则技能内部尽量做“确定性操作”不要引入无关的大模型调用。因为技能被调用的前提是场景适配一旦进入技能流程每一步都应该产出可预期结果。比如周报聚合技能内部可以写死“按 commit 的日期分组”“按文件的目录推断项目模块”这些逻辑用普通代码写即可不需要模型二次思考这样既快又省 token且可测试。2.3 依赖描述与运行环境技能包不能只有一个主脚本就完事。它得有依赖清单、运行环境说明、外部配置要求。这部分的格式我推荐参照开源项目的标准布局使用requirements.txt或package.json声明依赖用一个README记录人工维护时需要注意的场景再配一个可选的config.json放局部配置。为什么依赖和运行环境要单独拎出来因为 Agent 在生产环境中经常需要并发调用技能如果你一个技能里直接pip install了带着冲突的依赖很可能把一整台服务器搞挂。技能一旦被打包环境问题就会从“开发问题”变成“故障问题”所以我在项目里强制要求每个技能包自带美化的虚拟环境方案或者至少声明依赖时不要装那些重型的机器学习库。2.4 一个技能的典型目录布局一个 Mini 技能包实际长这样skills/ weekly_report/ SKILL.md src/ main.py collector.py formatter.py requirements.txt config.json tests/ test_collector.py目录的边界就是职责的边界。SKILL.md负责把行为描述喂给模型src/承载真正执行逻辑tests/用来保证改造时不会破坏原有行为。这种布局和微服务里的“一个服务一个代码库”很像技能包之间的耦合越低后续维护就越轻松。3. 从零手写一个可用技能实操全过程记录3.1 场景选择做一个“跨日排期冲突检查”技能空谈理论没有意义我直接拿最近在项目里做的一个技能举例。业务背景是客服团队每天会在共享表格里更新各人工位的排班表格里只记录开始时间和结束时间。原来的流程是主管人工检查是否有跨日、是否有重叠费时且容易漏。于是我在agent-skills里加了一个技能叫shift_conflict_check。它的价值主张非常聚焦检查一批站牌时间记录返回冲突清单。用户对 Agent 说“帮我看看这周排班有没有问题”Agent 就把这个技能调起来。3.2 一步步定义说明书写SKILL.md的过程中我实际用的是一份接近下面结构的模板--- name: shift_conflict_check description: 检查人员排班记录检测跨日问题与时间重叠问题。 when_to_use: 用户提供排班表格或时间区间列表要求检查冲突或确认排班是否健康时。 workflow: 1. 从用户输入或指定文件中提取排班记录。 2. 统一时间格式为 ISO8601 字符串。 3. 对每条记录检查结束时间是否小于开始时间异常、大于次日 6 点跨日。 4. 将所有记录按人员分组检测区间是否有重叠。 5. 返回冲突列表未发现冲突时返回 empty_conflicttrue。 input_format: schedule: - person: string start: string (YYYY-MM-DD HH:mm) end: string (YYYY-MM-DD HH:mm) output_format: conflicts: - type: string (OVERLAP 或 CROSS_DAY) person: string start: string end: string reason: string empty_conflict: boolean参数里的when_to_use写得比很多项目都要细致我在包含特定判断条件。因为这个技能的目标场景是排班检查如果不写明“用户可能直接贴表格、也可能上传文件名”模型拿到用户消息时就不太敢触发。说明书本质上是在教模型“把模糊的用户意图映射到精确的技能含义上”。3.3 写执行脚本的两个代码细节执行逻辑用 Python 写核心函数是把输入记录转为时间对象然后两两比较重叠。from datetime import datetime, timedelta def detect_conflicts(records): conflicts [] for r in records: start datetime.fromisoformat(r[start]) end datetime.fromisoformat(r[end]) # 异常记录结束早于开始 if end start: conflicts.append({ type: INVALID_RANGE, person: r[person], start: r[start], end: r[end], reason: end time earlier than start time }) # 跨日检查结束时间晚于次日 6 点 next_day_six (start timedelta(days1)).replace(hour6, minute0) if end next_day_six: conflicts.append({ type: CROSS_DAY, person: r[person], start: r[start], end: r[end], reason: shift crosses next day early morning }) # 重叠检查按人员分组 by_person {} for r in records: by_person.setdefault(r[person], []).append(r) for person, person_records in by_person.items(): sorted_records sorted(person_records, keylambda x: x[start]) for i in range(len(sorted_records) - 1): cur_end datetime.fromisoformat(sorted_records[i][end]) next_start datetime.fromisoformat(sorted_records[i 1][start]) if cur_end next_start: conflicts.append({ type: OVERLAP, person: person, start: sorted_records[i 1][start], end: sorted_records[i 1][end], reason: overlap between consecutive records }) return {conflicts: conflicts, empty_conflict: len(conflicts) 0}这里有两个容易被忽略的点。第一跨日判断我用的是自定义规则“次日 6 点”而不是判断“是否跨越零点”。因为客服班次经常有晚班到凌晨 1 点、2 点的情况那种跨零点但没到早晨根本不算异常。规则必须贴合业务技能的价值恰恰在于把这些隐性业务规则显性化。第二重叠检测用“按开始时间排序后逐个比较”而不是“双层循环全量比较”。两条记录如果 A 的结束时间早于 B 的开始时间那 A 和 B 不可能重叠所以排序后只需要比较相邻记录。既减少计算量逻辑也更好测试。写技能代码时不要追求炫技用最直观、最容易证明正确性的方案。3.4 注册进 Agent 主流程写完技能后需要在 Agent 主配置中注册。这一步不同框架差异很大但在agent-skills中我做的最重要的一件事是给技能注册器加上“可用技能列表自动发现”的能力。实现上就是去扫描skills/目录下所有含有SKILL.md的子文件夹把SKILL.md的前置元信息解析出来注入到模型可读的 context 里。扫描逻辑参考实现如下import os import yaml def discover_skills(skills_root): skills [] for entry in os.listdir(skills_root): meta_path os.path.join(skills_root, entry, SKILL.md) if not os.path.isfile(meta_path): continue with open(meta_path, encodingutf-8) as f: content f.read() # 简单解析 YAML front-matter 和 when_to_use 段落 meta parse_front_matter(content) skills.append({ name: meta.get(name, entry), description: meta.get(description, ), when_to_use: extract_section(content, when_to_use), }) return skills def parse_front_matter(content): if content.startswith(---): parts content.split(---, 2) if len(parts) 3: return yaml.safe_load(parts[1]) return {}实际产品中我不建议把完整的技能文档全部塞进模型上下文而是把name、description、when_to_use这精简三要素作为工具的“卡片”让模型快速决定要不要打开完整SKILL.md。少数情况下模型判断不了可以再设计一个“技能预检”动作先让模型读取完整说明书再决定这样更省 token。到底用哪套得在你自己的成本与准确率之间做权衡。4. 技能运行中最常见的坑与排查经验4.1 说了一百遍模型就是不调用技能这是几乎每个把任务做成技能的人都会遇到的问题。你写好了SKILL.md技能逻辑经过单测没有任何问题但模型在真实对话中就是不触发这个技能而是自作主张用通用方式回复用户。出现这种问题的头号原因九成是when_to_use写得太概念化。我第一次写每周舆情汇总技能时when_to_use只写了一句话“用户要求舆情分析时使用”。结果模型遇到“今天大家怎么讨论我们新版本”“帮我看看最近口碑怎么样”这类非常口语但明显需要舆情分析的请求时完全不触发技能。后来我改成枚举式写法把相似问法全部列进去再补上“即使没有出现‘舆情’字样只要涉及口碑、评价、讨论热度也应使用本技能”触发率立刻上升。排查这类问题我的建议是先看模型实际拿到的工具列表。多数框架支持打印每次请求的 System Prompt把工具相关的描述原样打出来以第三视角读一遍如果你自己是一个对外部世界毫无了解的新手看到这段描述你能在什么时候意识到“该用这个工具”吗如果描述里缺少触发的“用户语境”那问题就在这儿。4.2 参数解析老失败脚本接不住模型给的输入模型调用技能时输入参数往往并不稳定。我在做技能时曾遇到一种典型错误我在SKILL.md里写明了end_time但模型从用户口中提取“晚上十一点”时会别出心裁地传一个end_time: 十一点进来导致脚本的datetime.fromisoformat直接抛异常。后来我在项目中立了一条铁律技能入口必须做参数容错绝不能把原始输入直接塞给底层函数。规范的流程是先做字符串标准化中文数字转阿拉伯数字、模糊时间词转具体时间点再做格式校验最后才进入核心逻辑。比如对“十一点”这种输入可以先用一个normalize_time_expression函数转成23:00的标准格式解析前面无法处理的输入时明确返回错误信息而不是抛堆栈。这也引出一个更底层的设计原则技能必须在异常情况下给模型“软失败”反馈。模型调用技能失败后会把这段错误信息作为下一次推理的依据如果你返回的是一段晦涩的 stack trace模型也看不懂但如果你返回的是“无法解析时间字段 end_time请提供具体格式如 23:00”模型大概率能修正输入后再次调用成功。4.3 多个技能互相抢任务、打架技能数量少时没感觉等你沉淀了二十多个技能就会遇到“冲突”问题用户的某个请求技能 A 能处理、技能 B 也能处理模型随机选了一个结果你发现执行效果完全取决于模型“心情”。我在agent-skills里的做法是给每个技能加一层“优先级”元信息在when_to_use中写清楚“优先于谁”。比如我同时有一个通用file_operation技能和一个weekly_report技能当用户说“整理周报并保存到文件”时两个技能都会触发。我就在weekly_report的when_to_use里显式写上一句“当任务包含周报整理时始终使用本技能而不是通用文件操作技能”。优先级不放在代码里而是写在模型的说明文档里让模型具备优先级的先验知识。另一个更工程化的方案是做一个路由技能写一个入口技能内部用较低的成本判断用户意图再决定调用子技能。这相当于把多个技能的调度逻辑用一段确定性代码包起来不再依赖模型自由发挥。这个方案牺牲一点灵活性但换来很高的稳定性适合生产环境。4.4 技能出现副作用内部改坏了外部数据这是最隐蔽的问题。很多技能执行过程必然要读写文件、调数据库但执行到一半失败时可能已经留下了半份写入结果。这种事我踩过不止一次周报聚合技能在处理到第三个数据源时网络请求失败但前两个数据源已经写入结果文件整份报告既不是旧数据也不是完整的新数据。现在的处理方式统一是“两阶段提交”。技能在真正写外部系统前先把结果完整地构建在内存或临时目录里全部成功后进行一次原子性替换或写入宁可失败时不留下痕迹也不要让用户看到半个结果。这个原则在所有有副作用的技能里都应该成立。任何技能设计评审时我都会额外过一个问题清单这个技能失败时会对外部系统产生什么影响用户能不能通过重试安全恢复如果答案不确定那就说明副作用没有控制好。生产环境的 Agent 能力靠的不是偶尔的成功而是稳定可预期的失败恢复路径。5. 让技能库变成可持续维护的工程资产5.1 给技能加一套“模型无关”的测试技能系统一个容易被低估的挑战是模型本身是概率性的但是技能执行得是确定性的。所以在agent-skills项目中我引入了两层测试。第一层是纯函数测试。把你技能里的核心逻辑抽成tests/test_*.py里的单元测试覆盖正确场景、边界场景、异常输入。这部分与模型无关跑得快是技能质量的第一道门槛。第二层叫“意图触发测试”。用一组预置的用户话术列表逐条调用 Agent 编排层记录模型到底触发了哪个技能。做法不复杂就是准备一个包含 20 到 50 句话术的样本集跑一次批量验证看逐个请求的技能命中是否符合预期。这部分不追求 100% 准确率但能帮你看到对自己的技能描述做微调后触发率的整体走向是变好还是变差。5.2 技能也要渐进式暴露我在本地调试了一个新技能功能测试通过后没有立刻把它放进生产环境所有 Agent 的公开工具列表。更稳妥的做法是“金丝雀发布”先让这个技能只对内部测试用户可见收集几轮真实调用日志确认没有触发混乱、没有异常副作用后再逐步放量。这听起来有点“重”但对生产环境来说非常必要。Agent 技能一旦放出去用户会以你想象不到的方式召唤它很可能会触发你在说明书里没有预料的输入。渐进式暴露给了你一个观察期可以让问题平息在可控范围内。毕竟技能库的代码逻辑不难改比较难的反而是“一个错误技能被调用过一次后用户对 Agent 的信任损失”。5.3 版本与回滚维护一个技能应有的姿态最后也是我个人更想强调的一点技能是一种“会演进”的资产。业务规则会变输入输出结构会变当你把技能当作正式项目来维护时就不能像随手写个函数那样改完就上路。我现在的做法是给技能包打上version字段并在CHANGELOG里记录每次行为变更。当行为出现大变化时我会同时保留上一版本技能名下的SKILL.md通过模型路由里的新旧版本对比来放飞。回滚机制同样重要。有一次我在优化某技能的性能时把原来的同步处理流程改成了并发方式测试也通过了。上线后才发现技能依赖的内部接口有每秒请求数限制并发一上去直接 429 报错。当时如果没有一键回滚版本的能力修复时间至少要翻倍。所以技能包最好从头设计成“可替换目录”式结构新版本、旧版本各自独立目录主配置里通过 symlink 指向当前活跃版本。更新只是切换 symlink一分钟内就能完成回滚。6. 一点私货技能化思维改变了我的 Agent 实践到现在我维护agent-skills已经有段时间了。最初我以为它是一个技术项目后来发现它更是一个认知项目。它教会我的不是怎么写代码而是怎么理解“能力边界”——与其给 Agent 一个无所不包却模糊的“全能大脑”不如给它一套边界清晰、彼此协同的“肌肉记忆”。这种模式也大幅改善了我调试 Agent 的体验。以前模型表现不好我总在调 Prompt调完也不知道是变好还是变坏现在系统出了问题我可以直接打开对应技能的单元测试和触发样本集快速定位是“它不知道该用技能”还是“技能内部执行错误”排查面一下子就收窄了。如果你刚好也处在“Agent 工具箱越来越碎、Prompt 越来越长”的阶段我建议认真尝试一次技能化改造。不用追求一步到位挑一个你觉得反复出现过多次、流程相对固定的任务把它沉淀成第一个技能包。相信我当你亲眼看到模型准确触发它、稳定产出结果、还能被测试保护住的时候你会再也回不去那种什么都靠模型临场发挥的使用方式。