前阵子在折腾公司的智能客服项目发现每次给聊天机器人加一个新能力都要从写提示词、调接口、测边界一路重来循环往复特别痛。后来我换了个思路把各种能力封装成统一的“技能包”让 Agent 自己去匹配和调用整个开发节奏一下子就顺了。这套东西如今在圈子里有个挺火的名字叫 agent-skills本质上就是个“技能库”的设计模式。今天把这几个月从零搭建、踩坑、重构的经验完整写出来给正在搞 Agent 落地的朋友做个参考。1. 先搞明白 agent-skills 到底在解决什么问题先说个背景。这两年大模型应用从“单轮对话玩具”走向“真干活的生产工具”最大的瓶颈不是模型聪明不聪明而是怎么让模型稳定地去调用工具、完成任务。今天你让它帮你查天气明天让它订机票后天又让它分析一份 PDF每加一种能力就得重新设计一套调用逻辑。混乱、难维护、换场景直接报废。agent-skills 的核心思路很简单干脆把所有能力都写成标准化的“技能”用统一的格式来声明用一套机制来管理让 Agent 像一个装了各种工具的工人接到任务就自己挑合适的家伙。1.1 它和普通工具调用的本质区别在哪传统的 function calling 是把每个函数单独注册给模型比如 get_weather、book_flight 各写各的模型在对话里自己决定调哪个。这套方案在小规模场景下够用但技能一多就糟心每个函数都要单独调优提示词函数之间的协作没法声明复用基本靠复制粘贴。agent-skills 则把“技能”当成一个自包含的模块。每个技能文件里不仅有代码实现还有给模型看的说明书、示例、参数定义甚至专门的语言提示。比如一个“生成图表”技能里面就包括了图表类型说明、数据格式要求、多语言环境下的调用示例。模型拿到这个技能包不仅知道有这个功能还知道什么时候该用、怎么调用最稳、参数怎么给最不容易出错。1.2 为什么圈内都在聊 SKILL.md聊到 agent-skills 就绕不开 SKILL.md。这是 Anthropic 在 2024 年下半年力推的开放标准把某个技能的所有描述都写进一个 Markdown 文件里放在项目目录中。文件本身是人类可读的说明文档但它的价值在于结构足够规整模型能直接消费而且和 Human 对齐一致。我在实践中越来越觉得这种设计是把 Agent 的“上下文”变成可复用资产的关键。过去我们把知识都堆在系统提示词里提示词越来越长模型越来越“迷糊”有了 SKILL.md 之后知识和调用逻辑沉淀在技能库中主提示词保持清爽模型更容易专注与稳定发挥。1.3 适合谁、不适合谁先泼一盆冷水如果你只是做个 Demo调两三个 API 玩建议别上 agent-skills直接 function calling 最省事。技能库的收益要在技能的“种类和数量”达到一定规模后才明显。我大致估算过一笔账当你的 Agent 未来可能要维护超过十几个能力并且这些能力会被多个不同项目复用的时候用技能库的维护成本优势立刻就能看出来。如果公司有成体系的 prompt 管理需求、多 Agent 协同场景、频繁增加和调整技能那 agent-skills 算是长期角度看比较划算的基建。2. 核心设计拆解技能包长什么样、怎么写才不翻车真正动手之前必须先把技能包的结构摸清楚。最开始我照着 Anthropic 官方技能仓库的模板写写完第一个技能后发现结构看起来简单但细节里全是坑。一个合格的技能包至少要包含三块核心内容给模型看的声明、给系统跑的实现、给开发者维护的说明。2.1 技能包的标准目录结构我目前的技能库目录设计如下管理十几个技能基本不混乱skills/ ├── generate-chart/ │ ├── SKILL.md │ ├── scripts/ │ │ ├── make_chart.py │ │ └── requirements.txt │ └── assets/ │ └── example.png ├── web-search/ │ ├── SKILL.md │ └── scripts/ │ └── search.py └── pdf-summarizer/ ├── SKILL.md └── scripts/ └── summarize.py每个子目录就是一个独立的技能。系统在启动时扫描这个根目录读取每个目录中的 SKILL.md把文件内容作为可用能力的描述全文注入给模型。代码和资源文件按需加载不到用时不占上下文。2.2 SKILL.md 的写作规范别小看这几百字SKILL.md 可以说是整个技能库的灵魂。它不像普通技术文档读者不止是人还有大模型。一份好的 SKILL.md 要同时满足人和机器的阅读理解需求。以下是我总结的关键字段和写法建议字段作用写作要点name技能标识简洁准确和目录名一致不要用歧义词description模型选择技能的依据写清楚触发场景、输入要求、输出格式最好包含正例和反例when_to_use使用时机明确哪些情况必须用、哪些情况不要用这能显著减少模型误调用examples给模型的示范写2到3个完整的人机对话示例从提问到调参到最终结果输出template提示词模板定义调用该技能时模型要按什么步骤思考和输出description 字段尤其重要模型就是靠它来匹配“当前任务”和“技能清单”的。写得太泛模型会乱调写得太窄模型该用时又想不起来。我的经验是复杂技能至少准备 3 个具体触发场景的描述并在 when_to_use 里明确“无关时一定要忽略”。2.3 每个技能都应该是一个“迷你项目”很多教程把一个技能简单理解成“一段脚本 一段说明”这远远不够。技能里的代码部分应该是可独立运行、可测试、可调试的小型程序。比如我做“generate-pdf 报告”技能时把 PDF 生成逻辑做成一个 Python 命令行工具支持命令行参数传入主题、样式和数据文件技能代码只是调用这个工具。这样模型通过自然语言生成命令参数就能成事不需要动态写代码。我强烈建议所有技能内的代码都优先设计成 CLI 工具形式少用需要注入模型动态拼接的代码片段稳定性会明显提升。3. 实操从零搭建一个可用的技能库理论聊完直接上实操。这一节我用一个“网页内容总结成结构化报告”的真实技能案例完整带大家从目录创建、脚本编写到联调测试走一遍拿走就能改。3.1 先搭好基础环境我用的技术栈是 Python 3.11 Claude API LangChain 做任务编排层。不同模型、不同框架影响不大核心逻辑是通用的。目录结构就两行命令mkdir -p skills/webpage-report/scripts touch skills/webpage-report/SKILL.md技能实现部分我选择了 Fire 来写 CLI 工具非常轻量参数解析自动生成。# skills/webpage-report/scripts/report.py import json import sys from urllib.parse import urlparse import fire import requests from bs4 import BeautifulSoup def fetch_text(url: str, max_chars: int 8000) - str: 抓取网页正文并清洗 resp requests.get(url, timeout15, headers{ User-Agent: Mozilla/5.0 (AgentSkills/1.0) }) resp.raise_for_status() soup BeautifulSoup(resp.text, html.parser) for tag in soup([script, style, nav, footer]): tag.decompose() text soup.get_text(separator\n, stripTrue) return text[:max_chars] def generate_report(url: str, output: str report.md, max_chars: int 8000): 生成结构化报告 content fetch_text(url, max_chars) report { url: url, domain: urlparse(url).netloc, content_preview: content, word_count: len(content), status: fetched } with open(output, w, encodingutf-8) as f: f.write(json.dumps(report, ensure_asciiFalse, indent2)) print(json.dumps(report, ensure_asciiFalse, indent2)) if __name__ __main__: fire.Fire(generate_report)脚本逻辑很直观抓正文、清洗标签、截断、落盘。但几个设计细节值得提一下这也是我踩过坑之后总结出来的User-Agent 一定要设置很多站点默认拒绝 Python 的 urllib 请求HTML 清洗顺序有讲究先删 script/style再取纯文本否则打印出来全是 JS 代码截断字符数要控制避免技能把超长网页全部塞给模型上下文直接爆掉3.2 写一份模型看得懂、人也看得懂的 SKILL.md现在写核心的 SKILL.md。这份文件直接影响模型能不能正确使用上面的脚本--- name: webpage-report description: 将任意公开网页的内容提炼成结构化报告。当用户给出一个网页地址并希望了解该页面的主题、关键信息或总结内容时使用本技能。不适用于本地文件分析、PDF分析或不涉及具体网址的通用问答。 --- # Webpage Report 将用户提供的公开网页地址抓取并提炼成结构化摘要报告。 ## 使用步骤 1. 提取用户问题中的 URL确认是一个 http/https 链接 2. 参考下述示例构造参数调用 scripts/report.py 3. 根据抓取的内容生成结构化摘要页面主题、核心内容、关键结论 ## 参数说明 | 参数 | 必填 | 说明 | |------|------|------| | url | 是 | 网页完整地址必须包含 http:// 或 https:// 前缀 | | max_chars | 否 | 抓取正文的最大字符数默认 8000 | ## 示例 用户问题帮我总结一下 https://example.com 这篇文章的主要内容 调用方式 python scripts/report.py --url https://example.com --max_chars 6000 最终输出结构Markdown ## 页面主题 一句话概括页面主题 ## 核心内容 3-5 个关键要点每个要点附带简短说明 ## 关键结论 2-3 条主要结论或要点 ## 补充信息 如页面中有特殊数据、表格、统计数据在此列出description 里我特意写了“不适用场景”这样做的好处是模型在遇到“帮我看看这个PDF”的时候就不会误调用网页技能。这一段“排除描述”价值很大实测能明显降低误调用率刚开始做技能库的朋友容易忽略。3.3 把技能库挂到 Agent 上注入策略很关键写完单个技能还不够要把整个技能库接入运行中的 Agent。代码层面核心就两步扫描技能目录、注入上下文。from pathlib import Path from typing import List def load_skills(skills_dir: str) - List[str]: 扫描所有技能目录并提取 SKILL.md 内容 skill_docs [] base Path(skills_dir) for skill_path in base.iterdir(): if not skill_path.is_dir(): continue md_file skill_path / SKILL.md if md_file.exists(): skill_docs.append(f# {skill_path.name}\n\n{md_file.read_text(encodingutf-8)}) return skill_docs skills_context \n\n---\n\n.join(load_skills(./skills)) system_prompt f 你是一个智能助手拥有以下技能库。请根据用户需求选择并调用合适的技能完成任务。 skills_available {skills_context} /skills_available 运行时会发现一个关键问题技能一多系统提示词疯狂膨胀十几个技能全塞进去可能一次请求就要多烧几千 token。这里必须引入“按需注入”机制我的方案是先用轻量级索引让模型判断该用哪些技能再通过工具调用把具体的 SKILL.md 内容加载进来。SKILL_INDEX 可用技能列表 - webpage-report: 网页内容结构化总结 - generate-chart: 图表生成 - web-search: 联网搜索 - pdf-summarizer: PDF文档总结 - csv-analyzer: CSV数据分析 根据用户问题选择最相关的1-3个技能输出技能名称的JSON数组。 def route_and_load(question: str, skills_dir: str): 通过索引完成粗粒度技能路由 # 这里实际调用模型判断 route_result 为技能名列表 route_result llm_call(SKILL_INDEX, question) active_skills load_specific_skills(skills_dir, route_result) return build_execution_prompt(active_skills)经过这样改造每轮对话模型只需要看“技能索引”和与当前任务真正相关的“技能详情”上下文占用和响应速度会有本质性改善。这也是我从“全量注入”到“按需加载”的一个很有价值的优化迭代。4. 常见问题与排查技巧实录这部分是纯实战经验。我用 agent-skills 模式后遇到了一些非常典型的问题单个拎出来都能写篇文章这里全部集中分享。这些问题有些是设计初就埋下的有些是技能数量到一定规模才暴露的但都是必坑。4.1 模型选错技能或者根本不调用技能这是最常遇到的头号问题。现象是模型面对用户的“帮我分析这份财报里的营收数据变化”却调用了一个“网页搜索”技能或者明明库里就有“数据可视化”技能模型偏偏自己生成了图表代码不用现成的。排查下来原因基本集中在 SKILL.md 的 description 写得有问题。我总结过一个“三查一改”的排查流程查 description 是否包含了核心触发词。分析类任务description 里必须出现“分析”“营收”“财报”“趋势”这些和任务强相关的关键词。模型是靠语义相似度来做匹配的你的描述里如果全是“生成”“搜索”“报告”这种宽泛词模型自然会乱。查技能之间是否存在 overlap。比如“网页总结”和“PDF总结”的技能如果 description 都有“把内容总结成报告”模型就很容易混淆。解决办法是把触发条件区分到“网址”和“文档文件”这两个层面并在排除描述里明确说“不是处理网址的”“不是处理 PDF 的”。查 when_to_use 是否写了反例。我早期写技能包的时候只在 description 里写正面触发条件效果总是波动。后来加上“无关时必须忽略”的 when_to_use 反例误调用率直线下降。模型真的非常吃这一套。最后一步就是改描述改完用真实的用户问题跑 20 组回归测试观测技能调用准确率。4.2 上下文爆炸问题技能库数量多起来后很容易出现“把所有技能说明全塞给模型”的偷懒写法。我试过在系统提示词里直接拼接了 15 个 SKILL.md马上遇到两个问题token 消耗飞涨模型注意力分散技能描述里的关键信息经常被忽略。热组的“按需加载”已经是标准答案了没有更优雅的方案就是上面说的两步走索引路由加延迟加载。另外还要注意 SKILL.md 本身的篇幅控制单份技能说明最好控制在 500 字以内不要把冗长的实现细节写进去模型给技能本身留出余量会更有效。4.3 技能内部 Python 依赖冲突与环境隔离当你有十几个技能时依赖治理问题根本躲不开。技能 A 要 requests 2.28技能 B 要 requests 2.31技能 C 还需要一堆第三方库全装进同一个 Python 环境迟早会出事。我的方案是把“通用库”和“专用依赖”分开管理。通用库如 requests、BeautifulSoup 直接装进环境里专用依赖则在该技能目录下放一个 requirements.txt用到时再现场装首选是通过管道命令安装到隔离的虚拟环境中。你也可以用 uv、conda 环境管理不必纠结工具。关键是不要让某个依赖版本问题把整个 Agent 服务拖垮。4.4 技能静默失败问题技能脚本可能在中间环节出错比如网页请求超时、PDF 加密、API 返回空。最恶心的状态是脚本吞掉异常返回一个看似正常的空结果模型基于这个空结果“一本正经地胡说八道”。我规定所有技能脚本都必须遵循“成功或报错没有中间态”的原则。正常结果输出 JSON 格式并附带 status: ok出错直接抛异常退出码非 0并输出能从错误信息描述中看明白的错误文本。这样 Agent 才知道“这个技能没搞定”而不是拿一个残缺输出硬编故事。5. 工程化落地从个人玩具到团队基建设施当你的技能库从两三个技能长到二十多个技能参与的同事也从一个人变成三四个人的小团队时仅靠“写个文件夹放那里、谁要谁复制”的方式根本没法维护。你必须把技能库当成一个正经的代码仓库来管理而且要比普通代码仓库更讲究版本控制和并发协作。5.1 技能库的目录组织要像“技术雷达”一样分阶段我现在的技能库分成三层管理skills/ ├── stable/ # 稳定技能通过联调测试可被多项目复用 ├── beta/ # 测试技能功能可用但边界还没摸透 └── deprecated/ # 废弃技能保留记录不加载到生产环境这种分层虽然简单但解决了一个关键问题Agent 加载时只加载 stable 目录避免 beta 技能的不稳定行为影响线上任务同时新技能可以安全地在 beta 中试错迭代不用一次开发就要求完美。从实际结果看这个机制很好地管理了技能质量让团队能愉快地并行开发。5.2 给每个技能加测试这里说的不是 Pytest 单测技能的最核心保证不只是代码能跑通而是模型能正确理解和调用它。我在每个技能目录下加了 tests 文件夹里面放了几组用户提问和期望调用结果的“回归用例”。每次改动技能代码或调整 SKILL.md 描述都会用这些用例跑一遍“模拟用户提问 查看 Agent 是否选中该技能并输出预期结果的调用”。回归测试通过技能才能往 stable 目录迁移这一套已经跑了两三个月很稳。如果你们用 GitHub Actions 或 GitLab CI把这套用例集成进流水线效果会更好。skills/generate-chart/ ├── SKILL.md ├── scripts/ │ ├── make_chart.py │ └── requirements.txt └── tests/ ├── case1_user_chart_request.txt ├── case1_expected_call.json ├── case2_aggregate_request.txt └── case2_expected_call.json测试用例文件里存的都是真实用户可能问的问题和期望的工具调用 JSON跑起来之后很快就能发现“改了个描述别的技能被带偏了”这类回归问题。5.3 多 Agent 场景下的技能分配策略如果你做的不是一个单体 Agent而是多个 Agent 协作的系统技能库的组织方式要再加一层“路由维度”。比如同一个技能库里有“客服 Agent”和“数据分析 Agent”它们的技能调用范围应该不同。我在技能设计中增加了“适用 Agent”字段加载时根据当前 Agent 身份过滤技能索引。这个方法虽然增加了一点点规划量但能避免客服 Agent 突然调用数据库查询技能这类安全事故发生。5.4 技能库的版本演进与兼容最后说版本。技能会随着需求变化不断调整一个技能改了参数说明可能会导致部分已经在用的 Agent 失效。我的经验是技能接口设计上不要一开始就写死参数数量更不要频繁改名。为了兼容旧版SKILL.md 里可以附加一个 version 字段并在 description 中说明“旧参数已废弃请使用新参数”。同时在技能目录中保留旧版本说明文件供故障时检索。如果你的技能库要嵌入到商业产品中这个版本兼容设计尤其不能省。6. 现在就可以开始的落地路径agent-skills 不是某种需要“学习全套理论”才能上手的重型框架它更像一套工程约定。全部做完你随时可以落地并且可以先从团队里最小的一个场景开始。6.1 第一步选一个高频且边界清晰的功能比如“网页抓取总结”“CSV 数据分析”“PDF 转文本”“舆情搜索”。边界清晰的意思是输入和输出都是明确的不依赖过多前置判断这能让首个技能包的理论价值快速被验证。6.2 第二步按照前面写的方法创建目录和 SKILL.md先不要追求技能数量一个技能先跑通全流程写脚本、写 SKILL.md、接入 Agent、用真实问题测。这一步最容易卡在 SKILL.md 描述上如果你第一次写出来调用不准别纠结按前面 4.1 的“三查一改”流程调两个小时内基本上能调到满意的状态。6.3 第三步跑通后再按需新增一个技能跑顺了你对整套模式就有了手感。再新增技能时你会开始主动思考“这个技能和新技能的边界怎么界定”“它们的触发场景会不会重叠”“技能之间怎么配合”。当你有五六个技能跑出来以后这套架构的价值就很明显了加一个新能力基本就变成了“写脚本 写描述 跑回归测试”三个动作半小时左右能完成再也不用从零开始调提示词和流程了。根据我个人做了一整轮这种基建的经验最花时间的不是代码实现也不是模型调参而是把每个技能的使用边界想清楚。一个技能的多份说明里最有价值的不是“能做什么”而是“什么情况下不要用”。把注意力放在这里你会看到 Agent 整体的稳定性和可控性都上一个台阶。后续如果有精力和场景我建议你进一步往“技能间协同”去扩展也就是让多个技能像流水线一样串联配合。那套玩法就是把单技能工具推向多技能工作流的下一步演进了。