skills 这个词在 AI Agent 开发里最近被频繁提起。很多人第一反应是“技能”其实在 Agent 的世界里Skills 指的是一套可以被模型按需加载的指令、流程、脚本和参考资料的集合。它不是简单地把 Prompt 写长一点而是让 Agent 在高价值、重复性任务上保持稳定的水准。这篇文章我会从一个实际项目的角度聊聊技能文件的组织方式、触发逻辑、踩过的坑以及最后怎么把它真正跑起来。如果你正在做 Agent、自动化工作流或者研究提示工程这篇应该能帮你避开不少新手才会遇到的坑。1. 先说清楚Agent Skills 到底是个什么东西1.1 为什么我不说它是“超级 Prompt”我发现很多人第一次听说 Skills 时以为这就是“把提示词写得更好一点”。这个理解不能说全错但会错过关键的地方。传统 Prompt 最大的问题在于所有信息都塞进上下文里模型每次都要“大海捞针”。你今天告诉它“搜资料时要用 GET 请求”明天它可能就忘了因为它要处理的信息太多了。而且 Prompt 越长模型越容易在无关信息上分心。我更愿意把 Skill 理解成“给 Agent 装了一个可检索的工具箱”。举个生活化的类比团队来了一个新实习生你给他一张 A4 纸写上“遇到问题先查手册”他大概率还是会手足无措。但你如果给他一套“问题处理流程卡”——第一张卡说“先判断错误类型”第二张卡说“如果是网络错误就重试三次”第三张卡说“如果是权限错误就找到负责人”——他就能按图索骥。这套卡片其实就是 Skill 的结构。Skill 并不是一段孤零零的提示词它是一个独立模块通常包含说明文档、配套脚本、参数定义和触发条件。模型在收到一个任务时会先判断这个任务适合走哪张“流程卡”然后把卡片内容读到上下文里执行。这样既能控制上下文长度又能让每一步操作有章可循。1.2 Skills 和普通 Prompt 的最大区别如果要我用一张表总结大概是这样的维度普通 PromptSkills加载方式每次全量注入按需匹配后注入结构纯文本靠约定维持结构化文件 脚本 元数据复用性复制粘贴到别处放在目录里随处可用唯一性容易出现同名概念冲突通过名称和内容进行隔离可维护性改动后难以追溯有版本、有目录、有测试用例关键区别在于“按需加载”。举个例子我现在做一个本地 Agent它既要能查天气又要能算股票收益率还要能改代码格式。如果这三个能力全塞进一个巨型 Prompt每次对话都会消耗大量 token而且模型可能会把“查天气”的规则误用到“改代码”上。而用 Skills 拆开后模型遇到天气问题就只加载天气技能遇到代码问题就只加载代码技能互不干扰。还有一点很重要某些 Agent 框架支持在技能里声明“这个技能需要哪些工具权限”比如某个技能要执行 shell 命令另一个技能只读文件。这相当于给 Agent 加了一层权限边界而不是把所有能力都混在一起。1.3 一个最简单的 Skill 长什么样很多成熟的 Agent 产品里Skill 以目录 文件的形式存在。我以前端常用的某个 Agent 为例它会读取.agent/skills目录下的每个子目录每个子目录就是一个 Skill。一个最简单的 Skill 长这样.agent/skills/ weather_check/ SKILL.md scripts/ get_weather.pySKILL.md是这个技能的核心前端部分包含元信息后面是正文指令。比如下面这段就是从实际项目里简化来的--- name: weather_check description: 当用户询问某地当前天气或未来天气预报时使用此技能。不要在其他场景调用。 allowed-tools: - python3 --- # Weather Check 根据用户提供的城市名运行以下脚本获取天气信息 bash python3 scripts/get_weather.py --city 城市名输出格式城市名称当前温度天气状况建议是否需要带伞等配套的脚本 get_weather.py 负责真正的数据请求。这个例子看着简单但它已经体现了 Skills 最重要的四个部分触发描述、工具权限、执行指令、输出约定。后面我会一个个拆开讲。 当然你也可以把纯文本提示词做成 Skill。比如“翻译语气优化”这种不需要跑脚本的技能只要在 SKILL.md 里告诉模型该怎么改写译文就行。灵活度很大关键是结构清晰。 --- ## 2. 一个好 Skill 的设计拆解让模型“会看、会挑、会用” ### 2.1 描述写得不好技能等于白写 很多新手刚开始写 Skill 时在 description 里只有一句话“这个技能用于搜索”。结果就是 Agent 根本不知道什么时候该用它甚至从来不会调用。 一个真正能用的描述要回答三个问题什么时候用、什么时候不用、用了之后会改变什么。我给你对比一下 - 糟糕的描述description: 搜索信息 - 能用的描述description: 当用户需要查找最新新闻、验证某个事实或获取实时数据时使用。在回答常识性问题时不要使用。 第二种描述之所以有效是因为它同时给了正面信号和负面信号。模型在意图识别阶段只需要做“这个任务像不像这个描述”的判断我们描述得越具体它的判断就越准。 我在实际项目里还会习惯性加一句“如果用户只是让我解释概念不要使用”。这句话看似多余却能大幅降低误触发率。这是真实踩坑之后总结出来的我最初没写这条限制时Agent 在回答“什么是 JSON”这种问题时居然也会去调用搜索技能白白浪费了好几秒时间。 ### 2.2 粒度怎么控制 Skills 的粒度是个很微妙的话题。太小了比如“读取文件”和“写入文件”各做一个技能Agent 反而要在两个技能之间来回切换。太大了比如“做数据分析”一个技能里塞了读 CSV、画图表、算回归、出报告四件事模型加载起来负担重而且容易出现“前面步骤遵守了后面步骤忘了”的情况。 我的设计原则是一个 Skill 只围绕一个可衡量的产出展开。比如“生成周报”是一个合理粒度因为它的产出是一篇固定的报告“分析数据”就不是因为“分析数据”没有明确的结束状态。 如果你发现一个任务有多个步骤不要急着拆成多个技能可以先尝试把它们写进同一个技能的正文里像操作手册一样分章节。只有当某一步被其他技能也复用时才把这一步独立出来。这个原则有点类似编程里的“函数提取”——别一开始就抽象等你发现重复了再干。 在多个技能并存时我会刻意让技能之间不重叠。比如我既有一个“英文润色”技能又有一个“学术论文改写”技能这俩表面上是不同的事但在 Agent 眼里边界非常模糊。我最终把它们合并成了一个“文本改写”技能然后通过参数区分学术场景和日常场景准确率反而提升了。 ### 2.3 工具与依赖给模型“必须在什么环境里跑”的说明 这是很容易被忽略的部分。很多 Skill 文档里只写了“运行脚本 xxx”却没说脚本依赖什么环境、需要什么密钥、或者为什么不能用其他工具跑。 如果 Agent 的运行环境里有多个工具模型有可能选错。比如我的 Agent 里既有 run_shell 又有 run_python3如果我在技能里不指定“必须用 python3”模型可能会用 bash 去执行一个 Python 脚本然后直接报错。 所以我在编写元数据时会写清楚 yaml allowed-tools: - python3并且在正文里也强调一遍注意请使用python3命令运行脚本不要使用 bash 或 node。脚本需要 Python 3.9 及以上版本。API 密钥从当前环境变量中读取不要让用户提供。为什么写两遍因为元数据是给模型预筛选用的正文是给模型执行时看的。两者都写可以降低它在关键时刻犯错的概率。另外如果技能里要读取某个文件我会在正文里写明这个文件的路径是相对目录还是绝对目录。很多人喜欢写scripts/xxx.py但没说明这个路径是相对于技能目录还是相对于 Agent 的工作目录。一旦工作目录变了脚本就会找不到文件。我个人的做法是所有脚本路径都写成相对于 SKILL.md 所在目录然后在正文里直接注明“路径相对于技能目录”。2.4 用“启发式”而不是“死规则”在设计技能的执行指令时最容易犯的错误是把规则写得太死。比如有人写“每搜索一次必须抓取 10 条结果”“每篇输出必须超过 500 字”这些数字看起来很精确但模型执行时往往顾此失彼。我更喜欢用一种给模型“判断空间”的写法。以写作质检技能为例我不会写“你必须找出 100 个错误”而是写按重要性排序检查内容优先处理事实错误和逻辑矛盾其次是错别字和语法问题最后才是措辞风格。如果没有发现逻辑矛盾不要为了凑数而强行指出问题。这种写法的好处是模型不会机械地在每个句子里抠不存在的毛病。Skill 的指令本质上是约束但约束不该成为负担它应该引导模型做出合理判断而不是让它变成一个只会数数的机器。另一个常用技巧是给每个步骤加上“结束条件”。比如步骤 1检查输入参数。若缺少参数直接让用户补充不要猜。步骤 2运行脚本获取结果。若脚本返回错误根据错误提示修正后重试一次。步骤 3如果重试仍然失败给出临时降级方案例如用缓存数据并在输出中注明。这些“结束条件”相当于异常处理模型遇到问题知道该停在哪个点而不是一直循环尝试或者直接把错误抛给用户。3. 实操过程把一个 Skill 从零跑通3.1 先写脚本验证逻辑我不建议一开始就把 Skill 接入 Agent这样出了问题不好定位。我的做法是先在一个独立的目录里做一次脚本级验证。以我最近做的一个“网页标题批量抓取”技能为例这个技能的核心是输入一个 URL输出网页标题。听起来很简单但真正跑起来会碰到很多细节。我先写了一个 Python 脚本# fetch_title.py import sys import requests from bs4 import BeautifulSoup url sys.argv[1] resp requests.get(url, timeout10) soup BeautifulSoup(resp.text, html.parser) title soup.title.string.strip() print(title)在命令行里手动跑了几次发现普通页面没问题但有些页面返回 403还有几个页面编码不对。于是我在脚本里加了 User-Agent 和编码处理import sys import requests from bs4 import BeautifulSoup url sys.argv[1] headers {User-Agent: Mozilla/5.0 (compatible; MyAgent/1.0)} resp requests.get(url, timeout10, headersheaders) resp.encoding utf-8 soup BeautifulSoup(resp.text, html.parser) title soup.title.string.strip() if soup.title else 无标题 print(title)这个过程最重要的收获是验证了输入输出都是稳定的。脚本写好后我把sys.argv的读取方式固定下来这样在 Skill 里被调用时不容易出问题。3.2 配置 SKILL.md 文件并接入运行流程脚本稳定之后我再建立技能目录.agent/skills/ fetch_title/ SKILL.md scripts/ fetch_title.py然后写了这样一份SKILL.md--- name: fetch_title description: 当用户需要获取某个网页的标题或想确认某个链接对应的页面名称时使用。当用户只是转发链接但没有提出具体问题时不使用。 allowed-tools: - python3 --- # Fetch Webpage Title 获取网页标题。在调用脚本之前先确认用户提供的 URL 格式是否完整必须包含 http 或 https。 ## 执行流程 1. 提取 URL 参数如果缺失则询问用户补充。 2. 运行脚本 bash python3 scripts/fetch_title.py 完整URL将脚本输出作为最终标题返回给用户。注意事项路径相对于技能目录。脚本返回“无标题”时说明页面是单页应用或动态渲染这时候不要强行猜测标题。接入 Agent 后我先用一句“帮我看看这个链接叫什么”来测试。结果第一次跑就发现一个问题模型没有传 URL而是直接把整句话当作参数塞给了脚本导致脚本报错。 原因在于我的一号指令写得太隐晦。模型不知道自己该从对话中提取哪部分作为 URL。后来我把指令改成 从用户的完整消息中提取 URL 参数。URL 一定是以 http/https 开头的字符串。不要包含其他文字。 这里的关键是“不要包含其他文字”。模型默认情况下会把整个输入当作参数除非我们明确禁止。 ### 3.3 用真实效果对比来迭代 光说“跑通了”不算数我习惯做一次对比实验。 在关闭技能的情况下我连续问了 Agent 五个不同的网址让它输出标题。结果它靠自己的训练记忆瞎猜五个里有三个是错的。而且每次回答的格式都不一样有的带着引号有的没有。开启技能之后五个全部抓取正确输出格式统一。 更有意思的是关闭技能时 Agent 还会自作聪明地把网页内容概括一下再输出“标题”导致结果变得非常不可靠。而开启技能后它只做我指定的事反而更可控。 如果想要更客观地评价可以给同一个 Agent 跑同一批测试用例把回答和真实值做对比算准确率。我在迭代过程中就是用一个简单的 test_cases.json 文件来记录输入和期望输出每次改完技能就跑一遍回归。 json [ {input: https://example.com, expected: Example Domain}, {input: https://httpbin.org/html, expected: Herman Melville - Moby-Dick} ]这种测试文件平时没什么用处等技能数量多了之后尤其重要。因为你不确定改动一个通用依赖会不会影响其他技能。4. 常见问题与排查技巧实录4.1 技能完全没被调用这是最常见的问题。你发现 Agent 回答得稀烂而且一次技能都没触发过。排查思路有两种一是看 Agent 运行日志里有没有检测到候选技能二是直接测试描述语句。如果日志里根本没有这个技能说明技能目录没被正确读取。我之前犯过一个很低级的错误把技能目录放在了项目根目录下但 Agent 默认只读.agent/skills子目录结果它自然找不到。如果日志里检测到了技能但模型没用它那就是description写得不够贴合用户意图。这时候我会把用户可能问的话都列出来和description做一遍语义对比。比如用户说“网上的新闻怎么说”如果我的description里只有“搜索信息”模型可能不会关联起来而改成“根据最新事实搜索”之后触发率明显上升。用户表达技能描述倾向是否容易触发“帮我查一下”包含“查”字动机匹配高“这东西值得买吗”描述是“搜索信息”没有价值判断语义低“现在几点”描述是“获取时间”高“最近股价怎样”描述是“财经数据获取”高4.2 技能被调用但执行失败技能被触发只是成功了一半接下来还会遇到执行失败的问题。排查时先看返回的错误里有没有脚本日志。如果完全没有日志多半是权限或超时问题。另一个容易忽略的点是路径。脚本执行时的工作目录不一定等于技能目录所以我在正文里强制要求“使用相对技能目录的路径”。如果脚本还是找不到文件可以选择在脚本开头添加import os os.chdir(os.path.dirname(os.path.abspath(__file__)))这句话可以保证脚本切换到自身所在目录之后再读取相对路径就稳了。4.3 多个技能同时能匹配怎么选当你的技能数量超过十个以后一定会遇到“一个任务有两个技能都能匹配”的情况。比如我既有“摘要生成”技能又有“会议纪要点提取”技能这两个都包含“总结”这个关键词。解决方式有三种在description里增加排除条件比如“当内容是会议录音时不要使用摘要生成技能”。给技能加一个priority字段让有明确指向的技能优先。直接把两个技能合并。如果它们的产出格式和步骤差不多合并之后更干净。我最推荐第三种。技能一旦出现大量语义重叠维护成本会急剧上升。你真的很难保证一次对话里模型会不会突然选错。宁可让一个技能变胖一点也比两个技能天天打架好。4.4 技能上下文太大影响速度有些技能为了让模型表现好写了一大堆指令结果每次触发都要读几百行内容速度明显变慢。而且 Agent 的上下文窗口是有限的技能内容占比越高留给真正对话的空间就越少。我自己常用的手法是“懒加载”。SKILL.md里只保留必要的执行步骤剩下的参考资料、FAQ、模板都放在README.md或docs/子目录里并且注明“除非用户要求否则不需要读取这些文件”。这样模型在大多数情况下只会加载几十行指令只有遇到特殊情况才去翻文档。用上面的“网页标题抓取”技能举例加载内容只有 2KB 左右非常轻。如果是那种包含大量示例的大型技能我会把示例移到一个示例文件里技能正文只写“处理格式不熟悉时参考 examples.md”。模型需要时会自己读不需要时就不会浪费 token。最后再分享一个个人经验我在建技能库时最初喜欢让每个技能都“看起来厉害”后来发现真正好用的往往是最朴素的那几个。Skill 的存在意义不是让 Agent 更聪明而是让 Agent 更稳定。你与其堆二十个花哨的技能不如先把十个常用任务做到脚本级验证。还有一点给每个技能加一个版本号我吃过一次亏——改了某个技能之后忘记哪台机器生效了结果出现“同问不同答”的情况。版本号写进文件名里心里会踏实很多。
skills 这个词在 AI Agent 开发里最近被频繁提起。很多人第一反应是“技能”其实在 Agent 的世界里Skills 指的是一套可以被模型按需加载的指令、流程、脚本和参考资料的集合。它不是简单地把 Prompt 写长一点而是让 Agent 在高价值、重复性任务上保持稳定的水准。这篇文章我会从一个实际项目的角度聊聊技能文件的组织方式、触发逻辑、踩过的坑以及最后怎么把它真正跑起来。如果你正在做 Agent、自动化工作流或者研究提示工程这篇应该能帮你避开不少新手才会遇到的坑。1. 先说清楚Agent Skills 到底是个什么东西1.1 为什么我不说它是“超级 Prompt”我发现很多人第一次听说 Skills 时以为这就是“把提示词写得更好一点”。这个理解不能说全错但会错过关键的地方。传统 Prompt 最大的问题在于所有信息都塞进上下文里模型每次都要“大海捞针”。你今天告诉它“搜资料时要用 GET 请求”明天它可能就忘了因为它要处理的信息太多了。而且 Prompt 越长模型越容易在无关信息上分心。我更愿意把 Skill 理解成“给 Agent 装了一个可检索的工具箱”。举个生活化的类比团队来了一个新实习生你给他一张 A4 纸写上“遇到问题先查手册”他大概率还是会手足无措。但你如果给他一套“问题处理流程卡”——第一张卡说“先判断错误类型”第二张卡说“如果是网络错误就重试三次”第三张卡说“如果是权限错误就找到负责人”——他就能按图索骥。这套卡片其实就是 Skill 的结构。Skill 并不是一段孤零零的提示词它是一个独立模块通常包含说明文档、配套脚本、参数定义和触发条件。模型在收到一个任务时会先判断这个任务适合走哪张“流程卡”然后把卡片内容读到上下文里执行。这样既能控制上下文长度又能让每一步操作有章可循。1.2 Skills 和普通 Prompt 的最大区别如果要我用一张表总结大概是这样的维度普通 PromptSkills加载方式每次全量注入按需匹配后注入结构纯文本靠约定维持结构化文件 脚本 元数据复用性复制粘贴到别处放在目录里随处可用唯一性容易出现同名概念冲突通过名称和内容进行隔离可维护性改动后难以追溯有版本、有目录、有测试用例关键区别在于“按需加载”。举个例子我现在做一个本地 Agent它既要能查天气又要能算股票收益率还要能改代码格式。如果这三个能力全塞进一个巨型 Prompt每次对话都会消耗大量 token而且模型可能会把“查天气”的规则误用到“改代码”上。而用 Skills 拆开后模型遇到天气问题就只加载天气技能遇到代码问题就只加载代码技能互不干扰。还有一点很重要某些 Agent 框架支持在技能里声明“这个技能需要哪些工具权限”比如某个技能要执行 shell 命令另一个技能只读文件。这相当于给 Agent 加了一层权限边界而不是把所有能力都混在一起。1.3 一个最简单的 Skill 长什么样很多成熟的 Agent 产品里Skill 以目录 文件的形式存在。我以前端常用的某个 Agent 为例它会读取.agent/skills目录下的每个子目录每个子目录就是一个 Skill。一个最简单的 Skill 长这样.agent/skills/ weather_check/ SKILL.md scripts/ get_weather.pySKILL.md是这个技能的核心前端部分包含元信息后面是正文指令。比如下面这段就是从实际项目里简化来的--- name: weather_check description: 当用户询问某地当前天气或未来天气预报时使用此技能。不要在其他场景调用。 allowed-tools: - python3 --- # Weather Check 根据用户提供的城市名运行以下脚本获取天气信息 bash python3 scripts/get_weather.py --city 城市名输出格式城市名称当前温度天气状况建议是否需要带伞等配套的脚本 get_weather.py 负责真正的数据请求。这个例子看着简单但它已经体现了 Skills 最重要的四个部分触发描述、工具权限、执行指令、输出约定。后面我会一个个拆开讲。 当然你也可以把纯文本提示词做成 Skill。比如“翻译语气优化”这种不需要跑脚本的技能只要在 SKILL.md 里告诉模型该怎么改写译文就行。灵活度很大关键是结构清晰。 --- ## 2. 一个好 Skill 的设计拆解让模型“会看、会挑、会用” ### 2.1 描述写得不好技能等于白写 很多新手刚开始写 Skill 时在 description 里只有一句话“这个技能用于搜索”。结果就是 Agent 根本不知道什么时候该用它甚至从来不会调用。 一个真正能用的描述要回答三个问题什么时候用、什么时候不用、用了之后会改变什么。我给你对比一下 - 糟糕的描述description: 搜索信息 - 能用的描述description: 当用户需要查找最新新闻、验证某个事实或获取实时数据时使用。在回答常识性问题时不要使用。 第二种描述之所以有效是因为它同时给了正面信号和负面信号。模型在意图识别阶段只需要做“这个任务像不像这个描述”的判断我们描述得越具体它的判断就越准。 我在实际项目里还会习惯性加一句“如果用户只是让我解释概念不要使用”。这句话看似多余却能大幅降低误触发率。这是真实踩坑之后总结出来的我最初没写这条限制时Agent 在回答“什么是 JSON”这种问题时居然也会去调用搜索技能白白浪费了好几秒时间。 ### 2.2 粒度怎么控制 Skills 的粒度是个很微妙的话题。太小了比如“读取文件”和“写入文件”各做一个技能Agent 反而要在两个技能之间来回切换。太大了比如“做数据分析”一个技能里塞了读 CSV、画图表、算回归、出报告四件事模型加载起来负担重而且容易出现“前面步骤遵守了后面步骤忘了”的情况。 我的设计原则是一个 Skill 只围绕一个可衡量的产出展开。比如“生成周报”是一个合理粒度因为它的产出是一篇固定的报告“分析数据”就不是因为“分析数据”没有明确的结束状态。 如果你发现一个任务有多个步骤不要急着拆成多个技能可以先尝试把它们写进同一个技能的正文里像操作手册一样分章节。只有当某一步被其他技能也复用时才把这一步独立出来。这个原则有点类似编程里的“函数提取”——别一开始就抽象等你发现重复了再干。 在多个技能并存时我会刻意让技能之间不重叠。比如我既有一个“英文润色”技能又有一个“学术论文改写”技能这俩表面上是不同的事但在 Agent 眼里边界非常模糊。我最终把它们合并成了一个“文本改写”技能然后通过参数区分学术场景和日常场景准确率反而提升了。 ### 2.3 工具与依赖给模型“必须在什么环境里跑”的说明 这是很容易被忽略的部分。很多 Skill 文档里只写了“运行脚本 xxx”却没说脚本依赖什么环境、需要什么密钥、或者为什么不能用其他工具跑。 如果 Agent 的运行环境里有多个工具模型有可能选错。比如我的 Agent 里既有 run_shell 又有 run_python3如果我在技能里不指定“必须用 python3”模型可能会用 bash 去执行一个 Python 脚本然后直接报错。 所以我在编写元数据时会写清楚 yaml allowed-tools: - python3并且在正文里也强调一遍注意请使用python3命令运行脚本不要使用 bash 或 node。脚本需要 Python 3.9 及以上版本。API 密钥从当前环境变量中读取不要让用户提供。为什么写两遍因为元数据是给模型预筛选用的正文是给模型执行时看的。两者都写可以降低它在关键时刻犯错的概率。另外如果技能里要读取某个文件我会在正文里写明这个文件的路径是相对目录还是绝对目录。很多人喜欢写scripts/xxx.py但没说明这个路径是相对于技能目录还是相对于 Agent 的工作目录。一旦工作目录变了脚本就会找不到文件。我个人的做法是所有脚本路径都写成相对于 SKILL.md 所在目录然后在正文里直接注明“路径相对于技能目录”。2.4 用“启发式”而不是“死规则”在设计技能的执行指令时最容易犯的错误是把规则写得太死。比如有人写“每搜索一次必须抓取 10 条结果”“每篇输出必须超过 500 字”这些数字看起来很精确但模型执行时往往顾此失彼。我更喜欢用一种给模型“判断空间”的写法。以写作质检技能为例我不会写“你必须找出 100 个错误”而是写按重要性排序检查内容优先处理事实错误和逻辑矛盾其次是错别字和语法问题最后才是措辞风格。如果没有发现逻辑矛盾不要为了凑数而强行指出问题。这种写法的好处是模型不会机械地在每个句子里抠不存在的毛病。Skill 的指令本质上是约束但约束不该成为负担它应该引导模型做出合理判断而不是让它变成一个只会数数的机器。另一个常用技巧是给每个步骤加上“结束条件”。比如步骤 1检查输入参数。若缺少参数直接让用户补充不要猜。步骤 2运行脚本获取结果。若脚本返回错误根据错误提示修正后重试一次。步骤 3如果重试仍然失败给出临时降级方案例如用缓存数据并在输出中注明。这些“结束条件”相当于异常处理模型遇到问题知道该停在哪个点而不是一直循环尝试或者直接把错误抛给用户。3. 实操过程把一个 Skill 从零跑通3.1 先写脚本验证逻辑我不建议一开始就把 Skill 接入 Agent这样出了问题不好定位。我的做法是先在一个独立的目录里做一次脚本级验证。以我最近做的一个“网页标题批量抓取”技能为例这个技能的核心是输入一个 URL输出网页标题。听起来很简单但真正跑起来会碰到很多细节。我先写了一个 Python 脚本# fetch_title.py import sys import requests from bs4 import BeautifulSoup url sys.argv[1] resp requests.get(url, timeout10) soup BeautifulSoup(resp.text, html.parser) title soup.title.string.strip() print(title)在命令行里手动跑了几次发现普通页面没问题但有些页面返回 403还有几个页面编码不对。于是我在脚本里加了 User-Agent 和编码处理import sys import requests from bs4 import BeautifulSoup url sys.argv[1] headers {User-Agent: Mozilla/5.0 (compatible; MyAgent/1.0)} resp requests.get(url, timeout10, headersheaders) resp.encoding utf-8 soup BeautifulSoup(resp.text, html.parser) title soup.title.string.strip() if soup.title else 无标题 print(title)这个过程最重要的收获是验证了输入输出都是稳定的。脚本写好后我把sys.argv的读取方式固定下来这样在 Skill 里被调用时不容易出问题。3.2 配置 SKILL.md 文件并接入运行流程脚本稳定之后我再建立技能目录.agent/skills/ fetch_title/ SKILL.md scripts/ fetch_title.py然后写了这样一份SKILL.md--- name: fetch_title description: 当用户需要获取某个网页的标题或想确认某个链接对应的页面名称时使用。当用户只是转发链接但没有提出具体问题时不使用。 allowed-tools: - python3 --- # Fetch Webpage Title 获取网页标题。在调用脚本之前先确认用户提供的 URL 格式是否完整必须包含 http 或 https。 ## 执行流程 1. 提取 URL 参数如果缺失则询问用户补充。 2. 运行脚本 bash python3 scripts/fetch_title.py 完整URL将脚本输出作为最终标题返回给用户。注意事项路径相对于技能目录。脚本返回“无标题”时说明页面是单页应用或动态渲染这时候不要强行猜测标题。接入 Agent 后我先用一句“帮我看看这个链接叫什么”来测试。结果第一次跑就发现一个问题模型没有传 URL而是直接把整句话当作参数塞给了脚本导致脚本报错。 原因在于我的一号指令写得太隐晦。模型不知道自己该从对话中提取哪部分作为 URL。后来我把指令改成 从用户的完整消息中提取 URL 参数。URL 一定是以 http/https 开头的字符串。不要包含其他文字。 这里的关键是“不要包含其他文字”。模型默认情况下会把整个输入当作参数除非我们明确禁止。 ### 3.3 用真实效果对比来迭代 光说“跑通了”不算数我习惯做一次对比实验。 在关闭技能的情况下我连续问了 Agent 五个不同的网址让它输出标题。结果它靠自己的训练记忆瞎猜五个里有三个是错的。而且每次回答的格式都不一样有的带着引号有的没有。开启技能之后五个全部抓取正确输出格式统一。 更有意思的是关闭技能时 Agent 还会自作聪明地把网页内容概括一下再输出“标题”导致结果变得非常不可靠。而开启技能后它只做我指定的事反而更可控。 如果想要更客观地评价可以给同一个 Agent 跑同一批测试用例把回答和真实值做对比算准确率。我在迭代过程中就是用一个简单的 test_cases.json 文件来记录输入和期望输出每次改完技能就跑一遍回归。 json [ {input: https://example.com, expected: Example Domain}, {input: https://httpbin.org/html, expected: Herman Melville - Moby-Dick} ]这种测试文件平时没什么用处等技能数量多了之后尤其重要。因为你不确定改动一个通用依赖会不会影响其他技能。4. 常见问题与排查技巧实录4.1 技能完全没被调用这是最常见的问题。你发现 Agent 回答得稀烂而且一次技能都没触发过。排查思路有两种一是看 Agent 运行日志里有没有检测到候选技能二是直接测试描述语句。如果日志里根本没有这个技能说明技能目录没被正确读取。我之前犯过一个很低级的错误把技能目录放在了项目根目录下但 Agent 默认只读.agent/skills子目录结果它自然找不到。如果日志里检测到了技能但模型没用它那就是description写得不够贴合用户意图。这时候我会把用户可能问的话都列出来和description做一遍语义对比。比如用户说“网上的新闻怎么说”如果我的description里只有“搜索信息”模型可能不会关联起来而改成“根据最新事实搜索”之后触发率明显上升。用户表达技能描述倾向是否容易触发“帮我查一下”包含“查”字动机匹配高“这东西值得买吗”描述是“搜索信息”没有价值判断语义低“现在几点”描述是“获取时间”高“最近股价怎样”描述是“财经数据获取”高4.2 技能被调用但执行失败技能被触发只是成功了一半接下来还会遇到执行失败的问题。排查时先看返回的错误里有没有脚本日志。如果完全没有日志多半是权限或超时问题。另一个容易忽略的点是路径。脚本执行时的工作目录不一定等于技能目录所以我在正文里强制要求“使用相对技能目录的路径”。如果脚本还是找不到文件可以选择在脚本开头添加import os os.chdir(os.path.dirname(os.path.abspath(__file__)))这句话可以保证脚本切换到自身所在目录之后再读取相对路径就稳了。4.3 多个技能同时能匹配怎么选当你的技能数量超过十个以后一定会遇到“一个任务有两个技能都能匹配”的情况。比如我既有“摘要生成”技能又有“会议纪要点提取”技能这两个都包含“总结”这个关键词。解决方式有三种在description里增加排除条件比如“当内容是会议录音时不要使用摘要生成技能”。给技能加一个priority字段让有明确指向的技能优先。直接把两个技能合并。如果它们的产出格式和步骤差不多合并之后更干净。我最推荐第三种。技能一旦出现大量语义重叠维护成本会急剧上升。你真的很难保证一次对话里模型会不会突然选错。宁可让一个技能变胖一点也比两个技能天天打架好。4.4 技能上下文太大影响速度有些技能为了让模型表现好写了一大堆指令结果每次触发都要读几百行内容速度明显变慢。而且 Agent 的上下文窗口是有限的技能内容占比越高留给真正对话的空间就越少。我自己常用的手法是“懒加载”。SKILL.md里只保留必要的执行步骤剩下的参考资料、FAQ、模板都放在README.md或docs/子目录里并且注明“除非用户要求否则不需要读取这些文件”。这样模型在大多数情况下只会加载几十行指令只有遇到特殊情况才去翻文档。用上面的“网页标题抓取”技能举例加载内容只有 2KB 左右非常轻。如果是那种包含大量示例的大型技能我会把示例移到一个示例文件里技能正文只写“处理格式不熟悉时参考 examples.md”。模型需要时会自己读不需要时就不会浪费 token。最后再分享一个个人经验我在建技能库时最初喜欢让每个技能都“看起来厉害”后来发现真正好用的往往是最朴素的那几个。Skill 的存在意义不是让 Agent 更聪明而是让 Agent 更稳定。你与其堆二十个花哨的技能不如先把十个常用任务做到脚本级验证。还有一点给每个技能加一个版本号我吃过一次亏——改了某个技能之后忘记哪台机器生效了结果出现“同问不同答”的情况。版本号写进文件名里心里会踏实很多。
