1. agent-skills解决的不是能不能而是贵不贵如果你搞过一阵子Agent开发大概率遇到过这么一种情况想让模型完成某个具体动作比如从一篇文章里抽出正文、去掉导航和广告、再概括成三句话。硬靠提示词去堆也能跑通但代价是提示词越来越长、越来越脆弱换一个网站就崩改一个需求就要重新调一版prompt。我第一次接触到agent-skills这个项目时正好被这类问题折腾得够呛。回头看这个项目的核心思路其实很简单不要把所有能力都揉进提示词里而是把能力拆成一个个可以独立加载的技能包让Agent在需要的时候才去装载对应的技能。1.1 所有的工具类Agent最终都会遇到同一个瓶颈先说一个反直觉的观察。很多人以为Agent的能力上限由模型决定模型强就万事大吉。但实际跑过才发现真正卡住项目的往往是上下文窗口和指令冲突。举个例子。假设你要做一个能处理各种文档的助手早期做法很直接把如何解析PDF如何提取表格如何识别图片中的文字这些说明全部塞进system prompt。结果每个任务开始之前模型都要先读完这几千字的说明书再开始干活。这里有两个问题。第一个是费用和延迟每轮对话都在为那些用不到的说明文字付费第二个更麻烦指令越多模型越容易产生注意力漂移。技能说明和用户需求混在一起模型偶尔会分不清哪条指令才是当前的最高优先级的那个输出质量波动很大。agent-skills的解法是换个角度模型不需要在每轮对话中都具备所有能力。它只需要知道我有哪些技能可用每个技能是干什么的等真正碰到对应任务时再把详细的技能说明和脚本注入进去。1.2 技能包和工具调用的区别在哪有人可能会说这不就是function calling吗其实不完全一样。工具调用function calling是一个很薄的接口层你给模型暴露一个函数名、参数列表模型决定什么时候调用、传什么参数具体逻辑在你的代码里执行。而agent-skills更像一个完整的操作手册加执行脚本的组合体。一个技能包除了提供可执行的脚本还带着一份给模型看的说明书。说明书里写清楚了这个技能适合处理什么任务、在什么场景下用它、有哪些边界限制、完成任务的步骤是什么。模型下载技能包之后不只是调一个函数而是理解了一套做事的方法然后用脚本去执行。这一点差别在复杂任务上非常明显。工具调用适合执行单个原子操作但技能包适合完成一整个需要多步判断的任务。1.3 它是给谁用的简单梳理一下适合用agent-skills的人群。如果你在用Claude、DeepSeek这类支持长上下文的模型做自动化任务目前主要靠提示词堆功能且已经堆到维护困难的程度。如果你维护着多个Agent希望不同任务之间共享一套能力而不是每个Agent都copy一份prompt。如果你做的是文档处理、信息抓取、数据分析这类目标明确但过程经常变的任务静态提示词很难覆盖各种情况。如果你只是做一次性的脚本不需要工程化那这个东西对你来说可能有点重。但如果你想给自己的Agent搭一套可持续维护的能力体系它提供了一个挺完整的范式。2. 一个技能包的真实内部结构拆解agent-skills里一个技能不是一段字符串而是一个目录。我拿自己复刻过的项目结构来说典型的技能包长这样my-skill/ ├── SKILL.md ├── scripts/ │ ├── run.py │ └── requirements.txt └── resources/ └── reference.pdf乍看很简单但每一层的设计都有讲究。搞懂这个结构你自己写技能包时就能少走很多弯路。2.1 SKILL.md写给模型看的操作手册SKILL.md是整个技能包的核心也是和普通工具函数最大的区别所在。它用的是Markdown格式开头有一段YAML frontmatter里面是元数据--- name: web-content-extractor description: 从网页URL中提取干净的正文内容移除导航栏、广告、评论等噪音元素返回纯文本或结构化HTML。适用于文章阅读、内容聚合、资料归档等需要正文的场景。 when_to_use: 当输入是一个网页链接且目标是获取该页面的主体内容时使用。不适合需要登录、动态渲染极重的单页应用页面。 ---description和when_to_use这两个字段非常关键。它们就是模型决定要不要加载这个技能的依据。在实际运行时系统只会把这两个字段提供给模型做筛选只有当模型判断需要这个技能时完整SKILL.md才会被加载进上下文。这一点很像搜索引擎的索引页与正文页的关系。前者负责被检索和匹配后者负责在被需要时提供完整信息。frontmatter下面就是正文。正文的写法有几个原则我后面单独讲这里先记住一个核心它是写给人模型看的操作流程不是写给机器看的API文档。2.2 scripts真正干活的执行层脚本目录放的是具体的执行逻辑。这个设计有个很务实的意图让模型通过SKILL.md理解任务目标和步骤再通过调用脚本获得中间结果来逐步完成任务。比如上面的web-content-extractor流程是这样的模型拿到SKILL.md知道我要提取正文有脚本可以用。模型调用scripts/run.py传入URL参数。脚本返回处理后的文本。模型根据结果继续后续操作比如写摘要、翻译、归档。比较关键的一点是脚本不应该试图取代模型的判断能力而应该提供模型做不到的脏活累活能力。比如网络请求、HTML解析、图像处理、文件格式转换。模型负责的是决定怎么做脚本负责具体执行。2.3 resources技能相关的外部支撑材料resources目录是用来放参考材料的。这个目录更灵活可以是PDF、图片、数据字典、示例文件甚至是模板。为什么要单独安排一个resources目录因为不是所有参考资料都需要被脚本读取有些是给模型看的。比如你做一个涉及特定行业术语的技能可以在resources里放一份术语表SKILL.md中指引模型在需要时去查阅。这种分离存放、按需加载的思路贯穿整个技能的运行流程目的都是减少无谓的token消耗。3. 手写一个网页正文提取技能的完整过程前面拆得再清楚都不如亲自动手写一个技能包来得直接。我以自己实际做过的一个网页正文提取技能为例完整走一遍流程。3.1 先想清楚边界再动笔写SKILL.md写技能包最容易犯的错误是一上来就写代码。其实第一步应该是定义技能的边界。我当时给自己的技能定了几条规则输入一个可以公开访问的URL。输出干净的正文纯文本保留标题和段落结构。不做的事不处理需要登录的页面不渲染复杂JavaScript生成的内容不处理PDF那是另一个技能。失败时的行为如果页面提取不到正文内容返回明确错误信息不要返回整个HTML。定义完边界SKILL.md的正文就好写了。核心是给模型一个清晰的执行流程# Web Content Extractor ## 任务目标 从给定的网页URL中提取主要内容去除导航、侧边栏、广告、页脚等无关信息。 ## 执行步骤 1. 使用 scripts/run.py 请求目标URL参数为 --url 目标地址。 2. 如果脚本返回错误尝试更换URL格式如添加https://前缀后重试。 3. 如果脚本成功将返回的正文内容整理后提供给用户。 4. 整理时保留原文的段落层级删除多余空行。 ## 注意事项 - 脚本依赖目标网站结构不同新闻网站的表现差异较大输出异常时尝试更换来源URL。 - 提取结果仅为纯文本不包含图片和链接。 - 如果页面内容过短少于300字认定为提取失败。注意这里面的执行步骤是个非常重要的设计。它是在告诉模型先做什么遇到问题怎么办合格结果的标准是什么。模型拿到这套步骤之后会根据实际情况灵活调整但它不再需要凭空猜测了。3.2 编写脚本遵循一次调用、标准IO原则脚本部分我用的Python加上requests和BeautifulSoup两个库#!/usr/bin/env python3 import argparse import re import sys import requests from bs4 import BeautifulSoup def extract_main_content(html: str) - str: soup BeautifulSoup(html, html.parser) # 先移除明显不属于正文的模块 for tag in soup.find_all([nav, header, footer, aside, script, style]): tag.decompose() article soup.find(article) or soup.find(main) or soup.body if not article: return # 只保留文本段落去掉深层无用嵌套 paragraphs article.find_all(p) text_blocks [p.get_text(stripTrue) for p in paragraphs] text_blocks [b for b in text_blocks if len(b) 20] # 过滤短碎片 return \n\n.join(text_blocks) def main(): parser argparse.ArgumentParser(descriptionExtract main content from URL) parser.add_argument(--url, requiredTrue) args parser.parse_args() try: resp requests.get(args.url, timeout10, headers{ User-Agent: Mozilla/5.0 (compatible; agent-skills/1.0) }) resp.raise_for_status() content extract_main_content(resp.text) if len(content) 300: print(ERROR: extracted content is too short, the page may be protected or non-standard., filesys.stderr) sys.exit(1) print(content) except Exception as e: print(fERROR: {e}, filesys.stderr) sys.exit(1) if __name__ __main__: main()脚本设计上有个原则值得说一句脚本只做确定性的部分把判断留给模型。比如我不写任何摘要逻辑因为摘要是模型擅长的事我只负责把正文从HTML里拎出来这是模型不擅长且容易出错的事。另外脚本的输出必须简洁、干净。最好只输出正文内容或者加一个简单的错误格式不要把调试日志、进度信息混进来。模型需要从输出中快速判断下一步操作噪音太多会干扰它的决策。3.3 测试时用命令而不是口头描述去验证写完技能包后最关键的一步是用真实命令验证技能是否可用。这里说的可用包含两层意思脚本本身能不能跑通输出质量如何。模型读到SKILL.md之后能不能正确理解并调用脚本。我当时拿了三个不同类型的网站在测试结果发现了不少问题。比如某个网站结构特殊正文内容不在article里而是散落在多个div中又比如某个网站加了Cloudflare的校验直接请求会返回403。这些情况我在SKILL.md里补充了说明模型遇到403时会尝试换UA头或者直接告诉用户该页面需要额外的访问验证。这个实测-补充文档-再实测的循环非常关键。SKILL.md不只是一份静态说明它会随着真实场景的反馈不断迭代。这也提醒了我在写技能包时尽量预留一个常见异常及处理的段落让模型遇到问题时能参考。4. Agent的技能调度机制命中、加载与上下文管理技能包本身写好了接下来就要看Agent怎么知道在什么时候加载它了。这部分是整个agent-skills项目里最容易被人忽视、但对实际体验影响最大的环节。4.1 description是技能的唯一门面在大多数实现里Agent启动时只会拿到所有技能包的元数据列表通常是name、description、when_to_use这几个字段。模型会根据当前用户输入的任务类型在这个列表里做匹配有点像大脑快速扫一眼备忘录用的小标签。如果description写得不好技能包写得再好模型也不会去加载它。所以description的写作有个核心原则用用户会说的人话来写并且明确写出触发条件。举个例子。假设你的技能是用来处理Excel的description你写Advanced spreadsheet manipulation utilities for data processing operations——听起来很专业但模型看到的效果可能一般。你改成当用户提到Excel表格、xlsx、csv、表格数据清洗或转换时使用。支持读取、筛选、合并、拆分工作表——效果会好得多。原因在于模型匹配的是用户问题里的语义和你description里的语义你的描述越接近用户可能说的原话匹配成功率越高。这也解释了为什么技能包设计里when_to_use会被单独拆出来。它的作用就是逼着技能编写者想清楚一件事什么场景下用我这个技能想得越具体模型判断时就越不容易迷茫。4.2 按需加载的上下文压缩效果按需加载带来的一个直接好处是上下文窗口压力大幅下降。我拿自己的使用情况对比过方案每轮基础token消耗加载技能后token消耗说明全部技能写进system prompt约5k恒定5k每个任务都背着所有技能说明agent-skills按需加载约500约2k~3k大部分任务不需要加载任何技能在对话中多出来的这部分token是省不掉的但关键收益在于大量无关技能说明不再占用每轮上下文模型在推理时的注意力明显更集中。4.3 加载与卸载的时机技能加载并不是一次加载永久生效。我见过不少爱好者自主实现的方案加载逻辑写得非常简单只要某个技能被用到过就一直留在上下文里这会导致一个问题——对话主题切换到别的方向后之前的技能说明依然在上下文里占地方干扰后续推理。合理的做法应该是技能在任务切换后自动卸载。更精确地讲是Agent判断当前任务不涉及某个技能时要从上下文中移除或折叠对应的技能说明。当后续再遇到需要该技能的任务时重新加载。这种用则载、不用则卸的机制就是agent-skills项目在实践中最有区分度的地方。它不是简单的工具集而是带着一套有意识的上下文管理策略。4.4 技能冲突时的优先决策还有一种情况多个技能看起来都能解决当前问题。比如网页正文提取和网页标题批量提取输入都是一个URL列表用户说的却是帮我看看这个页面讲了啥。这时候模型会倾向于选择范围更贴近的正文提取技能。但如果两个技能的description都写得太宽泛模型就会犹豫。我在实战中的经验是尽量让技能的任务范围正交不要重叠。如果一个新技能和现有技能有大面积重合优先考虑扩展旧技能而不是新建一个。5. 实测中的数据表现与常见坑这一节说一些我实际跑agent-skills项目时遇到的真实问题也是社区里反馈最多的地方。每个坑背后都对应一条教训。5.1 我踩过的三个典型坑第一是脚本输出格式不规范。早期我写过一个生成报告的技能脚本直接打印了一段模板文本没有明确的成功/失败标记。结果模型在后续处理时把模板里的占位符错当成了真实内容折腾了很久。后来我把所有技能脚本的输出统一成成功就输出业务内容失败就输出ERROR:开头的信息模型处理起来省心很多。第二是SKILL.md写得过度详细。有些技能包作者担心模型理解不了把操作步骤写了十几条还加了大量背景介绍结果加载进去之后占了一堆token模型反而抓不住重点。现在我写SKILL.md正文控制在600字以内最多800字只保留流程、步骤、注意事项三个部分。第三是依赖环境不一致。这个问题在多人协作或迁移时特别明显。脚本用到的Python库没写进requirements.txt换环境跑就直接崩。后来我给自己定了一条规矩任何技能包的scripts目录下都必须有requirements.txt哪怕只有一个依赖也要显式声明。5.2 延迟表现需要注意的点技能加载确实会增加单次请求的处理时间。首次加载一个技能包要把SKILL.md和元数据注入上下文这会导致首token延迟增加几百毫秒到一两秒取决于技能说明的长度和模型服务的算力。但在长对话里这个成本会被摊薄。因为技能一旦加载后续任务就不再需要重复注入说明。如果你的Agent是一次性任务模式比如每次请求都是独立的新对话那技能加载的固定开销会占比较大比例。这种情况下可以考虑把最常用的技能预先放进系统提示词里把次常用的保留按需加载。5.3 如何调试模型就是不加载技能的问题如果你发现模型明明遇到了对应任务却始终不触发技能加载不要急着怪模型。按照下面这个链路排查先看技能列表里这个技能的name和description是不是被正确传给了模型。再看description里有没有出现关键词歧义。比如技能名叫url-fetcher但用户说的是抓取这个网页你的description里却写的是fetch URL data匹配不到很合理。然后跑一次带日志的会话把模型每次的选择过程打印出来看看它在候选技能里做了什么决策。最后如果一切正常但还是不加载可以在SKILL.md正文前加一行提示当用户需要获取网页内容时必须先使用此技能。预算一个排查链路听起来很基础但真的能解决80%的问题。6. 搭建自己的技能库从单技能到技能工厂单个技能跑通只是第一步。等到你的Agent需要五六个甚至十几个技能的时候怎么管理这些技能包就成了新的问题。下面是我自己在维护过程中总结的一些管理思路。6.1 技能命名与目录规范技能包的命名要符合两个标准一是自解释二是无歧义。web-content-extractor比extract好pdf-table-parser比pdf-tool好。另外目录层级建议保持扁平不要做太深的嵌套因为技能加载逻辑通常只是按文件名找SKILL.md目录嵌套太深会导致加载失败或路径出错。一个技能包一个文件夹所有文件平铺这是最简单的管理方式。6.2 技能测试用固定样本做回归为了确认改动不影响已有能力我维护了一套简单的测试样本包含每个技能的样例输入和期望输出。一两个典型的负例确保技能在错误场景下不会误触发。每次改完SKILL.md或脚本就跑一遍这套样本。这里给个非常实践的技巧把测试结果也放进一个独立的日志文件里不要只看通过/失败还要记录当时的加载耗时、返回内容长度。因为技能包的一个隐性指标是上下文消耗如果某次改动导致SKILL.md膨胀了30%即使功能没坏长期来看成本也不划算。6.3 如何借鉴社区项目做自己的体系agent-skills在开源社区里不是一个孤立的项目业界有非常多的借鉴思路。如果你打算构建自己的技能库比较推荐的做法是先列一个清单写下你的Agent最高频处理的十类任务。把每类任务拆成决策步骤和执行动作两部分。决策步骤留给模型执行动作判断是否需要脚本辅助。两类情况不需要做成技能包一种是系统prompt就能稳定搞定的简单任务另一种是高度依赖外部系统、需要复杂鉴权和状态管理的集成任务这类更适合用传统的function calling去做。把这十类任务里剩余的3-5个核心任务按前面讲的方法逐步做成技能包。6.4 公共技能与私有技能的拆分最后说一个容易被忽略的细节技能包也要区分公共和私有。像网页正文提取PDF转文本这种通用能力适合做成公共技能库团队内共享持续打磨。而像公司内部数据库查询特定业务报表生成这类包含业务逻辑甚至密钥信息的技能一定要做成私有技能和公共技能分开放置。我见过一些团队把API密钥直接放在技能包的脚本里传给模型这是非常有风险的做法。技能包的本质是一段可被模型读取和执行的代码凡是会出现在模型上下文里的东西都要假设它可能被说出来。所以涉及密钥的操作应该把凭证放在服务端环境变量里脚本从环境变量读模型上下文里只出现使用环境变量中的凭证这类描述。7. 一点个人总结技能包思维改变的不只是Agent能力做agent-skills项目这段时间我最深的体会是它改变的其实不只是Agent能做什么而是我怎么描述Agent的能力。过去我总觉得Agent的能力来自模型本身——模型越强Agent能做的事就越多。但技能包让我意识到真正的瓶颈在于如何把模型的通用智能稳定地嫁接到特定的领域任务上。SKILL.md本质上是在用人类可以理解的表达方式给模型搭建一座从理解到执行的桥梁。这个过程很像带实习生。你不能指望实习生第一天就能独立处理所有任务你得给他一本操作手册告诉他在什么场景下找哪个工具遇到问题先看哪一章哪些操作是红线。等你带过几批实习生你会发现最省力气的做法不是事事都亲力亲为而是把操作手册写清楚、把工具环境配好然后放手让他干。agent-skills就是这个思路在Agent世界的实践。它让我把对模型的不放心转化成了对技能包的持续迭代也让Agent的行为模式越来越稳定、越来越可预期。如果你也正在被提示词维护问题困扰不妨试试这套方法从第一个技能包开始搭起。