1. 从“skills”这个热词说起它到底在解决什么问题最近半年不管是在技术社区、开发者群聊还是各类工具讨论区“skills”这个词出现的频率高得离谱。很多人第一次看到“Agent Skills”或者“Claude Agent Skills”的时候第一反应是“这不就是个插件系统换了个名字吗”但真正上手用过之后会发现它想解决的根本不是插件的问题而是能力复用与组合的问题。我最早接触这个概念是在一个自动化内容处理的场景里。当时团队需要让一个智能体完成“抓取指定主题的公开资料、整理成结构化笔记、再生成一份可读性强的摘要”这样一条链路。如果按传统做法要么写一个庞大的提示词把所有逻辑塞进去要么拆成多个独立脚本用代码串起来。前者维护起来是灾难后者则失去了智能体本身灵活推理的优势。而 skills 这套机制恰好卡在中间它把一项具体能力封装成一个可描述、可调用、可组合的单元让智能体在需要的时候自己去“取用”而不是把所有东西都硬编码在一开始。这就是为什么“skills”会在短时间内衍生出这么多相关搜索词——agent skills测试、codex skills、skills开发、skills推荐、skills大全。大家关心的不是概念本身而是这东西怎么用、去哪找、怎么自己写、写完怎么测。我写这篇东西的目的就是把这几个月踩过的坑、试过的方案、以及一些不太容易在官方文档里看到的细节完整地摊开讲一遍。不管你是刚听说这个词想搞清楚它是什么还是已经在写自己的 skill 但卡在某个环节下面这些内容应该都能对上你的需求。2. 核心思路拆解为什么是“技能”而不是“插件”或“函数”2.1 从插件到技能抽象层级的变化传统插件系统的逻辑是宿主程序预留一组扩展点插件在扩展点里注册自己的实现。比如编辑器插件、浏览器扩展都是这个模式。它的前提是宿主知道自己在哪些地方需要扩展扩展点是预先设计好的。但智能体场景不一样。智能体面对的任务是开放式的你没法提前枚举出“它可能需要哪些能力”。今天让它处理一份表格明天让它分析一段代码后天让它根据几张图写一段分镜描述。如果还用插件思维就得为每一种可能的能力都预留一个扩展点这显然不现实。skills 的思路是把抽象层级往上提了一层它不关心宿主在哪里调用而是描述一项能力本身是什么、需要什么输入、会产生什么输出、在什么情况下应该被使用。智能体在推理过程中根据当前任务的需要自己去判断“我现在是不是该调用某个 skill”。这个判断过程可以是基于描述的语义匹配也可以是基于显式的触发条件。打个比方插件像是给一台机器预留好的标准接口你只能往那些接口上插东西而 skills 像是给一个助手一本能力手册手册里写着“我会做A、B、C每种能力需要什么材料、产出什么结果”助手自己翻手册决定用哪一项。2.2 技能封装带来的三个实际好处第一个好处是提示词的可维护性。在没有 skills 之前一个复杂任务的提示词往往会长到离谱几千字甚至上万字里面混杂着角色设定、任务描述、输出格式、边界条件、示例。一旦要改其中某个环节很容易牵一发而动全身。把能力拆成独立的 skill 之后每个 skill 只关心自己那一小块逻辑主提示词只需要负责调度和编排。第二个好处是能力的可测试性。这一点在agent skills测试这个搜索词里体现得很明显。一个独立的 skill 可以单独喂输入、单独看输出不用把整个链路跑一遍才能验证某个环节对不对。我自己的做法是给每个 skill 准备一组最小测试用例改完 skill 描述之后先跑这组用例通过了再放进主流程。第三个好处是跨项目的复用。你为一个项目写的“提取网页正文”skill换个项目只要场景类似就能直接拿来用最多改一下输入输出的字段名。这也是为什么会有skills推荐、skills大全这类需求——大家希望有一个地方能直接找到别人写好的、经过验证的 skill而不是每次都从零开始。2.3 一个容易踩的认知坑skill 不是越细越好刚开始写 skill 的时候很容易陷入“把每个动作都拆成一个 skill”的误区。比如“读取文件”一个 skill、“解析JSON”一个 skill、“格式化输出”一个 skill。拆到最后发现主流程里全是调度逻辑反而比原来更复杂了。我的经验是一个 skill 应该对应一个语义完整的任务单元而不是一个原子操作。判断标准很简单——如果你能用一句话向一个新人描述这个 skill 是干什么的而且这句话里不需要出现“然后”“接着”这类连接词那它就是一个合适的粒度。比如“根据给定主题生成一份结构化摘要”是一个合适的 skill“读取文件然后解析然后输出”就不是它应该被合并成一个“处理文件并输出结构化结果”的 skill。3. 核心细节解析一个 skill 到底由哪些部分组成3.1 描述信息决定 skill 会不会被正确调用skill 的描述信息是整个机制里最容易被低估的部分。很多人写 skill 的时候把大部分精力花在实现逻辑上描述随便写两句结果发现智能体要么不调用这个 skill要么在不该调用的时候调用。描述信息通常需要回答三个问题这个 skill 做什么、什么时候该用它、它需要什么。第一个问题决定语义匹配的准确性第二个问题决定触发时机的判断第三个问题决定调用前的参数准备。我试过的一个反面案例早期写了一个“文本摘要”skill描述只写了“对文本进行摘要”。结果在一个需要“提取关键信息”的任务里智能体没有调用它而是自己硬着头皮生成了一段质量很差的总结。后来把描述改成“当需要对一段较长的文本进行压缩、提取核心要点、生成简短概括时使用输入为原始文本输出为不超过指定字数的摘要”调用准确率明显上去了。注意描述里不要写实现细节比如“使用某某算法”“调用某某接口”。智能体关心的是能力和适用场景不是你怎么实现的。3.2 输入输出定义契约清晰才能组合skill 之间要能组合前提是输入输出的格式是明确的。这里说的明确不是指“大概知道是什么类型”而是指字段名、类型、是否必填、默认值、取值范围都要写清楚。我一般会用类似下面这样的结构来定义name: extract_article description: 从一段网页正文中提取标题、作者、发布时间和正文内容 input: raw_html: type: string required: true description: 网页的原始HTML字符串 base_url: type: string required: false description: 用于补全相对链接的基础URL output: title: type: string author: type: string publish_time: type: string format: ISO8601 content: type: string这样定义的好处是当另一个 skill 需要“文章内容”作为输入时它可以明确地知道应该从extract_article的输出里取content字段而不是猜。3.3 触发条件显式规则与语义匹配的取舍触发条件有两种写法一种是显式的规则比如“当输入中包含URL且用户要求提取内容时触发”另一种是纯语义描述让智能体自己判断。显式规则的好处是可控性强坏处是写多了会变得很僵硬而且很难穷举所有情况。纯语义描述灵活但对描述的质量要求很高写不好就容易误触发或者漏触发。我目前的习惯是以语义描述为主在容易混淆的场景下补充显式排除条件。比如一个“生成代码”的 skill我会在描述里写“适用于根据自然语言描述生成代码片段的场景”同时补一句“不适用于代码解释、代码审查、bug修复等场景”。后面这句排除条件能挡掉不少误调用。3.4 版本与依赖管理多人协作时绕不开的问题当 skill 数量多起来、参与的人多起来之后版本管理就成了必须面对的问题。我遇到过的情况是A 改了一个 skill 的输出字段名B 的流程里还在用旧字段名结果整个链路静默失败排查了半天才发现是字段对不上。比较稳妥的做法是给每个 skill 加版本号并且在依赖关系里明确指定版本。如果某个 skill 的输出格式发生了不兼容的变化就升大版本号依赖方需要显式更新。同时在 skill 的描述里保留一份变更记录方便排查问题时回溯。4. 实操过程从零写一个可用的 skill4.1 环境准备与基础结构搭建不管你用的是哪套支持 skills 的框架基础结构都大同小异。一般需要一个存放 skill 定义的目录每个 skill 一个子目录或者一个文件里面包含描述信息、输入输出定义、以及具体的执行逻辑。以我最近在用的一个结构为例skills/ extract_article/ skill.yaml # 描述、输入输出、触发条件 handler.py # 具体执行逻辑 tests/ cases.json # 测试用例 summarize_text/ skill.yaml handler.py tests/ cases.jsonskill.yaml负责声明handler.py负责实现tests/负责验证。这个结构的好处是职责清晰改描述不会碰到实现改实现不会影响描述。4.2 编写第一个 skill以“提取文章正文”为例先写skill.yamlname: extract_article version: 1.0.0 description: 从网页原始HTML中提取文章的主体内容包括标题、作者、发布时间和正文。 适用于需要对网页内容进行后续处理的场景如摘要生成、内容归档、信息抽取。 不适用于需要完整页面结构分析的场景。 input: raw_html: type: string required: true base_url: type: string required: false output: title: type: string author: type: string publish_time: type: string content: type: string再写handler.pyfrom bs4 import BeautifulSoup import re def handle(raw_html, base_urlNone): soup BeautifulSoup(raw_html, html.parser) title if soup.title: title soup.title.get_text(stripTrue) author author_meta soup.find(meta, attrs{name: author}) if author_meta: author author_meta.get(content, ) publish_time time_meta soup.find(meta, attrs{property: article:published_time}) if time_meta: publish_time time_meta.get(content, ) for tag in soup([script, style, nav, footer, header]): tag.decompose() content soup.get_text(separator\n, stripTrue) content re.sub(r\n{3,}, \n\n, content) return { title: title, author: author, publish_time: publish_time, content: content }这个实现很朴素但足够说明问题。实际用的时候可以根据目标站点的特点做针对性优化比如针对某些常见的文章容器选择器做优先匹配。4.3 测试用例的编写与执行tests/cases.json里放最小验证集[ { name: 基础文章提取, input: { raw_html: htmlheadtitle测试文章/title/headbodyarticlep这是正文第一段。/pp这是正文第二段。/p/article/body/html }, expect: { title: 测试文章, content_contains: [这是正文第一段, 这是正文第二段] } }, { name: 无标题场景, input: { raw_html: htmlbodyp只有正文没有标题。/p/body/html }, expect: { title: , content_contains: [只有正文没有标题] } } ]跑测试的时候我一般会写一个简单的 runner把每个用例的输入喂给 handler然后检查输出是否满足 expect 里的条件。content_contains这种模糊匹配比精确匹配更实用因为正文提取的结果往往会有细微的空白字符差异。4.4 把 skill 接入主流程skill 写好、测好之后接入主流程的方式取决于你用的框架。有的框架是自动扫描 skills 目录并注册有的需要显式声明。不管哪种方式核心都是让智能体在推理时能看到所有可用 skill 的描述然后自己决定调用哪个。我自己的做法是在主提示词里加一段说明告诉智能体“你可以使用以下技能来完成当前任务”然后把 skill 列表附上。如果框架支持自动注入那就更省事。提示接入之后一定要跑几个端到端的场景观察智能体是否在正确的时机调用了正确的 skill。这一步能发现很多单独测试 skill 时发现不了的问题比如描述之间的语义冲突、输入输出字段不匹配等。5. 常见问题与排查技巧实录5.1 skill 不被调用从描述和上下文两头查这是最常见的问题。排查顺序我一般是这样的先看描述是否足够具体。如果描述太泛比如“处理文本”智能体很难判断当前任务是否匹配。改成“对长文本进行压缩摘要输出不超过指定字数的概括”之后匹配度会明显提升。再看上下文里是否有更强的信号干扰。比如主提示词里已经明确说了“请直接生成摘要”那智能体可能就自己做了不会去调用 skill。这时候要么调整主提示词的措辞要么在 skill 描述里强调“当需要高质量摘要时优先使用本技能”。最后看 skill 的注册是否生效。有些框架需要重启或者重新加载才能识别新增的 skill这个坑我踩过不止一次。5.2 输出格式不稳定用 schema 约束而不是靠提示即使 skill 的 handler 返回了固定格式的字典经过智能体转述之后输出也可能变形。比如你返回的是{title: ..., content: ...}智能体在最终回复里可能写成“标题是xxx内容是yyy”。解决办法是在 skill 的输出定义里明确 schema并且在主提示词里要求“调用 skill 后严格按照其输出 schema 呈现结果”。如果框架支持结构化输出尽量开启能省掉很多格式对齐的麻烦。5.3 多个 skill 之间的字段对不上这个问题在 skill 数量多了之后特别常见。A skill 输出contentB skill 期望输入text中间没有做映射结果就是空值或者报错。我的做法是维护一份字段对照表记录每个 skill 的输入输出字段名和类型。新增 skill 或者修改字段时先查对照表看看有没有可以复用的字段名。如果确实需要不同的名字就在编排层加一个显式的映射步骤而不是指望智能体自己猜。常见问题排查方向解决手段skill 不被调用描述太泛、上下文干扰、注册未生效细化描述、调整主提示词、重新加载输出格式不稳定缺少 schema 约束明确输出 schema、开启结构化输出字段对不上命名不统一、缺少映射维护字段对照表、加显式映射调用时机错误触发条件模糊补充排除条件、增加正反例执行超时handler 逻辑太重拆分 skill、加超时和降级5.4 执行超时与降级策略有些 skill 的 handler 会做比较重的操作比如请求外部接口、处理大文件。如果不加超时控制一旦卡住就会拖垮整个流程。我一般会给每个 skill 设置一个合理的超时时间超时后返回一个带有错误标记的结果让主流程决定是重试、跳过还是走降级逻辑。降级逻辑可以是一个更简单的实现比如“提取正文”超时了就返回原始文本的前若干字符至少保证流程能继续走下去。5.5 调试技巧把 skill 的调用过程打出来排查 skill 相关问题的时候最有用的一招是把智能体的调用决策过程打出来。很多框架支持输出推理轨迹能看到它在每一步考虑了哪些 skill、为什么选了某个、为什么排除了某个。这个信息比单纯看最终输出有用得多。如果框架不支持可以在 skill 的 handler 里加日志记录每次被调用的输入和时间。结合主流程的日志基本能还原出调用链路。6. 技能组合与编排从单个 skill 到完整工作流6.1 串行组合前一个的输出是后一个的输入最简单的组合方式就是串行。比如“提取文章正文”的输出直接喂给“生成摘要”的输入。这种组合的关键是字段对齐前面提到的字段对照表在这里就派上用场了。串行组合的另一个注意点是错误传播。如果第一个 skill 失败了第二个 skill 拿到的就是空输入或者错误数据。所以每个 skill 的输出里最好带一个状态标记让下游能判断上游是否成功。6.2 并行组合多个 skill 同时处理同一份输入有些场景下同一份输入需要被多个 skill 分别处理最后把结果合并。比如一段文本既要提取关键词又要做情感分析还要生成摘要。这三个 skill 之间没有依赖关系可以并行执行。并行组合的难点在于结果合并。如果三个 skill 的输出格式各不相同合并逻辑就会很复杂。我的做法是让每个 skill 的输出都遵循一个统一的外层结构比如都包含status、data、error三个字段这样合并的时候只需要处理data部分。6.3 条件组合根据中间结果决定下一步更复杂的场景需要根据中间结果动态决定下一步走哪个分支。比如先判断文本的语言如果是中文走中文处理链路如果是英文走英文处理链路。这种组合方式对 skill 的描述要求更高因为智能体需要理解“在什么条件下应该选择哪个分支”。我一般会在主提示词里把分支逻辑写清楚而不是指望智能体自己推断。6.4 编排层的职责边界编排层不应该包含具体的业务逻辑它只负责调度和协调。具体的处理逻辑都在 skill 里。这个边界如果模糊了编排层就会变得越来越臃肿最后又回到“一个大提示词包打天下”的老路。我见过的一个反例是编排层里写了一堆条件判断和数据转换skill 反而成了简单的工具函数。这样做的后果是改一个业务规则要动编排层而编排层往往是最难测试的部分。正确的做法是把业务规则下沉到 skill 里编排层只做“什么时候调用哪个 skill”的决策。7. 技能的分发、复用与生态现状7.1 本地复用目录结构与命名规范在单个项目内部复用 skill最重要的是命名规范。我一般遵循“动词_名词”的格式比如extract_article、summarize_text、translate_content。这样从名字就能看出 skill 的功能也方便在编排层引用。目录结构上我习惯按功能域分组比如skills/extraction/、skills/transformation/、skills/generation/。这样 skill 多了之后不至于乱成一团。7.2 跨项目复用把 skill 做成独立包如果多个项目都需要用到同一组 skill可以考虑把它们抽成一个独立的包通过包管理工具分发。这样版本管理、依赖声明、更新升级都有成熟的机制可以用不用自己造轮子。抽包的时候要注意把 skill 的描述信息和实现逻辑一起打包因为描述信息是智能体调用决策的依据缺了它 skill 就没法被正确使用。7.3 社区生态去哪找现成的 skill目前已经有一些社区在收集和分享 skill 定义覆盖的场景从文本处理到代码生成到数据分析都有。找现成 skill 的时候我一般会看几个点描述是否清晰、输入输出是否明确、有没有测试用例、最近有没有更新。这几点都满足的基本可以直接拿来用或者稍作修改。不过也要注意别人的 skill 是针对别人的场景写的直接拿来用之前最好先在自己的数据上跑一遍测试用例确认行为符合预期。7.4 安全与权限调用外部能力时的边界如果 skill 的 handler 会访问外部资源或者执行有副作用的操作就需要考虑权限控制。比如一个“发送通知”的 skill不应该在任何情况下都能被随意调用而应该加上显式的确认步骤或者权限校验。我的做法是把有副作用的 skill 单独标记出来在编排层里对这类 skill 的调用加上额外的确认逻辑。同时在 skill 的描述里明确写出它的副作用让智能体在决策时有所感知。8. 我踩过的几个坑和对应的解法第一个坑是描述写得太抽象。早期写了一个“优化文本”的 skill描述就一句话。结果智能体要么不用它要么在不该用的时候用。后来把描述改成“对文本进行润色改善流畅度和可读性不改变原意适用于草稿修改场景”调用准确率才上来。第二个坑是输入输出没有做校验。有一个 skill 期望输入是 JSON 字符串但上游传过来的是已经解析好的字典结果 handler 里解析失败整个流程中断。后来在 handler 开头加了一个类型检查和兼容处理既能接受字符串也能接受字典问题就解决了。第三个坑是测试用例覆盖不够。有一个 skill 在正常输入下表现很好但遇到空输入或者超长输入就出问题。后来补了边界用例才发现空输入时没有做保护超长输入时没有做截断。这两个问题在端到端场景里很难复现因为正常流程很少走到这些边界。第四个坑是版本升级没有做兼容。改了一个 skill 的输出字段名但没有通知依赖方结果依赖方的流程静默失败。后来养成了习惯任何不兼容的改动都升大版本号并且在变更记录里写清楚影响范围。第五个坑是过度依赖智能体的自动决策。有些场景下智能体选择的 skill 并不是最优的但因为它“看起来也能用”就没有被拦截。后来在编排层加了一些硬性规则比如“当输入是URL时必须优先使用 extract_article”才把这类问题控制住。9. 写给准备开始写 skill 的人如果你刚开始接触 skills我的建议是从一个小而完整的场景入手不要一上来就设计一个大而全的技能体系。选一个你日常工作中反复出现的任务把它封装成一个 skill跑通从描述到实现到测试的完整流程。这个过程走一遍之后你对 skill 的粒度、描述怎么写、输入输出怎么定义都会有更具体的感知。另外不要追求一次写对。skill 的描述和实现都是迭代出来的。先写一个能用的版本在实际使用中观察它什么时候被调用、什么时候不被调用、输出是否符合预期然后针对性地调整。我自己的几个核心 skill 都改了不下十版每一版都是被实际问题逼出来的。最后保持 skill 的独立性。一个 skill 尽量不要依赖另一个 skill 的内部实现只通过明确定义的输入输出交互。这样任何一个 skill 需要替换或者升级时影响范围都是可控的。这个原则在 skill 数量少的时候可能感觉不到好处但等到你有几十个 skill 在跑的时候它会帮你省下大量的排查时间。 
长河君 · 2026/10/8 17:20:28 · 阅读 1.2k Agent Skills实战指南：从开发、测试到组合编排
1. 从“skills”这个热词说起它到底在解决什么问题最近半年不管是在技术社区、开发者群聊还是各类工具讨论区“skills”这个词出现的频率高得离谱。很多人第一次看到“Agent Skills”或者“Claude Agent Skills”的时候第一反应是“这不就是个插件系统换了个名字吗”但真正上手用过之后会发现它想解决的根本不是插件的问题而是能力复用与组合的问题。我最早接触这个概念是在一个自动化内容处理的场景里。当时团队需要让一个智能体完成“抓取指定主题的公开资料、整理成结构化笔记、再生成一份可读性强的摘要”这样一条链路。如果按传统做法要么写一个庞大的提示词把所有逻辑塞进去要么拆成多个独立脚本用代码串起来。前者维护起来是灾难后者则失去了智能体本身灵活推理的优势。而 skills 这套机制恰好卡在中间它把一项具体能力封装成一个可描述、可调用、可组合的单元让智能体在需要的时候自己去“取用”而不是把所有东西都硬编码在一开始。这就是为什么“skills”会在短时间内衍生出这么多相关搜索词——agent skills测试、codex skills、skills开发、skills推荐、skills大全。大家关心的不是概念本身而是这东西怎么用、去哪找、怎么自己写、写完怎么测。我写这篇东西的目的就是把这几个月踩过的坑、试过的方案、以及一些不太容易在官方文档里看到的细节完整地摊开讲一遍。不管你是刚听说这个词想搞清楚它是什么还是已经在写自己的 skill 但卡在某个环节下面这些内容应该都能对上你的需求。2. 核心思路拆解为什么是“技能”而不是“插件”或“函数”2.1 从插件到技能抽象层级的变化传统插件系统的逻辑是宿主程序预留一组扩展点插件在扩展点里注册自己的实现。比如编辑器插件、浏览器扩展都是这个模式。它的前提是宿主知道自己在哪些地方需要扩展扩展点是预先设计好的。但智能体场景不一样。智能体面对的任务是开放式的你没法提前枚举出“它可能需要哪些能力”。今天让它处理一份表格明天让它分析一段代码后天让它根据几张图写一段分镜描述。如果还用插件思维就得为每一种可能的能力都预留一个扩展点这显然不现实。skills 的思路是把抽象层级往上提了一层它不关心宿主在哪里调用而是描述一项能力本身是什么、需要什么输入、会产生什么输出、在什么情况下应该被使用。智能体在推理过程中根据当前任务的需要自己去判断“我现在是不是该调用某个 skill”。这个判断过程可以是基于描述的语义匹配也可以是基于显式的触发条件。打个比方插件像是给一台机器预留好的标准接口你只能往那些接口上插东西而 skills 像是给一个助手一本能力手册手册里写着“我会做A、B、C每种能力需要什么材料、产出什么结果”助手自己翻手册决定用哪一项。2.2 技能封装带来的三个实际好处第一个好处是提示词的可维护性。在没有 skills 之前一个复杂任务的提示词往往会长到离谱几千字甚至上万字里面混杂着角色设定、任务描述、输出格式、边界条件、示例。一旦要改其中某个环节很容易牵一发而动全身。把能力拆成独立的 skill 之后每个 skill 只关心自己那一小块逻辑主提示词只需要负责调度和编排。第二个好处是能力的可测试性。这一点在agent skills测试这个搜索词里体现得很明显。一个独立的 skill 可以单独喂输入、单独看输出不用把整个链路跑一遍才能验证某个环节对不对。我自己的做法是给每个 skill 准备一组最小测试用例改完 skill 描述之后先跑这组用例通过了再放进主流程。第三个好处是跨项目的复用。你为一个项目写的“提取网页正文”skill换个项目只要场景类似就能直接拿来用最多改一下输入输出的字段名。这也是为什么会有skills推荐、skills大全这类需求——大家希望有一个地方能直接找到别人写好的、经过验证的 skill而不是每次都从零开始。2.3 一个容易踩的认知坑skill 不是越细越好刚开始写 skill 的时候很容易陷入“把每个动作都拆成一个 skill”的误区。比如“读取文件”一个 skill、“解析JSON”一个 skill、“格式化输出”一个 skill。拆到最后发现主流程里全是调度逻辑反而比原来更复杂了。我的经验是一个 skill 应该对应一个语义完整的任务单元而不是一个原子操作。判断标准很简单——如果你能用一句话向一个新人描述这个 skill 是干什么的而且这句话里不需要出现“然后”“接着”这类连接词那它就是一个合适的粒度。比如“根据给定主题生成一份结构化摘要”是一个合适的 skill“读取文件然后解析然后输出”就不是它应该被合并成一个“处理文件并输出结构化结果”的 skill。3. 核心细节解析一个 skill 到底由哪些部分组成3.1 描述信息决定 skill 会不会被正确调用skill 的描述信息是整个机制里最容易被低估的部分。很多人写 skill 的时候把大部分精力花在实现逻辑上描述随便写两句结果发现智能体要么不调用这个 skill要么在不该调用的时候调用。描述信息通常需要回答三个问题这个 skill 做什么、什么时候该用它、它需要什么。第一个问题决定语义匹配的准确性第二个问题决定触发时机的判断第三个问题决定调用前的参数准备。我试过的一个反面案例早期写了一个“文本摘要”skill描述只写了“对文本进行摘要”。结果在一个需要“提取关键信息”的任务里智能体没有调用它而是自己硬着头皮生成了一段质量很差的总结。后来把描述改成“当需要对一段较长的文本进行压缩、提取核心要点、生成简短概括时使用输入为原始文本输出为不超过指定字数的摘要”调用准确率明显上去了。注意描述里不要写实现细节比如“使用某某算法”“调用某某接口”。智能体关心的是能力和适用场景不是你怎么实现的。3.2 输入输出定义契约清晰才能组合skill 之间要能组合前提是输入输出的格式是明确的。这里说的明确不是指“大概知道是什么类型”而是指字段名、类型、是否必填、默认值、取值范围都要写清楚。我一般会用类似下面这样的结构来定义name: extract_article description: 从一段网页正文中提取标题、作者、发布时间和正文内容 input: raw_html: type: string required: true description: 网页的原始HTML字符串 base_url: type: string required: false description: 用于补全相对链接的基础URL output: title: type: string author: type: string publish_time: type: string format: ISO8601 content: type: string这样定义的好处是当另一个 skill 需要“文章内容”作为输入时它可以明确地知道应该从extract_article的输出里取content字段而不是猜。3.3 触发条件显式规则与语义匹配的取舍触发条件有两种写法一种是显式的规则比如“当输入中包含URL且用户要求提取内容时触发”另一种是纯语义描述让智能体自己判断。显式规则的好处是可控性强坏处是写多了会变得很僵硬而且很难穷举所有情况。纯语义描述灵活但对描述的质量要求很高写不好就容易误触发或者漏触发。我目前的习惯是以语义描述为主在容易混淆的场景下补充显式排除条件。比如一个“生成代码”的 skill我会在描述里写“适用于根据自然语言描述生成代码片段的场景”同时补一句“不适用于代码解释、代码审查、bug修复等场景”。后面这句排除条件能挡掉不少误调用。3.4 版本与依赖管理多人协作时绕不开的问题当 skill 数量多起来、参与的人多起来之后版本管理就成了必须面对的问题。我遇到过的情况是A 改了一个 skill 的输出字段名B 的流程里还在用旧字段名结果整个链路静默失败排查了半天才发现是字段对不上。比较稳妥的做法是给每个 skill 加版本号并且在依赖关系里明确指定版本。如果某个 skill 的输出格式发生了不兼容的变化就升大版本号依赖方需要显式更新。同时在 skill 的描述里保留一份变更记录方便排查问题时回溯。4. 实操过程从零写一个可用的 skill4.1 环境准备与基础结构搭建不管你用的是哪套支持 skills 的框架基础结构都大同小异。一般需要一个存放 skill 定义的目录每个 skill 一个子目录或者一个文件里面包含描述信息、输入输出定义、以及具体的执行逻辑。以我最近在用的一个结构为例skills/ extract_article/ skill.yaml # 描述、输入输出、触发条件 handler.py # 具体执行逻辑 tests/ cases.json # 测试用例 summarize_text/ skill.yaml handler.py tests/ cases.jsonskill.yaml负责声明handler.py负责实现tests/负责验证。这个结构的好处是职责清晰改描述不会碰到实现改实现不会影响描述。4.2 编写第一个 skill以“提取文章正文”为例先写skill.yamlname: extract_article version: 1.0.0 description: 从网页原始HTML中提取文章的主体内容包括标题、作者、发布时间和正文。 适用于需要对网页内容进行后续处理的场景如摘要生成、内容归档、信息抽取。 不适用于需要完整页面结构分析的场景。 input: raw_html: type: string required: true base_url: type: string required: false output: title: type: string author: type: string publish_time: type: string content: type: string再写handler.pyfrom bs4 import BeautifulSoup import re def handle(raw_html, base_urlNone): soup BeautifulSoup(raw_html, html.parser) title if soup.title: title soup.title.get_text(stripTrue) author author_meta soup.find(meta, attrs{name: author}) if author_meta: author author_meta.get(content, ) publish_time time_meta soup.find(meta, attrs{property: article:published_time}) if time_meta: publish_time time_meta.get(content, ) for tag in soup([script, style, nav, footer, header]): tag.decompose() content soup.get_text(separator\n, stripTrue) content re.sub(r\n{3,}, \n\n, content) return { title: title, author: author, publish_time: publish_time, content: content }这个实现很朴素但足够说明问题。实际用的时候可以根据目标站点的特点做针对性优化比如针对某些常见的文章容器选择器做优先匹配。4.3 测试用例的编写与执行tests/cases.json里放最小验证集[ { name: 基础文章提取, input: { raw_html: htmlheadtitle测试文章/title/headbodyarticlep这是正文第一段。/pp这是正文第二段。/p/article/body/html }, expect: { title: 测试文章, content_contains: [这是正文第一段, 这是正文第二段] } }, { name: 无标题场景, input: { raw_html: htmlbodyp只有正文没有标题。/p/body/html }, expect: { title: , content_contains: [只有正文没有标题] } } ]跑测试的时候我一般会写一个简单的 runner把每个用例的输入喂给 handler然后检查输出是否满足 expect 里的条件。content_contains这种模糊匹配比精确匹配更实用因为正文提取的结果往往会有细微的空白字符差异。4.4 把 skill 接入主流程skill 写好、测好之后接入主流程的方式取决于你用的框架。有的框架是自动扫描 skills 目录并注册有的需要显式声明。不管哪种方式核心都是让智能体在推理时能看到所有可用 skill 的描述然后自己决定调用哪个。我自己的做法是在主提示词里加一段说明告诉智能体“你可以使用以下技能来完成当前任务”然后把 skill 列表附上。如果框架支持自动注入那就更省事。提示接入之后一定要跑几个端到端的场景观察智能体是否在正确的时机调用了正确的 skill。这一步能发现很多单独测试 skill 时发现不了的问题比如描述之间的语义冲突、输入输出字段不匹配等。5. 常见问题与排查技巧实录5.1 skill 不被调用从描述和上下文两头查这是最常见的问题。排查顺序我一般是这样的先看描述是否足够具体。如果描述太泛比如“处理文本”智能体很难判断当前任务是否匹配。改成“对长文本进行压缩摘要输出不超过指定字数的概括”之后匹配度会明显提升。再看上下文里是否有更强的信号干扰。比如主提示词里已经明确说了“请直接生成摘要”那智能体可能就自己做了不会去调用 skill。这时候要么调整主提示词的措辞要么在 skill 描述里强调“当需要高质量摘要时优先使用本技能”。最后看 skill 的注册是否生效。有些框架需要重启或者重新加载才能识别新增的 skill这个坑我踩过不止一次。5.2 输出格式不稳定用 schema 约束而不是靠提示即使 skill 的 handler 返回了固定格式的字典经过智能体转述之后输出也可能变形。比如你返回的是{title: ..., content: ...}智能体在最终回复里可能写成“标题是xxx内容是yyy”。解决办法是在 skill 的输出定义里明确 schema并且在主提示词里要求“调用 skill 后严格按照其输出 schema 呈现结果”。如果框架支持结构化输出尽量开启能省掉很多格式对齐的麻烦。5.3 多个 skill 之间的字段对不上这个问题在 skill 数量多了之后特别常见。A skill 输出contentB skill 期望输入text中间没有做映射结果就是空值或者报错。我的做法是维护一份字段对照表记录每个 skill 的输入输出字段名和类型。新增 skill 或者修改字段时先查对照表看看有没有可以复用的字段名。如果确实需要不同的名字就在编排层加一个显式的映射步骤而不是指望智能体自己猜。常见问题排查方向解决手段skill 不被调用描述太泛、上下文干扰、注册未生效细化描述、调整主提示词、重新加载输出格式不稳定缺少 schema 约束明确输出 schema、开启结构化输出字段对不上命名不统一、缺少映射维护字段对照表、加显式映射调用时机错误触发条件模糊补充排除条件、增加正反例执行超时handler 逻辑太重拆分 skill、加超时和降级5.4 执行超时与降级策略有些 skill 的 handler 会做比较重的操作比如请求外部接口、处理大文件。如果不加超时控制一旦卡住就会拖垮整个流程。我一般会给每个 skill 设置一个合理的超时时间超时后返回一个带有错误标记的结果让主流程决定是重试、跳过还是走降级逻辑。降级逻辑可以是一个更简单的实现比如“提取正文”超时了就返回原始文本的前若干字符至少保证流程能继续走下去。5.5 调试技巧把 skill 的调用过程打出来排查 skill 相关问题的时候最有用的一招是把智能体的调用决策过程打出来。很多框架支持输出推理轨迹能看到它在每一步考虑了哪些 skill、为什么选了某个、为什么排除了某个。这个信息比单纯看最终输出有用得多。如果框架不支持可以在 skill 的 handler 里加日志记录每次被调用的输入和时间。结合主流程的日志基本能还原出调用链路。6. 技能组合与编排从单个 skill 到完整工作流6.1 串行组合前一个的输出是后一个的输入最简单的组合方式就是串行。比如“提取文章正文”的输出直接喂给“生成摘要”的输入。这种组合的关键是字段对齐前面提到的字段对照表在这里就派上用场了。串行组合的另一个注意点是错误传播。如果第一个 skill 失败了第二个 skill 拿到的就是空输入或者错误数据。所以每个 skill 的输出里最好带一个状态标记让下游能判断上游是否成功。6.2 并行组合多个 skill 同时处理同一份输入有些场景下同一份输入需要被多个 skill 分别处理最后把结果合并。比如一段文本既要提取关键词又要做情感分析还要生成摘要。这三个 skill 之间没有依赖关系可以并行执行。并行组合的难点在于结果合并。如果三个 skill 的输出格式各不相同合并逻辑就会很复杂。我的做法是让每个 skill 的输出都遵循一个统一的外层结构比如都包含status、data、error三个字段这样合并的时候只需要处理data部分。6.3 条件组合根据中间结果决定下一步更复杂的场景需要根据中间结果动态决定下一步走哪个分支。比如先判断文本的语言如果是中文走中文处理链路如果是英文走英文处理链路。这种组合方式对 skill 的描述要求更高因为智能体需要理解“在什么条件下应该选择哪个分支”。我一般会在主提示词里把分支逻辑写清楚而不是指望智能体自己推断。6.4 编排层的职责边界编排层不应该包含具体的业务逻辑它只负责调度和协调。具体的处理逻辑都在 skill 里。这个边界如果模糊了编排层就会变得越来越臃肿最后又回到“一个大提示词包打天下”的老路。我见过的一个反例是编排层里写了一堆条件判断和数据转换skill 反而成了简单的工具函数。这样做的后果是改一个业务规则要动编排层而编排层往往是最难测试的部分。正确的做法是把业务规则下沉到 skill 里编排层只做“什么时候调用哪个 skill”的决策。7. 技能的分发、复用与生态现状7.1 本地复用目录结构与命名规范在单个项目内部复用 skill最重要的是命名规范。我一般遵循“动词_名词”的格式比如extract_article、summarize_text、translate_content。这样从名字就能看出 skill 的功能也方便在编排层引用。目录结构上我习惯按功能域分组比如skills/extraction/、skills/transformation/、skills/generation/。这样 skill 多了之后不至于乱成一团。7.2 跨项目复用把 skill 做成独立包如果多个项目都需要用到同一组 skill可以考虑把它们抽成一个独立的包通过包管理工具分发。这样版本管理、依赖声明、更新升级都有成熟的机制可以用不用自己造轮子。抽包的时候要注意把 skill 的描述信息和实现逻辑一起打包因为描述信息是智能体调用决策的依据缺了它 skill 就没法被正确使用。7.3 社区生态去哪找现成的 skill目前已经有一些社区在收集和分享 skill 定义覆盖的场景从文本处理到代码生成到数据分析都有。找现成 skill 的时候我一般会看几个点描述是否清晰、输入输出是否明确、有没有测试用例、最近有没有更新。这几点都满足的基本可以直接拿来用或者稍作修改。不过也要注意别人的 skill 是针对别人的场景写的直接拿来用之前最好先在自己的数据上跑一遍测试用例确认行为符合预期。7.4 安全与权限调用外部能力时的边界如果 skill 的 handler 会访问外部资源或者执行有副作用的操作就需要考虑权限控制。比如一个“发送通知”的 skill不应该在任何情况下都能被随意调用而应该加上显式的确认步骤或者权限校验。我的做法是把有副作用的 skill 单独标记出来在编排层里对这类 skill 的调用加上额外的确认逻辑。同时在 skill 的描述里明确写出它的副作用让智能体在决策时有所感知。8. 我踩过的几个坑和对应的解法第一个坑是描述写得太抽象。早期写了一个“优化文本”的 skill描述就一句话。结果智能体要么不用它要么在不该用的时候用。后来把描述改成“对文本进行润色改善流畅度和可读性不改变原意适用于草稿修改场景”调用准确率才上来。第二个坑是输入输出没有做校验。有一个 skill 期望输入是 JSON 字符串但上游传过来的是已经解析好的字典结果 handler 里解析失败整个流程中断。后来在 handler 开头加了一个类型检查和兼容处理既能接受字符串也能接受字典问题就解决了。第三个坑是测试用例覆盖不够。有一个 skill 在正常输入下表现很好但遇到空输入或者超长输入就出问题。后来补了边界用例才发现空输入时没有做保护超长输入时没有做截断。这两个问题在端到端场景里很难复现因为正常流程很少走到这些边界。第四个坑是版本升级没有做兼容。改了一个 skill 的输出字段名但没有通知依赖方结果依赖方的流程静默失败。后来养成了习惯任何不兼容的改动都升大版本号并且在变更记录里写清楚影响范围。第五个坑是过度依赖智能体的自动决策。有些场景下智能体选择的 skill 并不是最优的但因为它“看起来也能用”就没有被拦截。后来在编排层加了一些硬性规则比如“当输入是URL时必须优先使用 extract_article”才把这类问题控制住。9. 写给准备开始写 skill 的人如果你刚开始接触 skills我的建议是从一个小而完整的场景入手不要一上来就设计一个大而全的技能体系。选一个你日常工作中反复出现的任务把它封装成一个 skill跑通从描述到实现到测试的完整流程。这个过程走一遍之后你对 skill 的粒度、描述怎么写、输入输出怎么定义都会有更具体的感知。另外不要追求一次写对。skill 的描述和实现都是迭代出来的。先写一个能用的版本在实际使用中观察它什么时候被调用、什么时候不被调用、输出是否符合预期然后针对性地调整。我自己的几个核心 skill 都改了不下十版每一版都是被实际问题逼出来的。最后保持 skill 的独立性。一个 skill 尽量不要依赖另一个 skill 的内部实现只通过明确定义的输入输出交互。这样任何一个 skill 需要替换或者升级时影响范围都是可控的。这个原则在 skill 数量少的时候可能感觉不到好处但等到你有几十个 skill 在跑的时候它会帮你省下大量的排查时间。