Agent Skills 这个能力刚出来的时候我周围不少朋友的第一反应是这不就是把提示词写得更规范了一点吗我当时没急着反驳但心里清楚事情没这么简单。如果你上手写过几个真正的 Agent 应用就会发现最大的痛点根本不是模型笨而是它每次都在“临场发挥”同一个任务可能这次输出这个格式下次又换个思路。你真正需要的是让 Agent 在特定场景下稳定复现一套成熟的工作流而不是每次去猜。Agent Skills 解决的就是这个问题它把“你希望 AI 怎么做”从一段可有可无的建议变成了一份可加载、可复用、可版本管理的显式“工作手册”。这篇文章我想从设计思路、配置细节、到实际项目里踩过的坑完整拆一遍这个机制给正在折腾 Agent 工程化的朋友一份能直接参考的实操笔记。1. 整体设计与思路拆解为什么 Agent 需要“技能”而不是“提示词”很多人第一次接触 Agent Skills 时会觉得这玩意儿看着就像是一个加强版的 System Prompt或者是一份预设好的指令模板。这么理解不算全错但会低估它在整个 Agent 架构里的真正位置。我个人的看法是Skills 本质上重构了“人跟 Agent 协作”的接口方式它把“要求式”协作变成了“调用式”协作。这两者的差别非常大。1.1 从“临场发挥”到“按需取用”在常规的 Prompt 工程里你通常是在系统提示词里写上一大段“你要做什么、要遵循什么流程、输出格式是什么”。这些指令确实有用但它是静态的。Agent 每次对话都会读到这些内容不管当前任务需不需要都得把这些上下文塞进窗口里既消耗宝贵的上下文长度又容易导致模型在无关任务上被这些指令干扰——它可能本来只是想帮用户查个天气结果你的长提示词里写满了代码风格要求它就会表现得特别拧巴。Agent Skills 的思路完全不同。它是把一套完整的工作流程、规范、注意事项打包成一个独立的“模块”平时不加载只有用户请求命中了这个技能的使用场景时Agent 才会主动去调用它。这就是“函数式”思维需要的时候 import不需要的时候完全不占用资源。从我实际使用的感受来看这种方式至少带来三个直接好处上下文长度更省、指令针对性更强、Agent 的行为可预测性大幅提升。1.2 把“你该怎么想”变成“你能用什么”再往深一层看Agent Skills 的底层设计哲学其实是从“告诉模型怎么思考”转向了“给模型提供可操作的工具和规范”。前者依赖模型当时的“临场理解能力”后者则把组织好的经验直接固化下来。尤其是当你的项目里有一些极其复杂的领域知识比如金融合规检查、医疗数据处理或者需要结合企业内部的 API 规范去做开发时——这些知识靠模型在推理时“回忆”是极不可靠的你也绝不应该指望它自由发挥。通过 Skill 把这套规范准确固化下来Agent 在相关场景下就不再是一个“泛泛而谈的聪明人”而更像一个“熟读规章制度的专业执行者”。这个转变一旦发生Agent 应用的上限就高了很多因为它照抄的是你验证过的最佳实践而不是它自己临时推理出来的某个“看起来可行”的方案。我对 Agent Skills 的整体判断是它的确不是最炫酷的底层技术但它可能是当前把 Agent 从“玩具”推向“生产力工具”最关键的一环。2. 核心细节解析与实操要点SKILL.md 里究竟该写什么既然决定入坑第一步肯定是搞清楚一个 Skill 到底长什么样。以目前主流平台的标准实现为例一个 Skill 本质上就是一个目录目录里有一个SKILL.md文件以及若干可选的其他文件比如参考代码、模板、数据集。SKILL.md是整个技能的核心它的内容质量直接决定技能的好坏。2.1 SKILL.md 的双层结构元信息与指令主体我看到不少人第一个版本写的SKILL.md就是一大段话“你是一个擅长写报告的人你应该……”——这其实又绕回了 Prompt 的老路。规范的做法是把它拆成两块YAML 元信息区和Markdown 指令区。YAML 元信息区里最关键的是name和description两个字段。description尤其重要因为模型就是靠它来判断“当前用户诉求是否应该调用这个技能”。我的建议是不要在 description 里堆形容词要写清楚“这个技能解决什么输入、能产出什么输出以及典型的使用场景”。Markdown 指令区则是技能的“灵魂”。这部分不必长篇大论地讲道理而是要明明白白写清楚执行的流程规范。2.2 一个技能一个职责内聚性是第一原则很多人容易犯的另一个错误是想把一个技能写成“万能工具箱”什么都往里塞。我见过一个同事写的 Skill 名叫“数据分析”里面既能处理 CSV、又能画图表、还能做时间序列预测、甚至兼职写 SQL——结果就是模型调用它的时候经常懵圈不知道到底该执行哪一步。这里我的经验是一条技能只解决一个核心任务一个岗位只负责一条结果链路。宁可把功能拆成多个技能也不要揉成一个“四不像”。如果你处理 Excel 的数据时需要有清理步骤和可视化步骤那就拆成excel_data_cleaner和excel_chart_builder两个技能串行调用效果远好于一个技能里塞两个模块——因为模型在单个技能内会更专注优先执行你定义的步骤顺序而不是自己“随机漫步”搞出别的花样。2.3 引用文件路径把细节从提示词里解放出来当技能逻辑比较复杂时不建议把所有细节都堆进SKILL.md正文。更好的做法是把可执行脚本、代码模板、参数配置放到同一目录下的其他文件里然后在指令区写上“调用脚本 xxxxx 来完成 xxx 任务”。这会让技能主文档保持精炼模型每次只需要读取最核心的执行策略具体怎么算、怎么调库直接交给携带的脚本去执行就好。我在实际项目里养成了一个习惯凡是能用代码实现的过程绝不写进自然语言指令。拿生成报表来说我不会在SKILL.md里写“请使用 pandas 读取数据并计算均值”而是直接写好一个compute_summary.py指令里只写一句话“运行 compute_summary.py参数传入数据文件路径它会生成一份 summary.json后续的 Markdown 表格基于这个 JSON 生成。” 这样模型的操作路径立刻就从“思考用什么代码”变成了“按既定规范执行脚本”出错率大幅下降。3. Agent Skills 工程化实操从零搭建与核心字段精讲聊完了理念直接上手。我在这里用的一个实操场景是构建一个“技术周报自动生成”技能。选择它是因为周报场景在职场里极其普遍理解门槛低同时又能覆盖到 Skills 配置中的多数关键字段比较适合作为演示案例。3.1 建立目录与文件结构我习惯按“一个技能一个文件夹”的方式来组织agent-skills/ ├── weekly-report/ │ ├── SKILL.md │ ├── collect_git_log.sh │ └── templates/ │ └── weekly_report_template.md目录结构就位后核心是填充SKILL.md的内容。下面这个配置我经过多次调优几个字段值都直接影响调用效果逐个说明。3.2 SKILL.md 规范配置与字段解读--- name: weekly-report-generator description: 根据 Git 仓库的提交记录和当前日期生成符合规范的中文技术周报。当用户需要撰写周报、汇总一周工作或需要提交项目进度报告时使用。 ---这里最需要注意的就是 description 的写法和位置。name 字段是技能的唯一标识命名尽量用连字符分隔的小写单词方便识别和调用description 是整个技能的“触发开关”位置靠前但要确保它覆盖到“什么时候该调用这个技能”的全部常见说法。我特别加了“当用户需要……”这种句式模型对这种触发场景的描述非常敏感。尤其是“中文技术周报”这个词我一并放进触发描述里模型就更不容易漏判使用者其实是想要英文版本的需求。接下来是正文的“执行指令区”这是技能的心脏我按典型的“任务流”编写# 执行步骤 当你收到周报生成请求后严格按以下顺序执行 1. 切换到目标 Git 仓库根目录运行 ./collect_git_log.sh它会自动提取最近 7 天的提交记录保存到 git_log.txt。 2. 打开 git_log.txt以“工作内容”为维度将提交信息归类为功能开发、缺陷修复、技术调研、团队协作四类。 3. 使用 templates/weekly_report_template.md 中的模板根据归类后的信息填充周报内容。 4. 填充完毕后检查所有条目是否都有具体动作和结果说明避免只有动词没有对象的空洞描述。 # 补充规范 - 提交信息里的 commit 大概率不规范不要原样粘贴请转成符合商务沟通习惯的书面表达。 - 如果某个分类下没有内容直接删除该分类不要留空。 - 周报中的日期范围以脚本输出的起止日期为准。 - 文本组织使用礼貌、简洁的中文篇幅控制在 400 字以内。这份指令区的写法核心在于把每个操作步骤的前后依赖关系明明白白地交代清楚。注意我没有用“请尝试”“你可以考虑”这类模糊用语全部换成了“运行”“打开”“填充”“检查”这样的“命令式”操作。模型在处理这种高确定性指令时执行稳定性会明显提高如果你用商量语气反倒会让模型陷入过度思考输出不稳定。3.3 辅助脚本与模板设计collect_git_log.sh我写得很“无脑”#!/bin/bash since$(date -d 7 days ago %Y-%m-%d) until$(date %Y-%m-%d) echo 周报周期: $since ~ $until git log --since$since --until$until --prettyformat:%h|%an|%s --no-merges模板我用了最简单的占位结构# 技术周报{date_range} ## 功能开发 - {描述做了什么} ## 缺陷修复 - {描述修了什么} ## 技术调研 - {调研了什么结论如何}3.4 把技能挂载到 Agent路径与生效技能写完后如何让 Agent 真正“装上”它不同平台挂载位置不同但原理一致把技能目录放到 Agent 能扫描到的技能根目录下。以当前主流做法为例通常在 Agent 客户端或配置页的指定路径下创建skills目录把技能文件夹放到这里然后重启会话。挂载完成后你可以试着对 Agent 说一句“帮我生成本周的技术周报”观察它是否会自动识别并切入技能调用流程。这里有一个非常重要的排查经验很多朋友加载技能后一点反应都没有大概率不是代码写错了而是触发描述没写准。你可以做个快速自测——把自己写的 description 遮住想象你是模型看到用户说“总结一下这周的进展”你能不能百分百确定要调这个技能如果不能说明描述需要加关键词。实际调试时我和同事的习惯是建一个专门的测试会话把所有可能触发该技能的说法都试一遍确保命中率满意后再正式启用。4. Agent Skills 工程化实战从单技能到技能体系理解了 SKILL.md 的写法下一步就要考虑如何把 Skills 用到真实的 Agent 工程里。这里指的是更复杂的“技能体系”比如多个技能之间如何配合、参数如何传递、上下文如何共享。4.1 技能生命周期管理创建、测试、版本化把 Agent Skills 当作代码来管理是我从实践中总结出的最重要一条经验。既然是代码就要有生命周期开发、测试、发布、维护、退役。市场上很多团队写技能的方式非常“原始”直接丢给 ChatGPT 或 Claude 写好就上线出问题就在原文件上改改完也没记录最后谁都不知道线上跑的到底是哪一版。我现在的习惯是给每个 Skill 建立 Git 仓库并有意识地控制版本。假设你写好了weekly-report-generator的 v1.0 版本合入主干之前要跑一遍“最小验证集”就是用几条真实历史数据让 Agent 调用这个技能确认产出合格才能标记 release。上线后如果发现需要修正就在分支上改触发问题后提交 PR同事 review 通过再合入。这样经过几轮迭代你的技能会越来越稳定而且每个版本“为什么这么改”都有据可查。4.2 技能的组织与命名可被发现性技能多了之后最大的挑战就是“内耗”agent 可能选错了技能、也可能两个技能重复覆盖某类任务。所以我们团队内部对技能命名和描述有以下几条硬性约束这里分享给读者参考命名必须“所见即所得”比如一个专门负责把数据转成折线图的技能直接叫line-chart-generator不要叫visualizer_utils这种谁都看不懂的名字。描述里必须写清“边界”比如“本技能只适用于 2024 年后的数据格式老数据请使用 xxx 技能”。技能之间不要有交叉职责如果一个技能处理了另一个技能的触发场景说明职责划分有问题重新切分。我在项目中实际维护的技能就有 20 多个命名规范但边界不清晰时Agent 还经常“纠结”该用哪个。后来我们强制在 description 里增加了“优先级提示词”比如“如果用户要求是粗略分析请优先使用 quick-scan如果是详细报告再用 deep-dive”问题立刻缓解。指令里一点点的结构化设计就能显著提升 Agent 在复杂技能体系下的选择准确率。4.3 技能间的协作编排串行、并行与条件分支单个技能再强也只是一个零件。真实业务里往往需要多个技能配合才能完成一条完整工作流。比如客服机器人处理售后问题可能需要先调用order-lookup查订单再调用refund-policy-checker查退款规则最后用response-composer生成回复。这里我就把技能编排成“有向无环图”的感觉每个技能是一个节点每个节点的输出是下一个节点的输入。Agent 的模型本身具备这种“串行调用”的能力但你不去刻意设定顺序时它有可能会跳过某些步骤。所以我在 SKILL.md 里总是习惯写清楚“前一个技能输出什么字段后一个技能读取什么字段”甚至在关键节点要求模型“必须确认前一步已完成再推进”。听起来有点“死板”但 Agent 工程最怕的就是不可控这种刻板反而带来了确定性。5. 应用场景案例拆解一个内容采集 Skill 的完整落地记录本节挑一个更加“业务向”的真实案例来展示因为周报那个例子偏通用现在讲一个“竞品动态监控助手”的技能。这个场景是很多运营和产品团队的真实痛点每天都要人工去翻竞品官网、公众号、新闻源整理成摘要费时费力。我通过 Agent Skills 把整条链路做了自动化。5.1 技能结构设计我给这个技能命名为competitor-watch它的执行链路非常清晰输入竞品名称列表、监控时间范围动作爬取指定的 RSS 源、官方博客、新闻聚合页输出一份去重后的动态摘要按“产品更新、市场活动、人事变动、其他”四类归档整个技能内部不再是“模型自由发挥”而是每步都有对应的脚本支撑。5.2 SKILL.md 中的“小动作”设计在这个技能的 SKILL.md 里我设计了很多“小动作”这里挑两个最关键的示例一是对抓取源进行了强约束不要求模型自己去猜 URL二是对输出摘要字数与句式做硬性约束。下面是我的部分配置--- name: competitor-watch description: 监控竞品动态并生成日报。当用户需要了解某公司最近动态、竞品上新、或行业新闻汇总时使用。依赖 sources.yaml 确定抓取源。 --- # 执行步骤 1. 读取 sources.yaml确认本次监控的站点列表。 2. 依次对每个站点执行 python3 scraper.py --source {source_name} --days {days}将结果保存到 raw_results/ 目录。 3. 汇总 raw_results/ 中所有 JSON 文件剔除重复信息按四类归档。 4. 输出一份简明的中文简报每条动态不超过 50 字附原文链接。步骤 2 里没有写具体 Python 库或爬虫方案而是直接调用脚本这个设计非常关键它让模型其实是在“做调度”而非“做实现”。实现层全部由代码承包模型的自由度被约束在归类、总结、提炼这些它擅长的事情上。我也强烈建议读者在配置技能时把可编程部分尽量下沉到脚本里这真的是效率倍增器。5.3 依赖文件 sources.yaml 的作用sources.yaml是技能配置中容易被忽视但极其重要的一环。它让“配置”与“执行”分离后续新增监控源完全不需要改 SKILL.md只改这个 YAML 文件即可sources: - name: example_company_blog url: https://example.com/blog/rss.xml type: rss - name: example_company_news url: https://example.com/news type: html5.4 运行效果与问题复盘实测这个技能上线第一周我原本预期它能把准确率拉到 90% 以上结果只有 70% 多。排查下来发现两个问题非常有代表性一是模型在判重时过于机械只是看标题文字是否一样没有理解两篇文章可能是同一个产品的不同角度的报道导致大量漏掉。后来我在指令里加了“判重时需结合正文核心语义判断标题类似但角度不同视为两条”准确率立刻提升了。二是模型在解析 HTML 页面的正文时经常带上导航栏文字摘要里出现“首页、产品、关于我们”这类垃圾信息。最终解决方案是在脚本层面做了一个“正文清洗”的预处理只向模型喂入清洗后的正文问题才彻底消除。5.5 从技术“能跑”到业务“好用”从技术角度讲上述步骤执行完已经能自动生成竞品报告了。但从业务角度讲还差最后一步“水温校准”我们团队发现报告模板里直接放抓取到的所有信息使用率反而低因为核心信息被淹没在大量一般动态里。后来我在指令里加了一条“将当天最重要的三件事提取到开头作为快讯”这个改动直接让周报在业务团队里打开了局面。这再次印证了一个道理技能的价值在业务侧核心指标是“下游能不能直接消费”而不是“技术指标多好看”。6. 常见问题与排查技巧实录让 Agent 稳定执行不走样最后这部分集中回放我在实操里高频踩过的坑和排查方法。Skills 本身的语法不复杂真正磨人的是“在什么条件下它不按你的预期走”。6.1 技能未被调用与错误调用问题现象一用户需求已经命中了描述Agent 却还是“无视”技能自己去瞎回答。最可能的原因就是 description 覆盖面不够或者和用户说法差异过大。我的排查方式是故意用多个不同口语说法去触发测试然后逐个逼近。比如用户说“给我整理一下这个仓库这周的活”模型未必会联系到“周报”但如果你在 description 里写全了“整理、周报、每周进度、提交汇总”命中率就会高很多。现象二无关需求触发了技能行为非常奇怪。这个多半是 description 里写得太泛把“当用户提到某个行业”这个大类都吸收进去了。建议严格收敛把触发器限定在“动作对象”组合比如“用户需要总结代码库本周变更”而不是“用户说道代码库”。现象三技能被调用了但执行到一半就跳出流程。通常发生在模型遇到脚本报错或输出格式不对时。我会在 SKILL.md 中专门写一条“如果某步骤执行失败不要更换流程重试一次并报告失败原因”这能有效减少模型自己即兴发挥的概率。6.2 输出内容不合规与参数传递踩坑不合规的典型场景是你要求输出表格它给出一段带 Markdown 格式的长文本。这是上下文不明确导致的。建议把输出模板直接“贴”进 SKILL.md空字段留占位符模型大概率会照着填空。参数传递问题也常见尤其是有多个技能串行时前一个技能的 JSON 输出里字段命名和后一个技能的不一致直接导致后一个执行报错。最稳的办法是后一个技能读取参数时使用“.get(xxx)”式的兜底写法并在指令里注明“如果读取不到某字段请尝试使用备用字段名”。6.3 检查清单我把这些写进团队规范最后整理一份我内部一直使用的检查清单帮读者快速自检一个技能是否合格检查项自检标准description 触发词覆盖使用者的口语化说法吗执行步骤顺序是否绝对命令式是否存在模型自由发挥空间可编程部分是否下沉到脚本而不是写在自然语言里文件路径是否写全且与目录结构一致失败处理有无“重试一次并报告失败原因”的兜底逻辑输出模板是否附带明确的结构化模板上下文消耗是否避免在技能里存放无关背景资料6.4 排查思路心得真要说排查 Skills 故障最有效的手段还是开“调试模式”看模型的内部推理轨迹。如果平台支持打印“调用技能的全链路日志”一定打开。我在一次跨技能协作的 bug 里耗费了整整半天最后靠日志发现是模型在读取sources.yaml时序列化得到的是 Python 字典而后续脚本期望的却是一个 JSON 字符串。类似这种 K 型问题没有日志光靠猜是基本上找不到答案的。7. 结尾工具是冰冷的但规范让 Agent 真正可用做到这里你手里应该已经有一套可以落地的技能体系雏形了。如果你正从“写 Prompt”过渡到“做 Agent 工程”我的建议是别急着堆技能数量先拿一个最常用、重复度最高的任务反复打磨流程把它的 SKILL.md 写到“模型没有任何自由度发挥空间”的程度再复制这套经验到其他场景。Skills 这门技术本身不难掌握真正的分水岭在于你是否愿意用严谨的工程规范去约束它。一个写得好、边界清晰、带脚本支撑的技能绝对能顶得上十段长篇提示词的效果也会是你手上最靠谱的 AI 自动化资产之一。
Agent Skills深度拆解：从提示词到可复用工作流的工程实践
Agent Skills 这个能力刚出来的时候我周围不少朋友的第一反应是这不就是把提示词写得更规范了一点吗我当时没急着反驳但心里清楚事情没这么简单。如果你上手写过几个真正的 Agent 应用就会发现最大的痛点根本不是模型笨而是它每次都在“临场发挥”同一个任务可能这次输出这个格式下次又换个思路。你真正需要的是让 Agent 在特定场景下稳定复现一套成熟的工作流而不是每次去猜。Agent Skills 解决的就是这个问题它把“你希望 AI 怎么做”从一段可有可无的建议变成了一份可加载、可复用、可版本管理的显式“工作手册”。这篇文章我想从设计思路、配置细节、到实际项目里踩过的坑完整拆一遍这个机制给正在折腾 Agent 工程化的朋友一份能直接参考的实操笔记。1. 整体设计与思路拆解为什么 Agent 需要“技能”而不是“提示词”很多人第一次接触 Agent Skills 时会觉得这玩意儿看着就像是一个加强版的 System Prompt或者是一份预设好的指令模板。这么理解不算全错但会低估它在整个 Agent 架构里的真正位置。我个人的看法是Skills 本质上重构了“人跟 Agent 协作”的接口方式它把“要求式”协作变成了“调用式”协作。这两者的差别非常大。1.1 从“临场发挥”到“按需取用”在常规的 Prompt 工程里你通常是在系统提示词里写上一大段“你要做什么、要遵循什么流程、输出格式是什么”。这些指令确实有用但它是静态的。Agent 每次对话都会读到这些内容不管当前任务需不需要都得把这些上下文塞进窗口里既消耗宝贵的上下文长度又容易导致模型在无关任务上被这些指令干扰——它可能本来只是想帮用户查个天气结果你的长提示词里写满了代码风格要求它就会表现得特别拧巴。Agent Skills 的思路完全不同。它是把一套完整的工作流程、规范、注意事项打包成一个独立的“模块”平时不加载只有用户请求命中了这个技能的使用场景时Agent 才会主动去调用它。这就是“函数式”思维需要的时候 import不需要的时候完全不占用资源。从我实际使用的感受来看这种方式至少带来三个直接好处上下文长度更省、指令针对性更强、Agent 的行为可预测性大幅提升。1.2 把“你该怎么想”变成“你能用什么”再往深一层看Agent Skills 的底层设计哲学其实是从“告诉模型怎么思考”转向了“给模型提供可操作的工具和规范”。前者依赖模型当时的“临场理解能力”后者则把组织好的经验直接固化下来。尤其是当你的项目里有一些极其复杂的领域知识比如金融合规检查、医疗数据处理或者需要结合企业内部的 API 规范去做开发时——这些知识靠模型在推理时“回忆”是极不可靠的你也绝不应该指望它自由发挥。通过 Skill 把这套规范准确固化下来Agent 在相关场景下就不再是一个“泛泛而谈的聪明人”而更像一个“熟读规章制度的专业执行者”。这个转变一旦发生Agent 应用的上限就高了很多因为它照抄的是你验证过的最佳实践而不是它自己临时推理出来的某个“看起来可行”的方案。我对 Agent Skills 的整体判断是它的确不是最炫酷的底层技术但它可能是当前把 Agent 从“玩具”推向“生产力工具”最关键的一环。2. 核心细节解析与实操要点SKILL.md 里究竟该写什么既然决定入坑第一步肯定是搞清楚一个 Skill 到底长什么样。以目前主流平台的标准实现为例一个 Skill 本质上就是一个目录目录里有一个SKILL.md文件以及若干可选的其他文件比如参考代码、模板、数据集。SKILL.md是整个技能的核心它的内容质量直接决定技能的好坏。2.1 SKILL.md 的双层结构元信息与指令主体我看到不少人第一个版本写的SKILL.md就是一大段话“你是一个擅长写报告的人你应该……”——这其实又绕回了 Prompt 的老路。规范的做法是把它拆成两块YAML 元信息区和Markdown 指令区。YAML 元信息区里最关键的是name和description两个字段。description尤其重要因为模型就是靠它来判断“当前用户诉求是否应该调用这个技能”。我的建议是不要在 description 里堆形容词要写清楚“这个技能解决什么输入、能产出什么输出以及典型的使用场景”。Markdown 指令区则是技能的“灵魂”。这部分不必长篇大论地讲道理而是要明明白白写清楚执行的流程规范。2.2 一个技能一个职责内聚性是第一原则很多人容易犯的另一个错误是想把一个技能写成“万能工具箱”什么都往里塞。我见过一个同事写的 Skill 名叫“数据分析”里面既能处理 CSV、又能画图表、还能做时间序列预测、甚至兼职写 SQL——结果就是模型调用它的时候经常懵圈不知道到底该执行哪一步。这里我的经验是一条技能只解决一个核心任务一个岗位只负责一条结果链路。宁可把功能拆成多个技能也不要揉成一个“四不像”。如果你处理 Excel 的数据时需要有清理步骤和可视化步骤那就拆成excel_data_cleaner和excel_chart_builder两个技能串行调用效果远好于一个技能里塞两个模块——因为模型在单个技能内会更专注优先执行你定义的步骤顺序而不是自己“随机漫步”搞出别的花样。2.3 引用文件路径把细节从提示词里解放出来当技能逻辑比较复杂时不建议把所有细节都堆进SKILL.md正文。更好的做法是把可执行脚本、代码模板、参数配置放到同一目录下的其他文件里然后在指令区写上“调用脚本 xxxxx 来完成 xxx 任务”。这会让技能主文档保持精炼模型每次只需要读取最核心的执行策略具体怎么算、怎么调库直接交给携带的脚本去执行就好。我在实际项目里养成了一个习惯凡是能用代码实现的过程绝不写进自然语言指令。拿生成报表来说我不会在SKILL.md里写“请使用 pandas 读取数据并计算均值”而是直接写好一个compute_summary.py指令里只写一句话“运行 compute_summary.py参数传入数据文件路径它会生成一份 summary.json后续的 Markdown 表格基于这个 JSON 生成。” 这样模型的操作路径立刻就从“思考用什么代码”变成了“按既定规范执行脚本”出错率大幅下降。3. Agent Skills 工程化实操从零搭建与核心字段精讲聊完了理念直接上手。我在这里用的一个实操场景是构建一个“技术周报自动生成”技能。选择它是因为周报场景在职场里极其普遍理解门槛低同时又能覆盖到 Skills 配置中的多数关键字段比较适合作为演示案例。3.1 建立目录与文件结构我习惯按“一个技能一个文件夹”的方式来组织agent-skills/ ├── weekly-report/ │ ├── SKILL.md │ ├── collect_git_log.sh │ └── templates/ │ └── weekly_report_template.md目录结构就位后核心是填充SKILL.md的内容。下面这个配置我经过多次调优几个字段值都直接影响调用效果逐个说明。3.2 SKILL.md 规范配置与字段解读--- name: weekly-report-generator description: 根据 Git 仓库的提交记录和当前日期生成符合规范的中文技术周报。当用户需要撰写周报、汇总一周工作或需要提交项目进度报告时使用。 ---这里最需要注意的就是 description 的写法和位置。name 字段是技能的唯一标识命名尽量用连字符分隔的小写单词方便识别和调用description 是整个技能的“触发开关”位置靠前但要确保它覆盖到“什么时候该调用这个技能”的全部常见说法。我特别加了“当用户需要……”这种句式模型对这种触发场景的描述非常敏感。尤其是“中文技术周报”这个词我一并放进触发描述里模型就更不容易漏判使用者其实是想要英文版本的需求。接下来是正文的“执行指令区”这是技能的心脏我按典型的“任务流”编写# 执行步骤 当你收到周报生成请求后严格按以下顺序执行 1. 切换到目标 Git 仓库根目录运行 ./collect_git_log.sh它会自动提取最近 7 天的提交记录保存到 git_log.txt。 2. 打开 git_log.txt以“工作内容”为维度将提交信息归类为功能开发、缺陷修复、技术调研、团队协作四类。 3. 使用 templates/weekly_report_template.md 中的模板根据归类后的信息填充周报内容。 4. 填充完毕后检查所有条目是否都有具体动作和结果说明避免只有动词没有对象的空洞描述。 # 补充规范 - 提交信息里的 commit 大概率不规范不要原样粘贴请转成符合商务沟通习惯的书面表达。 - 如果某个分类下没有内容直接删除该分类不要留空。 - 周报中的日期范围以脚本输出的起止日期为准。 - 文本组织使用礼貌、简洁的中文篇幅控制在 400 字以内。这份指令区的写法核心在于把每个操作步骤的前后依赖关系明明白白地交代清楚。注意我没有用“请尝试”“你可以考虑”这类模糊用语全部换成了“运行”“打开”“填充”“检查”这样的“命令式”操作。模型在处理这种高确定性指令时执行稳定性会明显提高如果你用商量语气反倒会让模型陷入过度思考输出不稳定。3.3 辅助脚本与模板设计collect_git_log.sh我写得很“无脑”#!/bin/bash since$(date -d 7 days ago %Y-%m-%d) until$(date %Y-%m-%d) echo 周报周期: $since ~ $until git log --since$since --until$until --prettyformat:%h|%an|%s --no-merges模板我用了最简单的占位结构# 技术周报{date_range} ## 功能开发 - {描述做了什么} ## 缺陷修复 - {描述修了什么} ## 技术调研 - {调研了什么结论如何}3.4 把技能挂载到 Agent路径与生效技能写完后如何让 Agent 真正“装上”它不同平台挂载位置不同但原理一致把技能目录放到 Agent 能扫描到的技能根目录下。以当前主流做法为例通常在 Agent 客户端或配置页的指定路径下创建skills目录把技能文件夹放到这里然后重启会话。挂载完成后你可以试着对 Agent 说一句“帮我生成本周的技术周报”观察它是否会自动识别并切入技能调用流程。这里有一个非常重要的排查经验很多朋友加载技能后一点反应都没有大概率不是代码写错了而是触发描述没写准。你可以做个快速自测——把自己写的 description 遮住想象你是模型看到用户说“总结一下这周的进展”你能不能百分百确定要调这个技能如果不能说明描述需要加关键词。实际调试时我和同事的习惯是建一个专门的测试会话把所有可能触发该技能的说法都试一遍确保命中率满意后再正式启用。4. Agent Skills 工程化实战从单技能到技能体系理解了 SKILL.md 的写法下一步就要考虑如何把 Skills 用到真实的 Agent 工程里。这里指的是更复杂的“技能体系”比如多个技能之间如何配合、参数如何传递、上下文如何共享。4.1 技能生命周期管理创建、测试、版本化把 Agent Skills 当作代码来管理是我从实践中总结出的最重要一条经验。既然是代码就要有生命周期开发、测试、发布、维护、退役。市场上很多团队写技能的方式非常“原始”直接丢给 ChatGPT 或 Claude 写好就上线出问题就在原文件上改改完也没记录最后谁都不知道线上跑的到底是哪一版。我现在的习惯是给每个 Skill 建立 Git 仓库并有意识地控制版本。假设你写好了weekly-report-generator的 v1.0 版本合入主干之前要跑一遍“最小验证集”就是用几条真实历史数据让 Agent 调用这个技能确认产出合格才能标记 release。上线后如果发现需要修正就在分支上改触发问题后提交 PR同事 review 通过再合入。这样经过几轮迭代你的技能会越来越稳定而且每个版本“为什么这么改”都有据可查。4.2 技能的组织与命名可被发现性技能多了之后最大的挑战就是“内耗”agent 可能选错了技能、也可能两个技能重复覆盖某类任务。所以我们团队内部对技能命名和描述有以下几条硬性约束这里分享给读者参考命名必须“所见即所得”比如一个专门负责把数据转成折线图的技能直接叫line-chart-generator不要叫visualizer_utils这种谁都看不懂的名字。描述里必须写清“边界”比如“本技能只适用于 2024 年后的数据格式老数据请使用 xxx 技能”。技能之间不要有交叉职责如果一个技能处理了另一个技能的触发场景说明职责划分有问题重新切分。我在项目中实际维护的技能就有 20 多个命名规范但边界不清晰时Agent 还经常“纠结”该用哪个。后来我们强制在 description 里增加了“优先级提示词”比如“如果用户要求是粗略分析请优先使用 quick-scan如果是详细报告再用 deep-dive”问题立刻缓解。指令里一点点的结构化设计就能显著提升 Agent 在复杂技能体系下的选择准确率。4.3 技能间的协作编排串行、并行与条件分支单个技能再强也只是一个零件。真实业务里往往需要多个技能配合才能完成一条完整工作流。比如客服机器人处理售后问题可能需要先调用order-lookup查订单再调用refund-policy-checker查退款规则最后用response-composer生成回复。这里我就把技能编排成“有向无环图”的感觉每个技能是一个节点每个节点的输出是下一个节点的输入。Agent 的模型本身具备这种“串行调用”的能力但你不去刻意设定顺序时它有可能会跳过某些步骤。所以我在 SKILL.md 里总是习惯写清楚“前一个技能输出什么字段后一个技能读取什么字段”甚至在关键节点要求模型“必须确认前一步已完成再推进”。听起来有点“死板”但 Agent 工程最怕的就是不可控这种刻板反而带来了确定性。5. 应用场景案例拆解一个内容采集 Skill 的完整落地记录本节挑一个更加“业务向”的真实案例来展示因为周报那个例子偏通用现在讲一个“竞品动态监控助手”的技能。这个场景是很多运营和产品团队的真实痛点每天都要人工去翻竞品官网、公众号、新闻源整理成摘要费时费力。我通过 Agent Skills 把整条链路做了自动化。5.1 技能结构设计我给这个技能命名为competitor-watch它的执行链路非常清晰输入竞品名称列表、监控时间范围动作爬取指定的 RSS 源、官方博客、新闻聚合页输出一份去重后的动态摘要按“产品更新、市场活动、人事变动、其他”四类归档整个技能内部不再是“模型自由发挥”而是每步都有对应的脚本支撑。5.2 SKILL.md 中的“小动作”设计在这个技能的 SKILL.md 里我设计了很多“小动作”这里挑两个最关键的示例一是对抓取源进行了强约束不要求模型自己去猜 URL二是对输出摘要字数与句式做硬性约束。下面是我的部分配置--- name: competitor-watch description: 监控竞品动态并生成日报。当用户需要了解某公司最近动态、竞品上新、或行业新闻汇总时使用。依赖 sources.yaml 确定抓取源。 --- # 执行步骤 1. 读取 sources.yaml确认本次监控的站点列表。 2. 依次对每个站点执行 python3 scraper.py --source {source_name} --days {days}将结果保存到 raw_results/ 目录。 3. 汇总 raw_results/ 中所有 JSON 文件剔除重复信息按四类归档。 4. 输出一份简明的中文简报每条动态不超过 50 字附原文链接。步骤 2 里没有写具体 Python 库或爬虫方案而是直接调用脚本这个设计非常关键它让模型其实是在“做调度”而非“做实现”。实现层全部由代码承包模型的自由度被约束在归类、总结、提炼这些它擅长的事情上。我也强烈建议读者在配置技能时把可编程部分尽量下沉到脚本里这真的是效率倍增器。5.3 依赖文件 sources.yaml 的作用sources.yaml是技能配置中容易被忽视但极其重要的一环。它让“配置”与“执行”分离后续新增监控源完全不需要改 SKILL.md只改这个 YAML 文件即可sources: - name: example_company_blog url: https://example.com/blog/rss.xml type: rss - name: example_company_news url: https://example.com/news type: html5.4 运行效果与问题复盘实测这个技能上线第一周我原本预期它能把准确率拉到 90% 以上结果只有 70% 多。排查下来发现两个问题非常有代表性一是模型在判重时过于机械只是看标题文字是否一样没有理解两篇文章可能是同一个产品的不同角度的报道导致大量漏掉。后来我在指令里加了“判重时需结合正文核心语义判断标题类似但角度不同视为两条”准确率立刻提升了。二是模型在解析 HTML 页面的正文时经常带上导航栏文字摘要里出现“首页、产品、关于我们”这类垃圾信息。最终解决方案是在脚本层面做了一个“正文清洗”的预处理只向模型喂入清洗后的正文问题才彻底消除。5.5 从技术“能跑”到业务“好用”从技术角度讲上述步骤执行完已经能自动生成竞品报告了。但从业务角度讲还差最后一步“水温校准”我们团队发现报告模板里直接放抓取到的所有信息使用率反而低因为核心信息被淹没在大量一般动态里。后来我在指令里加了一条“将当天最重要的三件事提取到开头作为快讯”这个改动直接让周报在业务团队里打开了局面。这再次印证了一个道理技能的价值在业务侧核心指标是“下游能不能直接消费”而不是“技术指标多好看”。6. 常见问题与排查技巧实录让 Agent 稳定执行不走样最后这部分集中回放我在实操里高频踩过的坑和排查方法。Skills 本身的语法不复杂真正磨人的是“在什么条件下它不按你的预期走”。6.1 技能未被调用与错误调用问题现象一用户需求已经命中了描述Agent 却还是“无视”技能自己去瞎回答。最可能的原因就是 description 覆盖面不够或者和用户说法差异过大。我的排查方式是故意用多个不同口语说法去触发测试然后逐个逼近。比如用户说“给我整理一下这个仓库这周的活”模型未必会联系到“周报”但如果你在 description 里写全了“整理、周报、每周进度、提交汇总”命中率就会高很多。现象二无关需求触发了技能行为非常奇怪。这个多半是 description 里写得太泛把“当用户提到某个行业”这个大类都吸收进去了。建议严格收敛把触发器限定在“动作对象”组合比如“用户需要总结代码库本周变更”而不是“用户说道代码库”。现象三技能被调用了但执行到一半就跳出流程。通常发生在模型遇到脚本报错或输出格式不对时。我会在 SKILL.md 中专门写一条“如果某步骤执行失败不要更换流程重试一次并报告失败原因”这能有效减少模型自己即兴发挥的概率。6.2 输出内容不合规与参数传递踩坑不合规的典型场景是你要求输出表格它给出一段带 Markdown 格式的长文本。这是上下文不明确导致的。建议把输出模板直接“贴”进 SKILL.md空字段留占位符模型大概率会照着填空。参数传递问题也常见尤其是有多个技能串行时前一个技能的 JSON 输出里字段命名和后一个技能的不一致直接导致后一个执行报错。最稳的办法是后一个技能读取参数时使用“.get(xxx)”式的兜底写法并在指令里注明“如果读取不到某字段请尝试使用备用字段名”。6.3 检查清单我把这些写进团队规范最后整理一份我内部一直使用的检查清单帮读者快速自检一个技能是否合格检查项自检标准description 触发词覆盖使用者的口语化说法吗执行步骤顺序是否绝对命令式是否存在模型自由发挥空间可编程部分是否下沉到脚本而不是写在自然语言里文件路径是否写全且与目录结构一致失败处理有无“重试一次并报告失败原因”的兜底逻辑输出模板是否附带明确的结构化模板上下文消耗是否避免在技能里存放无关背景资料6.4 排查思路心得真要说排查 Skills 故障最有效的手段还是开“调试模式”看模型的内部推理轨迹。如果平台支持打印“调用技能的全链路日志”一定打开。我在一次跨技能协作的 bug 里耗费了整整半天最后靠日志发现是模型在读取sources.yaml时序列化得到的是 Python 字典而后续脚本期望的却是一个 JSON 字符串。类似这种 K 型问题没有日志光靠猜是基本上找不到答案的。7. 结尾工具是冰冷的但规范让 Agent 真正可用做到这里你手里应该已经有一套可以落地的技能体系雏形了。如果你正从“写 Prompt”过渡到“做 Agent 工程”我的建议是别急着堆技能数量先拿一个最常用、重复度最高的任务反复打磨流程把它的 SKILL.md 写到“模型没有任何自由度发挥空间”的程度再复制这套经验到其他场景。Skills 这门技术本身不难掌握真正的分水岭在于你是否愿意用严谨的工程规范去约束它。一个写得好、边界清晰、带脚本支撑的技能绝对能顶得上十段长篇提示词的效果也会是你手上最靠谱的 AI 自动化资产之一。