如果你最近在折腾 AI Agent或者说但凡关注过大模型应用层的进展那就一定绕不开一个词agent-skills。这个赛道最近热得发烫各个大厂和开源社区都在推自己的技能框架网上讨论也很多但大多数资料讲得云里雾里要不就是复制官方文档要不就是一上来甩一堆抽象架构图。我今天想从实战角度把这几个月我在真实项目里折腾 agent-skills 的踩坑经历、设计思路和落地细节一次讲透给准备上手或者已经在做 Agent 能力的同学一个直接能用的参考。我先说清楚agent-skills 解决的是一个非常具体、非常磨人的问题大模型本身的泛化能力再强在碰到特定领域的重复性任务时它依然是个“无工具的人”。让它写代码可以但让它按照你们团队的代码规范去写、让它直接操作你们内部的数据分析平台、让它按特定格式提交结果它就经常天马行空。传统做法是写提示词但提示词又臭又长维护起来想死后来流行工具调用但工具调用更适合那种单一动作比如查天气、算个税一旦涉及多步骤流程调用逻辑就变得混乱。agent-skills 的思路是把一整段可复用的能力——包括指令、脚本、依赖、示例——打包成一个“技能包”让 Agent 像人一样“学会了”这门手艺而不是临时翻说明书。这篇文章不劝退谁也不劝进谁。如果你打算给项目引入 agent-skills或者已经在用但效果不稳定我下面分享的这些设计细节、实操步骤、问题复盘都是能直接抄作业的。尤其是几个坑我敢说你十有八九也会踩。1. 整体设计与思路拆解1.1 什么是 agent-skills它和工具调用、提示词到底什么关系很多同学第一反应是这不就是给 AI 加了几个 API 调用吗还真不是。工具调用是“给 Agent 一支笔”而 agent-skills 是“培训 Agent 学会一套工作方法”。我打个比方你让一个实习生去整理报表。工具调用的做法是给他一个 Excel 操作接口告诉他“用这个接口打开文件、用那个函数求和”agent-skills 的做法是直接把你们部门沉淀的《报表整理操作手册》给他手册里包含了打开文件的标准姿势、脏数据怎么处理、格式怎么调、遇到异常怎么兜底甚至还有良好示例和错误示例。实习生抽到这份手册就能按经验办事。从实现层面拆解agent-skills 通常具备三个共同特征自包含每个技能是一个独立目录包含技能说明、执行脚本、依赖清单、示例输入输出不依赖外部知识库的实时查询。可被模型按需调用Agent 通过读取技能描述通常是 SKILL.md 文件理解这个技能能做什么然后在合适时机主动触发。面向流程而非单点技能内部可以串联多个步骤甚至调用多个底层 API但对 Agent 来说它只是一个心智单元。这个设计与传统“提示词工程”最本质的区别在于提示词是写在系统上下文里的每次对话都要重新“阅读理解”一遍技能是放在仓库里的Agent 在需要时才去加载。这意味着技能可以做得非常细节、非常长而不会占用每轮对话的上下文窗口。我实测过一个复杂的技能说明文件可以有几百行而 Agent 在普通对话里完全感受不到它的存在只有等到任务需要它执行时它才发挥价值。1.2 为什么需要把能力“模块化”它解决了什么痛点在做 Agent 项目的过程中我遇到过三个特别典型且很难绕过的坎而 agent-skills 简直是冲着这三个坎去的。第一个坎是上下文窗口不够用。假设你做一个客服 Agent日常要处理退换货、物流查询、优惠券计算、投诉升级等多种业务。如果把所有业务细则全部塞进系统提示词上下文窗口瞬间被占满而且模型在长上下文中容易“迷失重点”前期规则会被后面的内容稀释。而技能化之后每条业务规则只需要在对应技能里出现Agent 只有处理相关问题时才读取上下文压力直接下降了一个数量级。第二个坎是复杂流程容易断。单一工具调用适合原子操作但真实业务往往是一条链查订单、核对库存、计算赔偿、生成工单、发通知。如果让 Agent 拿着五六个工具在那里自己编排它经常会在中途漏掉一步或者步骤顺序错乱。而技能封装之后整条链路在代码里就写死了Agent 拿到的接口只有一个“执行售后处理”内部的严谨性由技能脚本保证不由模型发挥保证。第三个坎是能力无法沉淀复用。今天调通的流程明天换个项目又要重写。直接用技能目录管理团队内部可以像共享代码库一样共享技能新项目接入就是复制一个文件夹的事。我见过有的团队已经积累了上百个技能文件夹相当于给公司攒了一个“数字员工技能库”这个复利效应是很惊人的。1.3 设计一个技能包的基本心智模型我设计了不下二十个技能最后总结出一个核心心智模型把技能当作“给一个靠谱但没经验的新员工的入职培训材料”。你不可能把一个什么都懂的老员工塞进 AI 里但你可以把老员工沉淀下来的经验写成标准作业程序然后交给一个学习能力极强但容易自作聪明的新人。基于这个模型每个技能的设计都要回答四个问题什么场景下触发这个技能触发条件执行这个技能需要哪些输入参数与输入执行的步骤是什么每一步要做到什么标准流程什么情况算成功什么情况算失败失败怎么处理边界这四个问题的答案就是技能包的骨架。很多同学做的技能不稳定我事后去复盘十有八九是只写了“怎么做”漏了“什么时候做”和“做砸了怎么办”。2. 核心细节解析与实操要点2.1 技能目录结构与 SKILL.md 的写法我直接给出一个经过实战检验的技能目录结构你可以当成模板来用skills/ └── weekly-report/ ├── SKILL.md ├── scripts/ │ ├── generate_report.py │ └── collect_data.py ├── assets/ │ ├── template.docx │ └── example_output.md ├── requirements.txt └── meta.json这里每个文件都有存在的意义我一个个说。SKILL.md 是这个技能的“说明书”也是 Agent 决定是否调用这个技能的唯一依据。它的质量直接决定了技能的召唤成功率和执行准确度。我总结了一个有效写法分为五个段落# 技能名称周报自动生成 ## 描述 自动收集本周工作记录汇总并生成符合公司格式的周报 Markdown 文件。 适用于需要周期性提交工作汇报的场景。 ## 适用场景 - 用户说“帮我写周报” - 用户说“汇总一下这周的工作” - 用户提到“本周进展/下周计划”等关键词 ## 不适用场景 - 用户需要的是日报、月报请使用其他技能 - 用户手工提供了完整周报内容仅要求排版 ## 输入要求 - 必须能访问本周的工作记录数据源 - 如果没有数据源请明确询问用户数据位置 ## 执行步骤 1. 读取 scripts/collect_data.py从数据源拉取本周记录 2. 调用 scripts/generate_report.py传入数据文件路径 3. 使用 assets/template.docx 作为输出样式参考 4. 生成 Markdown 文件按优先级排序重要事项 5. 输出文件路径给用户 ## 质量标准 - 周报必须包含本周完成、下周计划、风险与求助 - 数据缺失时不要编造标注“待补充” - 输出文件为 UTF-8 编码你注意看这份 SKILL.md 和传统提示词有一个显著区别它没有用“你要扮演一个周报助手”这种人格设定而是像一份工程规范一样直接告诉模型“在这里判断、在那里执行、在某种情况下不要做”。我测试过同一套步骤用角色扮演式写法模型经常会跑偏去关心用户情绪换成这种纯流程式写法执行稳定性直线上升。2.2 脚本与依赖管理的几个实操原则技能里绑定脚本最大的坑就是环境不一致。你的开发环境能跑到 Agent 的运行环境里报错这是常见得不能再常见的故障。我给你三个原则第一尽量用最通用的运行环境。比如 Python 技能能用标准库就绝不引第三方包实在要引也要锁定版本号。我在 requirements.txt 里一般这么写pandas2.0.3 openpyxl3.1.2 requests2.31.0第二脚本入参出参必须统一。我给内部团队定的规范是所有技能脚本统一接受 JSON 作为标准输入从 stdin 或者文件读入统一输出 JSON 到 stdout。这样 Agent 调用技能时不需要知道不同脚本的差异化传参方式脚本之间也好串联。下面是个参考范例#!/usr/bin/env python3 import json, sys def main(): # 从 stdin 读取输入 input_data json.load(sys.stdin) user_name input_data.get(user_name, 未知用户) # 执行业务逻辑 result {report_title: f{user_name}的周报, status: ok} # 输出 JSON print(json.dumps(result, ensure_asciiFalse)) if __name__ __main__: main()第三脚本要有充分的防御性。不要假设输入一定完整不要假设文件一定存在。一个技能失败不可怕可怕的是失败之后 Agent 还继续往下跑产出错误结果。所以脚本里每一段关键逻辑都要有 try-except并且明确返回错误码。我给错误码定的规范是0 表示成功非 0 表示失败并要在输出里带上 human-readable 的错误信息方便 Agent 决定下一步动作。2.3 元数据与版本管理技能的可维护性一个技能从开发到上线一定会经历无数版本迭代。没有版本管理技能库迟早变成一锅粥。我在 meta.json 里会维护这些信息{ name: weekly-report, version: 1.3.0, author: zhangsan, description: 自动生成周报支持钉钉/飞书格式, triggers: [周报, weekly report, 工作汇报], dependencies: [collect_data], last_updated: 2025-11-02, compatible_models: [claude-sonnet-4-5, gpt-4o] }你可能觉得这些都是干巴巴的信息但实际排查问题的时候这些信息就是救命稻草。比如哪天技能突然不触发了你查一下 last_updated发现最近改过触发词问题定位就快了。又比如换了模型之后技能效果变差你查 compatible_models发现当前模型根本没在兼容列表里那就知道是该调技能还是该换模型了。另一个维护技巧是给技能写 changelog。每个版本号对应一个变更说明我习惯放在技能目录下的 CHANGELOG.md 里。听起来很繁琐但技能库到了几十个规模之后没有变更记录根本没法回溯。3. 实操过程与核心环节实现3.1 从零构建一个技能以“代码规范审查”为例光说不练假把式我拿一个我自己项目里的真实技能——“代码规范审查”——来完整走一遍实操流程。这个技能的需求背景是团队有代码规范文档但模型写出来的代码经常不合规比如命名风格不对、错误处理缺失、注释格式混乱。传统做法是把整个规范文档塞进系统提示词结果上下文爆炸而且规范一多模型就选择性忽略。我设计这个技能的步骤如下**第一步梳理触发场景。**这个技能应该在模型编写或修改代码文件时被调用。我定义几个高频触发信号用户要求“写一个函数”“重构这段代码”“修复 bug”。如果是这些指令技能就需要介入。**第二步拆解执行流程。**规范的审查不能靠模型自由发挥我要把流程固定下来。流程分为四段读取当前代码文件调用scripts/lint_check.py进行静态规则检查调用scripts/style_check.py进行命名与格式检查汇总问题清单按严重级别排列输出修改建议**第三步写 SKILL.md。**这一份比周报的例子更复杂因为涉及大量的规范细节。我提取几个关键片段给你看## 执行步骤 1. 获取用户当前编辑的文件路径确认文件存在且可读 2. 运行 scripts/lint_check.py --file path收集错误 3. 运行 scripts/style_check.py --file path收集风格问题 4. 将两类问题合并去重按下面规则排序 - P0会导致运行时错误的逻辑问题 - P1违反团队核心命名规范的问题 - P2格式和注释的可优化项 5. 对每个问题给出“代码位置 问题描述 修改建议” 6. 如果 P0/P1 问题数量为 0直接输出“代码已符合规范” ## 质量标准 - 不虚构问题lint 脚本没有报错的地方模型不得自行添加“可能有问题”的臆断 - 修改建议必须可执行不能只说“请改善代码质量”要说“请将变量名 data 改为 data_list”注意第 6 条这其实是一个很关键的设计。大模型有个毛病就是“刷存在感”明明代码已经没问题了它非要给你提出一堆无关紧要的“建议”。我在质量标准里强制规定“没有报错就输出已合规”直接把这个毛病给按住了。**第四步实现脚本。**lint_check.py 和 style_check.py 我直接用开源工具封装一层但做了一个关键的调整原来开源工具的输出太冗长模型根本消化不了。我写了一个解析层把工具输出整理成简洁的结构化 JSON{ level: P0, file: src/utils.py, line: 42, message: 密码字段未脱敏可能导致敏感信息泄露, suggestion: 使用 mask_secret 函数处理后再输出 }为什么必须做结构化因为模型在处理结构化的输入时它的“阅读理解”能力会大幅提升而面对大段混乱的纯文本时经常抓不住重点导致它在汇总时漏报或误报。这一步是整个技能稳定性的关键所在。3.2 技能编排多技能协作的方法当技能数量多起来之后下一个问题就是多个技能如何协作。我的做法是引入一个“编排技能”的概念它本身不执行具体任务而是负责任务分解和调度其他技能。举个例子用户说“帮我生成产品发布公告”编排技能会这样思考从需求池技能获取产品功能清单从竞品分析技能获取对比优势点从文案生成技能生成初稿从规范审查技能检查文案是否合规输出最终文案在这个过程里编排技能相当于一个项目经理它通过读取每个子技能的 SKILL.md 描述来判断谁适合干什么。这里我给一个经验值子技能的 SKILL.md 描述写得越精准编排的成功率越高。模糊的描述会让编排技能做出错误的选择所以每个技能的“适用场景”和“不适用场景”两段一定要反复打磨。3.3 技能调用链路里的参数传递设计多技能协作中最容易翻车的是参数传递。Agent 在执行完一个技能后需要把结果数据传给下一个技能但如果数据结构不一致下一个技能根本接不住。我在项目里定了一条铁律所有技能之间传递数据统一使用 JSON并且每个技能输出的 JSON 必须包含一个 result 字段和一个 meta 字段其中 meta 里面记录来源技能、执行时间、数据格式版本。我放一个真实的数据流转示例{ result: { feature_list: [智能推荐, 一键导出], highlight: 推荐准确率提升 30% }, meta: { from_skill: requirement-pool, skill_version: 2.1.0, timestamp: 2025-11-02T14:30:00Z } }这样下游技能在消费数据前可以先检查 meta 里的 from_skill 和 skill_version一旦发现数据来源不是预期版本就提前报警而不是稀里糊涂地往下游传脏数据。这个设计帮我避免了好几次线上事故。多说一句参数校验不要指望模型自觉。一定要在代码里写死校验逻辑比如检查必填字段是否存在类型是否正确范围是否合法。模型是一个不可靠的“传输带”你要在传输带上加卡扣。4. 常见问题与排查技巧实录4.1 技能不被触发先检查描述文件我遇到最多的问题是技能明明做好了Agent 却“视而不见”。排查思路其实不复杂90% 的情况出在 SKILL.md 的描述段落上。模型是根据描述来判断要不要调用技能的如果你的描述只有一句“这个技能可以做很多事情”模型根本无从判断何时该用。我给排查这类问题准备了一张速查表现象大概率原因排查动作技能完全没有触发SKILL.md 描述过于模糊重新写“适用场景”使用任务动词和具体名词触发时机不对描述与用户意图关联弱补充更多同义触发短语该触发时没触发不该触发时乱触发“不适用场景”缺失明确补充排除条件技能触发后中途放弃执行步骤不够清晰将步骤拆分到原子粒度每步单独说明我还试过一个笨但有效的排查方法把“适用场景”写成用户原话示例比如“当用户输入类似‘查一下这个函数有没有内存泄漏’这样的指令时”。模型对具体例子的理解远远好于抽象概括这是大模型本身的特性决定的。4.2 技能产出不稳定八成是脚本输出太含糊技能触发了但结果质量忽高忽低这也让很多同学头疼。我在排查这类问题时第一件事不是看提示词而是看脚本输出。如果脚本输出是一大段没有结构的文本模型在润色和汇总时就容易自由发挥导致每次结果都不一样。如果脚本输出是严格的结构化 JSON模型的发挥空间就小得多稳定性自然提升。举个反面案例我之前有个技能负责抓取网页正文脚本直接 print 了网页所有段落的纯文本拼接结果。这个技能在生产环境跑10 次结果里得有 6 次内容不完整或顺序错乱。后来我把脚本改了输出变成带段落 ID、标题层级、正文分类的结构化 JSON准确率瞬间提升到了 95% 以上。你要相信一件事给模型吃什么决定模型拉什么。喂进垃圾结构出来就是垃圾结果。4.3 依赖冲突与环境不一致的终极解法技能脚本越来越多之后依赖冲突不可避免。项目 A 的技能用 pandas 1.5项目 B 的技能用 pandas 2.0装在一个环境里必炸。我建议用虚拟环境隔离 集中注册的思路每个技能在requirements.txt里声明依赖部署时按技能目录分别创建虚拟环境运行时通过入口脚本动态切换环境实际操作上我项目的部署脚本大概是这样的思路# 为每个技能创建独立虚拟环境 python -m venv skills/weekly-report/.venv skills/weekly-report/.venv/bin/pip install -r skills/weekly-report/requirements.txt # 统一入口通过技能名路由到对应环境 python run_skill.py --skill weekly-report --input input.json底层的 run_skill.py 会去对应技能目录的 .venv 里找解释器来执行子脚本。这样做看似浪费了一点磁盘空间但是换来的是各技能互不干扰排障时也只需要锁定单个技能的环境。4.4 模型顺序错乱从提示词和代码两头夹击有时候 Agent 会把技能步骤的顺序搞反比如先生成报告再收集数据或者跳过校验直接输出。这个问题我经历过很多次最后的解决方案是“双保险”。第一道保险在 SKILL.md 里明确写出步骤依赖关系。不能用“步骤 1、步骤 2、步骤 3”这种并列写法要写成## 执行步骤 1. 必须先完成数据收集调用 collect_data.py 2. 数据收集成功后才能执行报告生成调用 generate_report.py 3. 报告生成之后才能执行格式校验 4. 若前置步骤失败必须终止流程并向用户报告错误第二道保险是在脚本层面做前置检查。generate_report.py 启动时第一步就是检查数据文件是否存在且时间戳是否新鲜不存在就直接抛出错误。这样即使模型在提示词层面试图乱序代码层也会把它挡下来。这两道保险缺一不可。只靠提示词那是相信模型的自律只靠代码那模型路径上很多中间选择没人引导。要让提示词负责引导让代码负责兜底。4.5 技能调试的高效路径从最小示例开始最后分享一个调试效率技巧。我调试技能从来不用复杂任务测试而是先用一个最小示例验证链路通不通。比如新写一个技能我会构造一个最简单、最不容易出错的输入跑一遍看 Agent 是否能正确触发、脚本是否能顺利执行、输出是否合规。这一步通过了再逐渐增加输入复杂度。我调试一个“报表生成”技能时的最小示例长这样用户请生成张三本周的工作周报 预设数据源里只有两条工作记录如果连这种任务都跑不通说明技能定义有基本问题没必要拿复杂样本折磨自己。等最小示例通过再上多数据源、异常数据、边界情况的测试集。这个路径帮我节省了大量时间。5. 一些值得说的补充经验5.1 技能要控制在“一个技能干一件事”写到后面我发现一个规律越是想让一个技能干很多事这个技能就越难用。比如我最早把“代码审查”和“代码修复”放在同一个技能里结果 Agent 经常审完直接改但改的时候又不够谨慎产生新问题。拆成两个独立技能后审查只负责指出问题修复是另一个确认环节整个流程反而更可控。这是因为模型的执行稳定性与单个任务的复杂度成反比。一个技能的执行步骤最好控制在 5 到 8 步超过这个数量模型的错误率就开始明显上升。如果发现步骤太多要考虑拆技能或者把部分步骤下沉到脚本里用代码固定住。5.2 技能库的文档化与分享最后我想说一个组织层面的经验。技能做多了以后团队协作的效率瓶颈往往不在技能本身而在“别人不知道你有哪些技能”。我建议维护一份全局索引 README按领域分类列出所有可用的技能、各自的适用场景、负责人、版本状态。这份索引是给人和 Agent 一起看的Agent 可以在初始化时读取它人类同事也可以快速搜索。我见过一个团队把索引做成了“技能商店”的形态新人不问东问西就能找到现成的数据处理技能、文案技能、测试技能。这种沉淀下来的组织资产才是 agent-skills 真正值钱的地方。不是某个技能代码有多炫而是整套体系能不能让团队越用越顺手越用越离不开。我在实际项目里最大的感受是agent-skills 本质上不是技术问题而是把“人类经验结构化成机器可执行流程”的问题。你花在梳理业务边界、设计异常路径、打磨脚本输出上的时间远远大于模型调参的时间。只要这一步做扎实了后面 Agent 的表现就不会差到哪去。如果你正准备入坑建议先挑一个频次高、边界清晰的场景把第一个技能做透再谈规模化。技能做起来之后你会突然发现原本那些“只能靠人肉”的重复劳动已经被悄悄啃掉了一大块。
AI Agent技能封装实战：从提示词到可复用技能包
如果你最近在折腾 AI Agent或者说但凡关注过大模型应用层的进展那就一定绕不开一个词agent-skills。这个赛道最近热得发烫各个大厂和开源社区都在推自己的技能框架网上讨论也很多但大多数资料讲得云里雾里要不就是复制官方文档要不就是一上来甩一堆抽象架构图。我今天想从实战角度把这几个月我在真实项目里折腾 agent-skills 的踩坑经历、设计思路和落地细节一次讲透给准备上手或者已经在做 Agent 能力的同学一个直接能用的参考。我先说清楚agent-skills 解决的是一个非常具体、非常磨人的问题大模型本身的泛化能力再强在碰到特定领域的重复性任务时它依然是个“无工具的人”。让它写代码可以但让它按照你们团队的代码规范去写、让它直接操作你们内部的数据分析平台、让它按特定格式提交结果它就经常天马行空。传统做法是写提示词但提示词又臭又长维护起来想死后来流行工具调用但工具调用更适合那种单一动作比如查天气、算个税一旦涉及多步骤流程调用逻辑就变得混乱。agent-skills 的思路是把一整段可复用的能力——包括指令、脚本、依赖、示例——打包成一个“技能包”让 Agent 像人一样“学会了”这门手艺而不是临时翻说明书。这篇文章不劝退谁也不劝进谁。如果你打算给项目引入 agent-skills或者已经在用但效果不稳定我下面分享的这些设计细节、实操步骤、问题复盘都是能直接抄作业的。尤其是几个坑我敢说你十有八九也会踩。1. 整体设计与思路拆解1.1 什么是 agent-skills它和工具调用、提示词到底什么关系很多同学第一反应是这不就是给 AI 加了几个 API 调用吗还真不是。工具调用是“给 Agent 一支笔”而 agent-skills 是“培训 Agent 学会一套工作方法”。我打个比方你让一个实习生去整理报表。工具调用的做法是给他一个 Excel 操作接口告诉他“用这个接口打开文件、用那个函数求和”agent-skills 的做法是直接把你们部门沉淀的《报表整理操作手册》给他手册里包含了打开文件的标准姿势、脏数据怎么处理、格式怎么调、遇到异常怎么兜底甚至还有良好示例和错误示例。实习生抽到这份手册就能按经验办事。从实现层面拆解agent-skills 通常具备三个共同特征自包含每个技能是一个独立目录包含技能说明、执行脚本、依赖清单、示例输入输出不依赖外部知识库的实时查询。可被模型按需调用Agent 通过读取技能描述通常是 SKILL.md 文件理解这个技能能做什么然后在合适时机主动触发。面向流程而非单点技能内部可以串联多个步骤甚至调用多个底层 API但对 Agent 来说它只是一个心智单元。这个设计与传统“提示词工程”最本质的区别在于提示词是写在系统上下文里的每次对话都要重新“阅读理解”一遍技能是放在仓库里的Agent 在需要时才去加载。这意味着技能可以做得非常细节、非常长而不会占用每轮对话的上下文窗口。我实测过一个复杂的技能说明文件可以有几百行而 Agent 在普通对话里完全感受不到它的存在只有等到任务需要它执行时它才发挥价值。1.2 为什么需要把能力“模块化”它解决了什么痛点在做 Agent 项目的过程中我遇到过三个特别典型且很难绕过的坎而 agent-skills 简直是冲着这三个坎去的。第一个坎是上下文窗口不够用。假设你做一个客服 Agent日常要处理退换货、物流查询、优惠券计算、投诉升级等多种业务。如果把所有业务细则全部塞进系统提示词上下文窗口瞬间被占满而且模型在长上下文中容易“迷失重点”前期规则会被后面的内容稀释。而技能化之后每条业务规则只需要在对应技能里出现Agent 只有处理相关问题时才读取上下文压力直接下降了一个数量级。第二个坎是复杂流程容易断。单一工具调用适合原子操作但真实业务往往是一条链查订单、核对库存、计算赔偿、生成工单、发通知。如果让 Agent 拿着五六个工具在那里自己编排它经常会在中途漏掉一步或者步骤顺序错乱。而技能封装之后整条链路在代码里就写死了Agent 拿到的接口只有一个“执行售后处理”内部的严谨性由技能脚本保证不由模型发挥保证。第三个坎是能力无法沉淀复用。今天调通的流程明天换个项目又要重写。直接用技能目录管理团队内部可以像共享代码库一样共享技能新项目接入就是复制一个文件夹的事。我见过有的团队已经积累了上百个技能文件夹相当于给公司攒了一个“数字员工技能库”这个复利效应是很惊人的。1.3 设计一个技能包的基本心智模型我设计了不下二十个技能最后总结出一个核心心智模型把技能当作“给一个靠谱但没经验的新员工的入职培训材料”。你不可能把一个什么都懂的老员工塞进 AI 里但你可以把老员工沉淀下来的经验写成标准作业程序然后交给一个学习能力极强但容易自作聪明的新人。基于这个模型每个技能的设计都要回答四个问题什么场景下触发这个技能触发条件执行这个技能需要哪些输入参数与输入执行的步骤是什么每一步要做到什么标准流程什么情况算成功什么情况算失败失败怎么处理边界这四个问题的答案就是技能包的骨架。很多同学做的技能不稳定我事后去复盘十有八九是只写了“怎么做”漏了“什么时候做”和“做砸了怎么办”。2. 核心细节解析与实操要点2.1 技能目录结构与 SKILL.md 的写法我直接给出一个经过实战检验的技能目录结构你可以当成模板来用skills/ └── weekly-report/ ├── SKILL.md ├── scripts/ │ ├── generate_report.py │ └── collect_data.py ├── assets/ │ ├── template.docx │ └── example_output.md ├── requirements.txt └── meta.json这里每个文件都有存在的意义我一个个说。SKILL.md 是这个技能的“说明书”也是 Agent 决定是否调用这个技能的唯一依据。它的质量直接决定了技能的召唤成功率和执行准确度。我总结了一个有效写法分为五个段落# 技能名称周报自动生成 ## 描述 自动收集本周工作记录汇总并生成符合公司格式的周报 Markdown 文件。 适用于需要周期性提交工作汇报的场景。 ## 适用场景 - 用户说“帮我写周报” - 用户说“汇总一下这周的工作” - 用户提到“本周进展/下周计划”等关键词 ## 不适用场景 - 用户需要的是日报、月报请使用其他技能 - 用户手工提供了完整周报内容仅要求排版 ## 输入要求 - 必须能访问本周的工作记录数据源 - 如果没有数据源请明确询问用户数据位置 ## 执行步骤 1. 读取 scripts/collect_data.py从数据源拉取本周记录 2. 调用 scripts/generate_report.py传入数据文件路径 3. 使用 assets/template.docx 作为输出样式参考 4. 生成 Markdown 文件按优先级排序重要事项 5. 输出文件路径给用户 ## 质量标准 - 周报必须包含本周完成、下周计划、风险与求助 - 数据缺失时不要编造标注“待补充” - 输出文件为 UTF-8 编码你注意看这份 SKILL.md 和传统提示词有一个显著区别它没有用“你要扮演一个周报助手”这种人格设定而是像一份工程规范一样直接告诉模型“在这里判断、在那里执行、在某种情况下不要做”。我测试过同一套步骤用角色扮演式写法模型经常会跑偏去关心用户情绪换成这种纯流程式写法执行稳定性直线上升。2.2 脚本与依赖管理的几个实操原则技能里绑定脚本最大的坑就是环境不一致。你的开发环境能跑到 Agent 的运行环境里报错这是常见得不能再常见的故障。我给你三个原则第一尽量用最通用的运行环境。比如 Python 技能能用标准库就绝不引第三方包实在要引也要锁定版本号。我在 requirements.txt 里一般这么写pandas2.0.3 openpyxl3.1.2 requests2.31.0第二脚本入参出参必须统一。我给内部团队定的规范是所有技能脚本统一接受 JSON 作为标准输入从 stdin 或者文件读入统一输出 JSON 到 stdout。这样 Agent 调用技能时不需要知道不同脚本的差异化传参方式脚本之间也好串联。下面是个参考范例#!/usr/bin/env python3 import json, sys def main(): # 从 stdin 读取输入 input_data json.load(sys.stdin) user_name input_data.get(user_name, 未知用户) # 执行业务逻辑 result {report_title: f{user_name}的周报, status: ok} # 输出 JSON print(json.dumps(result, ensure_asciiFalse)) if __name__ __main__: main()第三脚本要有充分的防御性。不要假设输入一定完整不要假设文件一定存在。一个技能失败不可怕可怕的是失败之后 Agent 还继续往下跑产出错误结果。所以脚本里每一段关键逻辑都要有 try-except并且明确返回错误码。我给错误码定的规范是0 表示成功非 0 表示失败并要在输出里带上 human-readable 的错误信息方便 Agent 决定下一步动作。2.3 元数据与版本管理技能的可维护性一个技能从开发到上线一定会经历无数版本迭代。没有版本管理技能库迟早变成一锅粥。我在 meta.json 里会维护这些信息{ name: weekly-report, version: 1.3.0, author: zhangsan, description: 自动生成周报支持钉钉/飞书格式, triggers: [周报, weekly report, 工作汇报], dependencies: [collect_data], last_updated: 2025-11-02, compatible_models: [claude-sonnet-4-5, gpt-4o] }你可能觉得这些都是干巴巴的信息但实际排查问题的时候这些信息就是救命稻草。比如哪天技能突然不触发了你查一下 last_updated发现最近改过触发词问题定位就快了。又比如换了模型之后技能效果变差你查 compatible_models发现当前模型根本没在兼容列表里那就知道是该调技能还是该换模型了。另一个维护技巧是给技能写 changelog。每个版本号对应一个变更说明我习惯放在技能目录下的 CHANGELOG.md 里。听起来很繁琐但技能库到了几十个规模之后没有变更记录根本没法回溯。3. 实操过程与核心环节实现3.1 从零构建一个技能以“代码规范审查”为例光说不练假把式我拿一个我自己项目里的真实技能——“代码规范审查”——来完整走一遍实操流程。这个技能的需求背景是团队有代码规范文档但模型写出来的代码经常不合规比如命名风格不对、错误处理缺失、注释格式混乱。传统做法是把整个规范文档塞进系统提示词结果上下文爆炸而且规范一多模型就选择性忽略。我设计这个技能的步骤如下**第一步梳理触发场景。**这个技能应该在模型编写或修改代码文件时被调用。我定义几个高频触发信号用户要求“写一个函数”“重构这段代码”“修复 bug”。如果是这些指令技能就需要介入。**第二步拆解执行流程。**规范的审查不能靠模型自由发挥我要把流程固定下来。流程分为四段读取当前代码文件调用scripts/lint_check.py进行静态规则检查调用scripts/style_check.py进行命名与格式检查汇总问题清单按严重级别排列输出修改建议**第三步写 SKILL.md。**这一份比周报的例子更复杂因为涉及大量的规范细节。我提取几个关键片段给你看## 执行步骤 1. 获取用户当前编辑的文件路径确认文件存在且可读 2. 运行 scripts/lint_check.py --file path收集错误 3. 运行 scripts/style_check.py --file path收集风格问题 4. 将两类问题合并去重按下面规则排序 - P0会导致运行时错误的逻辑问题 - P1违反团队核心命名规范的问题 - P2格式和注释的可优化项 5. 对每个问题给出“代码位置 问题描述 修改建议” 6. 如果 P0/P1 问题数量为 0直接输出“代码已符合规范” ## 质量标准 - 不虚构问题lint 脚本没有报错的地方模型不得自行添加“可能有问题”的臆断 - 修改建议必须可执行不能只说“请改善代码质量”要说“请将变量名 data 改为 data_list”注意第 6 条这其实是一个很关键的设计。大模型有个毛病就是“刷存在感”明明代码已经没问题了它非要给你提出一堆无关紧要的“建议”。我在质量标准里强制规定“没有报错就输出已合规”直接把这个毛病给按住了。**第四步实现脚本。**lint_check.py 和 style_check.py 我直接用开源工具封装一层但做了一个关键的调整原来开源工具的输出太冗长模型根本消化不了。我写了一个解析层把工具输出整理成简洁的结构化 JSON{ level: P0, file: src/utils.py, line: 42, message: 密码字段未脱敏可能导致敏感信息泄露, suggestion: 使用 mask_secret 函数处理后再输出 }为什么必须做结构化因为模型在处理结构化的输入时它的“阅读理解”能力会大幅提升而面对大段混乱的纯文本时经常抓不住重点导致它在汇总时漏报或误报。这一步是整个技能稳定性的关键所在。3.2 技能编排多技能协作的方法当技能数量多起来之后下一个问题就是多个技能如何协作。我的做法是引入一个“编排技能”的概念它本身不执行具体任务而是负责任务分解和调度其他技能。举个例子用户说“帮我生成产品发布公告”编排技能会这样思考从需求池技能获取产品功能清单从竞品分析技能获取对比优势点从文案生成技能生成初稿从规范审查技能检查文案是否合规输出最终文案在这个过程里编排技能相当于一个项目经理它通过读取每个子技能的 SKILL.md 描述来判断谁适合干什么。这里我给一个经验值子技能的 SKILL.md 描述写得越精准编排的成功率越高。模糊的描述会让编排技能做出错误的选择所以每个技能的“适用场景”和“不适用场景”两段一定要反复打磨。3.3 技能调用链路里的参数传递设计多技能协作中最容易翻车的是参数传递。Agent 在执行完一个技能后需要把结果数据传给下一个技能但如果数据结构不一致下一个技能根本接不住。我在项目里定了一条铁律所有技能之间传递数据统一使用 JSON并且每个技能输出的 JSON 必须包含一个 result 字段和一个 meta 字段其中 meta 里面记录来源技能、执行时间、数据格式版本。我放一个真实的数据流转示例{ result: { feature_list: [智能推荐, 一键导出], highlight: 推荐准确率提升 30% }, meta: { from_skill: requirement-pool, skill_version: 2.1.0, timestamp: 2025-11-02T14:30:00Z } }这样下游技能在消费数据前可以先检查 meta 里的 from_skill 和 skill_version一旦发现数据来源不是预期版本就提前报警而不是稀里糊涂地往下游传脏数据。这个设计帮我避免了好几次线上事故。多说一句参数校验不要指望模型自觉。一定要在代码里写死校验逻辑比如检查必填字段是否存在类型是否正确范围是否合法。模型是一个不可靠的“传输带”你要在传输带上加卡扣。4. 常见问题与排查技巧实录4.1 技能不被触发先检查描述文件我遇到最多的问题是技能明明做好了Agent 却“视而不见”。排查思路其实不复杂90% 的情况出在 SKILL.md 的描述段落上。模型是根据描述来判断要不要调用技能的如果你的描述只有一句“这个技能可以做很多事情”模型根本无从判断何时该用。我给排查这类问题准备了一张速查表现象大概率原因排查动作技能完全没有触发SKILL.md 描述过于模糊重新写“适用场景”使用任务动词和具体名词触发时机不对描述与用户意图关联弱补充更多同义触发短语该触发时没触发不该触发时乱触发“不适用场景”缺失明确补充排除条件技能触发后中途放弃执行步骤不够清晰将步骤拆分到原子粒度每步单独说明我还试过一个笨但有效的排查方法把“适用场景”写成用户原话示例比如“当用户输入类似‘查一下这个函数有没有内存泄漏’这样的指令时”。模型对具体例子的理解远远好于抽象概括这是大模型本身的特性决定的。4.2 技能产出不稳定八成是脚本输出太含糊技能触发了但结果质量忽高忽低这也让很多同学头疼。我在排查这类问题时第一件事不是看提示词而是看脚本输出。如果脚本输出是一大段没有结构的文本模型在润色和汇总时就容易自由发挥导致每次结果都不一样。如果脚本输出是严格的结构化 JSON模型的发挥空间就小得多稳定性自然提升。举个反面案例我之前有个技能负责抓取网页正文脚本直接 print 了网页所有段落的纯文本拼接结果。这个技能在生产环境跑10 次结果里得有 6 次内容不完整或顺序错乱。后来我把脚本改了输出变成带段落 ID、标题层级、正文分类的结构化 JSON准确率瞬间提升到了 95% 以上。你要相信一件事给模型吃什么决定模型拉什么。喂进垃圾结构出来就是垃圾结果。4.3 依赖冲突与环境不一致的终极解法技能脚本越来越多之后依赖冲突不可避免。项目 A 的技能用 pandas 1.5项目 B 的技能用 pandas 2.0装在一个环境里必炸。我建议用虚拟环境隔离 集中注册的思路每个技能在requirements.txt里声明依赖部署时按技能目录分别创建虚拟环境运行时通过入口脚本动态切换环境实际操作上我项目的部署脚本大概是这样的思路# 为每个技能创建独立虚拟环境 python -m venv skills/weekly-report/.venv skills/weekly-report/.venv/bin/pip install -r skills/weekly-report/requirements.txt # 统一入口通过技能名路由到对应环境 python run_skill.py --skill weekly-report --input input.json底层的 run_skill.py 会去对应技能目录的 .venv 里找解释器来执行子脚本。这样做看似浪费了一点磁盘空间但是换来的是各技能互不干扰排障时也只需要锁定单个技能的环境。4.4 模型顺序错乱从提示词和代码两头夹击有时候 Agent 会把技能步骤的顺序搞反比如先生成报告再收集数据或者跳过校验直接输出。这个问题我经历过很多次最后的解决方案是“双保险”。第一道保险在 SKILL.md 里明确写出步骤依赖关系。不能用“步骤 1、步骤 2、步骤 3”这种并列写法要写成## 执行步骤 1. 必须先完成数据收集调用 collect_data.py 2. 数据收集成功后才能执行报告生成调用 generate_report.py 3. 报告生成之后才能执行格式校验 4. 若前置步骤失败必须终止流程并向用户报告错误第二道保险是在脚本层面做前置检查。generate_report.py 启动时第一步就是检查数据文件是否存在且时间戳是否新鲜不存在就直接抛出错误。这样即使模型在提示词层面试图乱序代码层也会把它挡下来。这两道保险缺一不可。只靠提示词那是相信模型的自律只靠代码那模型路径上很多中间选择没人引导。要让提示词负责引导让代码负责兜底。4.5 技能调试的高效路径从最小示例开始最后分享一个调试效率技巧。我调试技能从来不用复杂任务测试而是先用一个最小示例验证链路通不通。比如新写一个技能我会构造一个最简单、最不容易出错的输入跑一遍看 Agent 是否能正确触发、脚本是否能顺利执行、输出是否合规。这一步通过了再逐渐增加输入复杂度。我调试一个“报表生成”技能时的最小示例长这样用户请生成张三本周的工作周报 预设数据源里只有两条工作记录如果连这种任务都跑不通说明技能定义有基本问题没必要拿复杂样本折磨自己。等最小示例通过再上多数据源、异常数据、边界情况的测试集。这个路径帮我节省了大量时间。5. 一些值得说的补充经验5.1 技能要控制在“一个技能干一件事”写到后面我发现一个规律越是想让一个技能干很多事这个技能就越难用。比如我最早把“代码审查”和“代码修复”放在同一个技能里结果 Agent 经常审完直接改但改的时候又不够谨慎产生新问题。拆成两个独立技能后审查只负责指出问题修复是另一个确认环节整个流程反而更可控。这是因为模型的执行稳定性与单个任务的复杂度成反比。一个技能的执行步骤最好控制在 5 到 8 步超过这个数量模型的错误率就开始明显上升。如果发现步骤太多要考虑拆技能或者把部分步骤下沉到脚本里用代码固定住。5.2 技能库的文档化与分享最后我想说一个组织层面的经验。技能做多了以后团队协作的效率瓶颈往往不在技能本身而在“别人不知道你有哪些技能”。我建议维护一份全局索引 README按领域分类列出所有可用的技能、各自的适用场景、负责人、版本状态。这份索引是给人和 Agent 一起看的Agent 可以在初始化时读取它人类同事也可以快速搜索。我见过一个团队把索引做成了“技能商店”的形态新人不问东问西就能找到现成的数据处理技能、文案技能、测试技能。这种沉淀下来的组织资产才是 agent-skills 真正值钱的地方。不是某个技能代码有多炫而是整套体系能不能让团队越用越顺手越用越离不开。我在实际项目里最大的感受是agent-skills 本质上不是技术问题而是把“人类经验结构化成机器可执行流程”的问题。你花在梳理业务边界、设计异常路径、打磨脚本输出上的时间远远大于模型调参的时间。只要这一步做扎实了后面 Agent 的表现就不会差到哪去。如果你正准备入坑建议先挑一个频次高、边界清晰的场景把第一个技能做透再谈规模化。技能做起来之后你会突然发现原本那些“只能靠人肉”的重复劳动已经被悄悄啃掉了一大块。