做Agent开发这一年我发现自己经常掉进同一个循环接到一个新场景先写一段工具调用逻辑再调参数、试提示词好不容易跑顺了下一个需求过来之前的成果基本作废又得从头再来。后来我把重心从“怎么写提示词”挪到“怎么沉淀能力”上整理了一套叫 agent-skills 的技能库方案。它不是又一个Agent框架而是一套把Agent可复用能力拆成独立技能模块的方法论和脚手架。如果你正在做个人助理、自动化工作流、垂直场景机器人或者只是想让常用的大模型助手少犯重复错误这篇内容会适合你。我会把自己搭这套体系时踩过的坑、验证过的做法包括技能目录怎么设计、SKILL.md怎么写、运行时怎么接、效果怎么测全部摊开讲。1. agent-skills到底是做什么的先解决一个真问题1.1 从“一次性脚本”到“可复用技能”的转变很多人一开始接触Agent都是从“给模型加一个工具”开始的。比如让模型能查天气、能算个日期、能调某个接口。这种做法在Demo阶段很爽因为代码量少肉眼可见地能看到效果。但一旦场景变多麻烦就来了每个工具都是散落的函数Agent不知道该在什么时候用哪个你只能在系统提示词里把所有工具描述堆在一起新增一个能力还得重新处理调用逻辑。agent-skills的思路是把工具的粒度提高一层不叫“函数”叫“技能”。技能是自包含的有明确的职责边界、有结构化的输入输出、有完整的说明文档甚至有自己的测试用例。Agent拿到用户请求后不是执行提前写死的函数而是根据用户意图去“检索”最合适的技能再把技能执行结果带回来。相当于把Agent从“只会套餐的店员”变成“会看菜单点菜的顾客”。这个转变解决了一个核心问题能力不再和业务逻辑耦合在一起。技能库可以独立迭代Agent只要学会如何读技能描述就能自动适配新的技能。以后你新增一个能力不需要改Agent主程序只要往技能库里塞一个新模块然后告诉它“这个技能什么时候能用”。1.2 技能库带来的三个直接收益我自己实践下来把技能集中管理之后最明显的变化是三个。第一维护成本直线下降。以前修一个工具函数要担心会不会影响别的地方。现在每个技能单独放在一个目录里依赖、脚本、测试都跟着技能走改一个不会波及另一个。第二可测试性变强了。技能是标准的输入输出结构我可以为每个技能准备一组黄金样例离线就能验证“给这个输入能不能得到预期输出”。这比每次跑到真实对话里试错要快得多。第三扩展路径变得清晰。新来的能力只需要复制一个技能目录的模板填好描述和实现就能被Agent发现。哪怕由不同人维护不同的技能只要遵守同一套规范整个库依然是可管理的。这三个收益不是理论推演是我把之前零散的工具代码重构进 agent-skills 之后真实感受到的变化。尤其是“可测试”这一点后面我会专门展开。2. 核心设计技能描述与执行体分离2.1 一个技能目录长什么样在设计 agent-skills 时我定了一个硬性规范每个技能必须自包含在一个独立目录里。目录结构是这样的skills/ article_summarizer/ SKILL.md run.py requirements.txt tests/ test_cases.json run_tests.py format_converter/ SKILL.md run.py requirements.txt tests/ sensitive_word_check/ SKILL.md run.py requirements.txt tests/其中 SKILL.md 是技能的“身份证”run.py 是技能的“执行体”tests 目录是技能的“质检报告”。你可能会问为什么不直接把描述写在代码注释里非要单独一个 Markdown 文件因为Agent读取技能信息靠的是文本不是代码解析。SKILL.md 的作用是给模型看的它需要使用自然语言把“这个技能是干什么的、什么时候用、需要什么参数、会返回什么”讲清楚。run.py 则负责真正干活。两者分离之后你不会因为改实现细节而破坏模型对技能的理解也不会因为改描述而误碰代码。2.2 SKILL.md 怎么写一个可复用的模板我踩过很多次坑之后总结出 SKILL.md 的推荐结构。核心是 YAML frontmatter 加正文说明。--- name: article_summarizer version: 1.2.0 description: 当用户需要将一篇长文章或长文本压缩成摘要时使用。适合新闻、博客、技术文档。如果用户明确提到“总结一下”“提取要点”“写摘要”优先使用本技能。 input_schema: type: object properties: content: type: string description: 需要生成摘要的原文内容 max_length: type: integer description: 摘要最大字数默认200 required: - content --- # 文章摘要技能 本技能接收一段长文本输出结构化的中文摘要。输出内容包括核心结论、关键论据和行动建议。摘要必须保持客观不添加原文没有的信息。 ## 使用场景 - 用户上传或粘贴一篇长文要求快速了解内容 - 需要将技术文档转为简短的要点列表 - 对新闻稿件进行二次编辑前的预压缩 ## 注意事项 - 当原文为英文时输出摘要仍使用中文 - 如果内容少于100字直接返回原文不强行生成摘要 - max_length 只作为软限制实际输出可以上下浮动10%字段里面 name 是技能唯一标识version 是语义化版本号description 是给模型看的触发说明input_schema 是参数校验用的 JSON Schema。正文部分不是装饰很多模型在读取技能时会把整份 Markdown 都放进上下文正文里的“使用场景”和“注意事项”能显著提高选技能的正确率。2.3 为什么用“自然语言描述 JSON Schema”的组合一开始我也想过直接用函数定义不就行了吗后来发现不够。函数签名只能表达参数类型表达不了“什么时候该用我”。比如一个图片压缩技能函数签名可能是compress_image(input_path, output_path, quality)模型知道怎么传参但它不知道用户说“帮我压一下这张图”应该调用它而用户说“把这张图变小一点”可能也要调用它。这种意图匹配靠的是自然语言不是类型签名。所以我采用两层结构description 负责意图匹配input_schema 负责参数校验。模型先根据描述判断“是否用这个技能”再根据 JSON Schema 生成符合要求的参数。这样既保留了机器可校验的严格性又给了模型足够的语义空间。2.4 执行体的三种形态脚本、API、组合技能一个技能的 run.py 不一定要直接“干活”它可以做三种事情。第一种是本地脚本执行。例如文本转换、文件重命名、批量图片压缩这些任务跑在本地环境输入参数直接传给脚本输出写回文件或者打印结果。第二种是封装外部API。比如你要调用某个云服务商的语音识别接口可以在 run.py 里写请求逻辑对外暴露统一的输入输出。这样做的好处是以后换服务商只要改 run.py 内部实现SKILL.md 不用动Agent 也不用动。第三种是组合技能。技能 A 的输出可以作为技能 B 的输入比如先调用“文档解析”把 PDF 转成纯文本再调用“敏感词检查”扫描文本。组合逻辑可以写在一个编排型技能里让 Agent 不用关心中间细节。一开始不要急着做组合先把单一职责的技能做扎实。组合技能的调试复杂度是线性上涨的一旦中间某一步出问题排查成本会翻倍。3. 从零搭建技能库一步步可落地3.1 第一步盘点高频操作提取技能边界动手写第一个技能前我先列了一张表把最近两周Agent需要反复处理的操作全部写下来。这张表里可能包括文章摘要、格式转换、敏感词过滤、数据清洗、定时提醒。然后对每项操作问三个问题输入是什么输出是什么边界在哪里边界是最容易模糊的地方。比如“数据清洗”这个技能一开始我把它定义得太大里面既要去空行、又要去重、还要纠正错别字。结果Agent调用时经常只生效其中一部分因为描述不够具体。后来我把每个清洗动作拆成独立技能比如remove_duplicate_lines、trim_whitespace、fix_typos虽然技能数量多了但每个都用得准确。我的建议是拆分粒度以“一句话能说清楚”为准。如果描述需要写两段才能说明适用范围大概率边界还是太宽。3.2 第二步定义目录结构与命名规则目录结构我上面已经给了但命名规则值得单独说。技能名必须用小写字母和下划线不能出现空格和缩写。命名要体现动作和对象比如summarize_article、convert_markdown_to_html不要叫util、helper这种含义模糊的词。还有一点容易忽略技能目录名要和 SKILL.md 里的 name 保持一致。我遇到过目录叫article_summarizer里边的 name 写成summarize结果运行时加载器按目录名找技能模型却按 name 引用两边对不上折腾了半天。后来我加了一个校验脚本启动时检查所有技能的目录名、name、文件名三者是否一致一致才允许加载。3.3 第三步实现第一个技能并接入Agent运行时下面给一个最小可用的技能执行体。假设我们要实现article_summarizer的 run.py这里直接用大模型做摘要。# run.py import json import sys from typing import Any import requests def call_summary_api(content: str, max_length: int) - str: # 这里以通用大模型接口为例按你的环境替换 endpoint 和密钥 resp requests.post( https://your-llm-endpoint/v1/completions, json{prompt: f请用不超过{max_length}字总结下列内容\n{content}}, timeout30, ) resp.raise_for_status() return resp.json()[choices][0][text].strip() def run(input_data: dict) - dict: content input_data[content] max_length input_data.get(max_length, 200) summary call_summary_api(content, max_length) return {summary: summary, length: len(summary)} if __name__ __main__: payload json.loads(sys.stdin.read()) result run(payload) print(json.dumps(result, ensure_asciiFalse))这个技能接收标准 JSON 输入输出标准 JSON 结果。配合一个技能加载器就可以被 Agent 发现。# loader.py import json import importlib.util from pathlib import Path def load_skill(skill_dir: Path): skill_md_path skill_dir / SKILL.md run_path skill_dir / run.py # 读取 frontmatter简单用字符串截取 text skill_md_path.read_text(encodingutf-8) frontmatter text.split(---)[1] meta parse_frontmatter(frontmatter) # 简化实现 spec importlib.util.spec_from_file_location(run_path.stem, run_path) module importlib.util.module_from_spec(spec) spec.loader.exec_module(module) return {meta: meta, run: module.run}接入 Agent 时只需要把 SKILL.md 的描述部分交给模型做意图匹配匹配完成后调用run()并传参再把结果作为观测信息交给模型生成最终回复。3.4 第四步版本管理与灰度发布技能不是写完就固定不变的。我维护了一个轻量版本机制SKILL.md 里的 version 字段配合 Git 标签使用。每次修改描述、输入输出或者实现version 都按语义化规则递增。大版本变化意味着输入输出不兼容小版本变化只是修了描述或者内部实现。灰度发布的做法很朴素技能库里可以同时存在article_summarizer的 v1 和 v2SKILL.md 里的 description 加一句“新版本优先使用”让 Agent 先在低流量场景试跑确认没问题再切换默认版本。我一开始不做灰度直接覆盖上线结果某个技能在线上把一个长报告截断了影响了三天数据。后来老老实实加版本切换虽然麻烦但心里踏实。4. 测试、观测与调优让技能越用越准4.1 离线测试为每个技能建立黄金样例集技能能不能稳定工作不能靠聊天验证。我给自己定的规矩是每个技能在提交之前必须有至少十个黄金样例。这些样例覆盖典型场景、边界场景和反例。典型场景是正常请求边界场景是空输入、超长文本、缺失参数反例则是“这个请求明明不该调用本技能但描述容易误导模型”的情况。tests/test_cases.json 的格式我用的是[ { name: 正常中文文章摘要, input: { content: 这是一篇超过一千字的测试文章……, max_length: 200 }, expected_keywords: [核心结论, 关键论据], should_invoke: true }, { name: 空内容不触发, input: {content: }, should_invoke: false } ]离线测试分两层第一层验证技能执行逻辑用真实输入调用 run.py检查输出是否包含关键字段第二层验证意图匹配把用户原始语句输入匹配器看模型是否做出正确调用决策。第二层才是 agent-skills 的价值所在因为代码执行错误通常一眼就能看出而意图匹配错误会在对话中悄悄出现。跑测试我会直接用 pytest 包装把每一条 sample 变成测试用例。刚开始跑测试经常一片红大部分原因是 SKILL.md 描述写得不够精确而不是 run.py 本身错误。这其实是个好信号说明测试真的能发现问题。4.2 在线观测记录每一次调用才能找到失灵原因离线测试覆盖不了所有真实场景线上日志必须保留。我给每次技能调用增加了一条结构化记录字段包括用户原始请求、匹配到的技能、匹配置信度、传参数据、执行返回、执行耗时、模型最终回复。有了这份日志很多诡异问题就能定位。比如某个技能调用率特别低查日志发现模型经常匹配到另一个相似技能或者本次请求明显应该用 A 技能模型却用了 B。如果没有日志你只能靠印象去猜效率极低。我还会对日志做最简单的统计每个技能的调用次数、成功率、平均耗时。调用次数为零的技能要重点关注要么描述有问题要么需求根本不存在。成功率低于80%的技能优先检查参数校验和执行体异常处理。4.3 描述调优一场持续的成本最低的优化在 agent-skills 里优化技能效果最高杠杆的手段是改描述而不是改代码。我的经验是描述需要反复打磨三点。第一触发词要具体。不要只写“用户要求摘要”要写“总结一下”“提取重点”“说人话”“太长不想看”等常见的用户表达。第二反例要写清楚。如果某个技能容易被误调用要在“注意事项”里明确写出“当用户只是询问格式不要使用本技能”。第三参数解释要给足。模型生成参数时如果看不明白字段含义很容易瞎填。有一次我接手一个convert_timezone技能description 只写了“时区转换”。结果用户说“帮我看看纽约现在几点”时模型确实调用了技能却把“纽约”转成了字符串而不是时区标识。后来我在参数描述里补了一句“推荐用 IANA 时区标识例如 America/New_York”误用问题立刻少了。调优时我还发现替换描述后需要重新跑一遍黄金样例集防止修好一个问题又带出新问题。描述微调看似简单但一次只改一个技能不要批量改完再测不然分不清哪个改动影响了效果。5. 高频踩坑与排查技巧实录5.1 技能明明存在Agent却不调用这是最常遇到的问题也是第一个让我失眠的问题。技能目录、描述、代码都没问题但Agent在真实对话里就是不用它。排查顺序我一般这么走先看日志里匹配阶段的得分如果得分很低说明描述和用户语言距离太远需要补充更多触发场景如果得分不低但Agent仍然没调用说明上下文里其他指令冲淡了技能存在感可以在系统提示词里加一句固定格式的技能清单如果还不是就要检查技能是否被加载器成功注册有时技能目录名带了一个空格加载时被静默跳过。还有一个隐蔽原因技能名和用户表达里的词冲突。比如有个技能叫summarize_code用来解释代码。用户说“帮我总结一下这段代码”模型可能因为看到了“总结”而选了一般的文本摘要技能。这种情况要在技能清单里显式指出差异给模型一个区分依据。5.2 参数传错、格式不对的快速定位参数问题大多不是模型“笨”而是技能描述没给足信息。比如 JSON Schema 里定义了max_length是整数但没说单位模型把 200 当成“字”还是“字符”全靠猜。我都会在字段 description 里标注期望格式和默认值比如“整数单位字默认200”。如果参数结构复杂技能说明正文里最好放一个“参数示例”。模型看到完整的 JSON 示例生成的参数会更规范。这个方法比在Schema里堆约束条件更管用。验证参数时我建议 run.py 里别只做类型断言要做业务校验。比如content字段如果是空字符串直接返回错误而不是把空文本送进摘要模型否则会得到一堆莫名奇妙的输出。5.3 技能冲突相似度过高怎么办技能库大了之后两个技能描述相似是必然的。比如format_date和convert_timezone一个处理日期显示格式一个处理时区换算用户一句“把日期改成中国格式”可能同时命中两个。解决冲突我常用的办法是“描述区割”给每个技能明确划分领地。将format_date描述限定为“仅修改显示格式不改变时间值”将convert_timezone描述限定为“改变时间值对应的时间区域”。然后在正文里互写一句“如果用户只是改格式请调用 format_date而不是本技能”。如果两个技能实在分不开可能说明它们应该合并成一个技能内部根据参数再分流。判断标准就是用户的一句话是否经常需要同时触发它们。为了更直观我把常见问题整理成了速查表。现象可能原因排查动作模型始终不调用技能描述触发词不足补充用户常用表达增加“使用场景”调用后参数明显错误字段含义不清晰在 JSON Schema 描述中补充格式、单位、示例多个技能被同时选中技能边界重叠明确分区描述必要时合并技能技能执行报错但日志无记录加载器未捕获异常在加载器外层增加异常捕获与日志写入改了描述后效果变差描述过度泛化恢复到上一版本缩小改动范围再测试5.4 技能库维护的两个“土办法”最后分享两个不复杂但很管用的维护习惯。第一个是“技能体检日”。我每周抽一个固定时间跑一遍所有技能测试再拉一份线上调用日志找出调用率为零和成功率偏低的技能。该修描述修描述该下架下架。技能库不是越大越好堆了一堆没人用的技能只会增加匹配噪音。第二个是“变更牵动测试”。任何技能的 SKILL.md 变更都必须跑一次它自己的测试集同时跑一次相邻技能的测试集防止“修 A 坏 B”。我吃过一次亏给“文章摘要”增加了一句话“适合技术文档”结果一个“技术问答”技能被影响模型开始用摘要技能回答问题。从那以后相邻测试就成标配了。最后再分享一点我的切身体会搭建 agent-skills 这个项目的过程其实也是我对Agent开发认知升级的过程。以前我总想着怎么让模型变得更聪明后来发现把能力边界理清、把技能描述写准、把测试做扎实模型的表现会稳定得多。聪明不是堆出来的是规则、结构和反馈一起支撑出来的。如果你刚开始做自己的技能库不用担心一次设计得完美。先挑三个最常用的技能按我上面的流程跑通再慢慢扩展。踩过几次坑之后你会对这种“技能优先”的开发方式上瘾的——因为每新增一个技能都是给未来的自己省时间。