如果你也在折腾AI Agent一定遇到过这种场景模型能力很强工具也接了一堆可它一遇到稍微复杂的情况就掉链子要么压根不知道该调什么要么调了却用不对参数。我前段时间接手一个内部自动化项目就卡在这上面很久。后来把重心从“多接工具”转向“把技能做扎实”问题才算真正解开。“agent-skills”这个词字面上是智能体技能往深了说它指的是让大模型在特定场景下稳定完成任务的一套能力封装方式。它不是某一个具体的开源仓库而是一类工程实践的统称把模型需要掌握的做事方法、边界约束、参考案例、执行步骤打包成可复用、可维护、可被模型自动识别调用的单元。这篇文章我会从技能是什么、怎么设计、怎么写、怎么调试这几个角度把自己踩过的坑和真正管用的做法一起整理出来。1. 先给agent-skills定个性它解决的是“会”而不是“有”的问题1.1 工具、技能、工作流三个概念别混在讨论agent-skills之前必须先把几个经常被混在一起的概念拆开。工具tools是最底层的能力出口它负责执行具体的动作比如发请求、查数据库、调API、操作文件。工具本身不带“什么时候该用”的上下文它只是被调用的函数。技能skills则高一层。它描述的是“怎么做成一件事”的方法论包含触发条件、执行步骤、边界约束、参考样例。技能可以调用多个工具也可以不调用工具纯粹指导模型按特定方式思考。工作流workflows是更高阶的编排它把技能和工具串成固定的业务路径通常有明确的顺序和分支。我用一个生活化的例子解释工具是菜刀和砧板技能是“怎么切土豆丝”的完整手法工作流是“今天做一桌四人餐”的全流程安排。很多项目的问题就出在只堆了菜刀却没教模型怎么切。你给Agent接了十个API它可能在错误的时候调了错误的接口或者在需要组合使用的时候只调了其中一个。agent-skills补的正是中间这一层——让模型不仅“有工具”而且“会干活”。1.2 一套完整的技能单元应该长什么样我见过不少技能写得草率的项目一个函数套一段prompt就算完事。实际跑起来以后模型发挥极其不稳定。经过反复迭代我现在理解的完整技能单元至少包含四块内容第一是元信息包括技能名称、版本、用途描述。名称要唯一且语义清晰描述要写清楚“什么场景下触发”这是模型选择技能的主要依据。第二是执行指令也就是技能的正文部分。这里写具体的操作步骤、思考方式、输出格式、注意事项。执行指令的质量直接决定技能的上限。第三是参考资产包括示例输出、模板文件、常见问题对照表、少量Few-shot样本。参考资产用来稳定输出的格式和质量尤其重要。第四是依赖关系写清楚这个技能需要哪些工具、依赖哪些环境变量、是否需要用户二次确认。你可以把这四块想象成给新员工写的SOP手册目录元信息、操作流程执行指令、模板样例参考资产、需要找谁协调依赖关系。缺了任何一块新员工都可能把事情办歪。对Agent来说这套手册就是它与生俱来的“岗位培训材料”。2. 技能设计阶段最重要描述写不好后面全白搭2.1 技能粒度怎么定一个让人反复踩坑的问题第一次搭技能库的时候我犯过一个很典型的错误把技能拆得太细。当时觉得“原子化”是好的于是把“查订单”“算金额”“发通知”都拆成一个个独立技能结果模型在真实任务里要连续调五六个技能才能完成一件事中间只要有一次判断失误整个流程就断了。后来我又走到另一个极端把一整套业务流程塞进一个技能里看起来一步到位但灵活性又没了。用户改一个环节的需求就得改整个技能文件。现在我自己用的标准是一个技能应该对应一个完整的“可交付结果”。什么叫可交付结果就是这件事做完之后能产生一个明确、独立、可以被检查的产物。比如“生成周报数据摘要”是一个技能因为它产出的是摘要文档“查数据库”就不是技能它只是一个步骤“完成客户全流程跟进”也不是技能它太大横跨了多个角色和多次交互。在这个原则下技能的粒度以“三到八个步骤能完成”为宜。步骤太少说明它可能只是一个工具调用步骤太多说明它应该被拆成多个技能或升级为工作流。2.2 description这样写模型才会正确命中技能描述description是模型判断“该不该用这个技能”的第一依据但它恰恰是最容易被忽略的部分。很多项目的description写成这样“处理报表相关任务”。这种描述等于没写。模型面对多个技能时根本分不清“报表相关”包不包括“把Excel转换成PDF”“统计销售额环比”这些具体操作。我后来总结了一套description的写法核心是“用触发场景倒推描述”明确用户可能怎么说把用户口语化的表达列出来比如“帮我看看这周数据咋样”“这月业绩出来了没”。明确任务的输入和输出描述里直接写清楚“输入是一个时间段输出是包含同比/环比的Markdown报告”。明确边界写清楚“本技能不处理账单导出”防止模型越权调用。举个我实际用过的例子name: weekly-report-generator description: 当用户要求生成本周/本月/指定时间段的业务数据报告时使用本技能。 典型说法包括“帮我出个周报”、“这周数据怎么样”、“生成一份销售分析”。 输入为时间段输出为包含摘要、趋势图表、异常提醒的Markdown报告。 本技能不处理财务报表不生成PDF文件。这样写的好处是模型在进行技能匹配时能够通过语义相似度准确命中而不是靠运气。2.3 指令文本里的“边界感”要划清楚技能的指令文本经常被人写成一段“鼓励文”洋洋洒洒几百字都在讲“你要认真分析”“你要全面考虑”结果模型执行起来还是天马行空。我的经验是指令文本要重点划清楚三个边界第一是行为边界。明确告诉模型“不要做什么”。比如一个报告生成技能里要写明“不访问外部网络”“不修改原始数据文件”“不生成超出输入时间范围的数据”。第二是输出边界。规定输出格式、长度、层级。比如“摘要不超过200字”“所有数字保留两位小数”“异常项必须用加粗标出”。模型的输出如果不可控下游解析就会跟着崩。第三是中断边界。写明“什么情况下必须停下来问用户”。比如“当输入数据缺失超过30%时不要自行推断必须询问用户是否继续”。指令文本里也建议包含一个“负向样例”也就是告诉模型“不要像这样执行”。我试过在技能文件里加一小段“反例说明”模型的错误率能再降一截。3. 从零搭建一个技能库的实操记录3.1 先定目录结构一个技能一个文件夹技能库的目录结构没有统一标准但有一个原则我非常认同一个技能一个独立文件夹所有相关文件都放里面。这是为了可维护性。如果所有技能都堆在一个大文件里改一个技能动辄影响全局拆到独立目录后每个技能可以单独改、单独测试、单独回滚互不干扰。我目前常用的结构长这样skills/ ├── weekly-report/ │ ├── SKILL.md │ ├── assets/ │ │ ├── report_template.md │ │ └── example_output.md │ └── scripts/ │ └── query_builder.py ├── customer-followup/ │ ├── SKILL.md │ └── assets/ │ └── tone_guide.md └── intent-classifier/ ├── SKILL.md └── assets/ └── label_set.txtSKILL.md是入口文件承载元信息和执行指令assets放参考模板、示例输出、领域知识文本scripts放这个技能专用的辅助脚本。有些技能还会带data/目录放技能运行时需要读取的静态数据比如汇率表、产品分类词典。这些内容不适合写进prompt太占token放在目录里按需读取是更好的选择。3.2 SKILL.md的写法与一个完整示例SKILL.md的格式可以参考很多开源项目通用做法前面是YAML frontmatter写元信息后面是正文写指令。一个我实际用过的示例经过脱敏和简化--- name: weekly-report description: 当用户要求生成周报/月报/时段报表时触发。输入时间段 输出包含概览、关键指标、趋势说明、异常提醒四部分的Markdown报告。 不处理财务审计报表不自动发送邮件。 version: 1.2.0 dependencies: tools: - query_metrics - render_chart env: - REPORT_DATA_DIR --- # 周报生成技能 ## 任务目标 根据指定的时间段从指标库中获取数据生成结构化的周报。 ## 执行步骤 1. 从用户输入中解析起始日期和结束日期。如果用户只给了模糊描述 比如“上周”“最近一个月”按以下规则换算 - 上周自然周周一到周日 - 最近一个月自然月1号到月末 2. 调用 query_metrics 工具按天粒度拉取核心指标。 注意只拉取用户关心的指标不要一次性拉取全量数据。 3. 调用 render_chart 生成关键指标的走势图SVG格式。 4. 按模板生成报告放入 assets/report_template.md 中的结构。 ## 输出要求 - 概览小结控制在150字以内突出变化最大的指标 - 所有百分比保留一位小数所有金额保留两位小数 - 异常提醒必须加粗说明异常所属日期和可能原因如果数据中有 - 不要编造数据任何缺失的数据项要明确标注“无数据” ## 禁止事项 - 不要在报告中加入个人判断或主观建议 - 不要访问除指标库以外的任何数据源 - 不要修改assets目录下的模板文件这个文件看起来不算长但真正执行时模型依据它就能稳定产出合格报告。关键点在于执行步骤足够具体、输出要求可检查、禁止事项划清了边界。3.3 用一段简单的加载与匹配逻辑把它们串起来有了技能文件之后需要在代码里实现加载和匹配。这里的实现不用很复杂一个基础的版本管理逻辑就能跑通大部分场景。import yaml from pathlib import Path from typing import Dict, List class SkillRegistry: def __init__(self, skills_dir: Path): self.skills_dir skills_dir self.skills: Dict[str, dict] {} self._load_all() def _load_all(self): for skill_folder in self.skills_dir.iterdir(): md_file skill_folder / SKILL.md if not md_file.exists(): continue with open(md_file, r, encodingutf-8) as f: content f.read() # 解析 frontmatter 和正文 meta, instructions self._parse_md(content) self.skills[meta[name]] { meta: meta, instructions: instructions, path: skill_folder, } def match(self, user_query: str, model_funcNone): model_func 是一个接受 query 和候选技能列表返回最佳技能名的函数。 在真实项目中这里可以用 embedding 相似度做预筛再交给 LLM 做最终选择。 candidates [ {name: name, description: info[meta][description]} for name, info in self.skills.items() ] if model_func: chosen model_func(user_query, candidates) return self.skills.get(chosen) # 若没有传 model_func则用简单的关键词匹配兜底 for name, skill in self.skills.items(): desc skill[meta][description] if name in user_query or any(word in user_query for word in desc.split()): return skill return None这个实现里_parse_md负责切割YAML和正文match负责给模型返回候选技能列表。实际项目中匹配层会用embedding计算用户查询与技能描述的相似度取Top K再交给LLM裁决。写到这里想到一个容易忽略的细节每次构建candidates列表时description不要太长。因为一次性把所有技能的完整描述都塞给模型会大量占用上下文窗口而且模型在长列表中更容易选错。控制在每个技能一句话描述效果最好。3.4 技能之间的依赖与复用技能库规模大了以后技能之间必然出现重复逻辑。比如“解析时间段”这个能力周报技能要用销售统计技能也要用。如果同一个逻辑复制到每个技能文件里后期修改会很痛苦。我的做法是把公共逻辑提取成“内部技能”或工具函数不在SKILL.md里重复写完整步骤而是写一个引用说明“本技能的时间解析逻辑复用common/time-parser技能调用方式见该技能目录”。这样做的代价是模型需要多一步跳转但换来的是改动一处、全局生效。目前来看利远大于弊。注意依赖关系不要写成环。我曾一度把A技能依赖B、B又依赖A结果测试时模型陷入了循环判断日志刷了几百行都没结束。后来在注册表里加了一个依赖检测加载时检查是否成环有问题直接报错这个问题就再没出现过。4. 技能库上线后的调试与维护4.1 模型就是不调用对应技能怎么排查这是群里被问得最多的一个问题技能写好了日志显示候选列表也包含它但模型就是不选。根据我的经验按顺序排查这三件事第一看description是不是“自说自话”。如果描述里写的是“本技能用于生成周报”而不是“当用户想要一周的数据总结时”模型很难把它和用户的真实口语关联起来。把描述改成从用户视角出发的触发语句命中率会明显提升。第二看候选列表太多。如果一次给模型塞了三十个技能再强的模型也容易眼花。建议用embedding先做粗筛只把Top 5到Top 8的技能描述送进决策上下文。第三看是不是技能描述之间太像。比如“生成销售周报”和“生成销售月报”两个技能描述如果都写“生成销售报告”模型大概率会选错。这时候要在描述里刻意拉开差距突出时间维度和模板差异。还有一个容易被忽略的原因模型指令里如果存在“优先使用工具A”之类的固定倾向也会盖过技能匹配结果。排查时可以暂时把系统提示词简化为最小配置看看技能命中率是否恢复正常。4.2 技能冲突与覆盖如何避免当技能库超过几十个之后冲突问题就会浮出水面。一种冲突是语义重叠。比如新加了一个“销售数据分析”技能和已有的“销售周报”技能职责划分不清晰。模型可能一会儿调用这个一会儿调用那个输出风格不一致。解决方式是建立技能“职责边界表”每周或每隔一段时间过一遍所有技能名称和一句话描述发现语义距离过近的要么合并要么在description里互斥声明“当需要日期趋势对比时用A当需要单日明细时用B”。另一种冲突是文件覆盖。多个技能引用了同一个资源文件其中一个技能更新了文件另一个技能的行为就受影响。避免方法引用3.4里提到的原则公共资源单独存放技能间不共享可变文件。4.3 版本迭代技能改了之后怎么回归测试技能文件是文本改起来很容易但正因为容易很多人改完不验证就直接上线结果模型在部分场景下出现诡异行为。我现在强制自己给每个技能维护一个小的示例集每个示例包含输入语句、期望调用的技能名、期望的输出结构。技能修改后用这个示例集做回归命中率低于95%就说明这次改动引入了问题。def regression_test(skill_name: str, cases: list): registry SkillRegistry(PATH) failure 0 for case in cases: result registry.match(case[query]) if result is None or result[meta][name] ! case[expected_skill]: failure 1 print(fFAIL: {case[query]}, expected {case[expected_skill]}) print(f{skill_name}: {len(cases) - failure}/{len(cases)} passed)不要小看这个土办法它已经帮我抓出过至少十几次“看似没问题其实破坏了既有能力”的修改。4.4 常见问题速查表现象可能原因处理动作模型从不选某个技能description写得过于抽象改写描述加入用户口语触发词多个技能都被触发技能职责边界不清拆分或互斥声明建立职责边界表技能执行到一半停止指令缺少中断条件在指令中补充“遇到XX情况时询问用户”输出格式偶尔漂移缺少样例和模板在assets里增加两份以上示例输出技能库加载耗时过长技能文件过多或过大做懒加载只在命中时读取完整指令改了公共资源影响多个技能依赖关系没理清公共资源单独版本化技能引用固定版本这张表是我实际排查问题的沉淀建议你在搭建技能库时直接拿去做Checklist。我个人在实际操作中的体会是agent-skills的价值不在于写多少漂亮的Markdown文件而在于能不能让模型稳定、可控、可预期地完成真实任务。它是一门“磨刀”的功夫磨好了后面所有Agent应用都会顺很多。最后再分享一个小技巧每个技能文件里都写一段“变更记录”哪怕只有一行说明今天改了什么、为什么改。技能库运行两三个月之后这段记录会变成你调试时最宝贵的线索来源。别嫌麻烦等你真正需要回看一个技能为什么这么写的时候会感谢当初敲下那几行字的自己。