1. 自定义 Skill 的价值与设计思路我一直觉得OpenSkills 这类框架对 Skill 的定义其实和一个团队招人非常像。你看一个新人进来首先得知道他是干什么的、擅长什么、在什么场景下能帮上忙。框架里的 Skill 也一样它本质上是给智能体配置的一种专业能力外包服务——把我们平时做业务时重复调用模型、处理文本、转格式、调接口这类固定动作封装成一个模型可以主动识别并调用的独立模块。这是一个非常聪明的设计模型不擅长的事情交给代码去做代码不擅长理解意图的地方交给模型去判断二者各管一段。这一篇我们实操的是自定义 Skill。很多人会用框架自带的 Skill但一说到自己写就觉得门槛很高。其实自定义 Skill 的核心没有那么玄乎主要就三件事第一搞清楚 Skill 这个外壳长得什么样第二把输入输出的结构设计好第三把什么时候该触发这个边界条件写清楚。只要把这三件事做扎实你写出来的 Skill 在项目里就是妥妥的外挂。而且我可以负责任地说自己写 Skill 的收益通常远超调现成的因为业务里最核心的专属逻辑往往就在这些别人替不了你的流程里。这个能力适合谁简单来说只要你手头有一个用 OpenSkills 搭起来的智能体应用不管是做内容处理、数据清洗还是对接内部接口都有必要把高频重复的环节抽成自定义 Skill。它能帮你把一个会聊天的模型变成一个能干活的执行者。这篇文章我会从设计、结构、代码实现到问题排查完整走一遍代码也会给出可以直接抄作业的版本你照着跑一遍就能看出效果。2. 自定义 Skill 的核心结构与实现机制2.1 Skill 的三个关键组成部分在动手写之前先把 Skill 的骨架子摸清楚。OpenSkills 框架里一个 Skill 的常规组成可以归纳为三个部分元信息描述、上下文约束和执行模块。第一部分是元信息描述。这一块负责告诉智能体这个 Skill 叫什么、是干什么用的、什么情况下你应该想起来用它。它相当于一份使用说明书加上触发条件清单。Description 写得好不好直接影响模型能不能在恰当的时候把 Skill 捞出来。如果你写得过于宽泛模型会在不该调用的场景下强行调用写得过于狭窄模型又会视而不见。这中间的度是第一个要磨的细节。第二部分是上下文约束。这里主要定义 Skill 接收什么格式的数据需要哪些前置信息。比如一个文本摘要的 Skill它需要接收原文、语言偏好、摘要长度上限一个定时任务提醒的 Skill它可能需要接收截止时间、任务描述和通知渠道。把输入边界定义清楚模型就不会把乱七八糟的东西塞给你。第三部分是执行模块。这是真正干活的代码。它接收模型传过来的结构化参数执行具体的逻辑最后把结果返回到对话流里。这里的返回结果最好是一个干净的结构化数据方便模型基于结果做进一步的解释或追问。我之前见过有人在执行模块里返回一大堆日志和调试信息结果模型直接被带偏在回答中反复提及这些无关细节非常影响体验。2.2 Skill 被调用的完整生命周期理解 Skill 什么时候被调用、调用过程中发生了什么比单纯拼代码更关键。用一句话概括整个生命周期模型先做意图判断再按 Skill 定义拼参数拼好参数后调用执行模块拿到结果后整理成回复。详细拆开看一次完整的 Skill 调用是这样一个链路意图识别阶段。用户发出请求模型先基于当前对话历史比对候选 Skill 的元信息描述判断当前这个问题是不是该用某个 Skill 来做。这一步完全依赖描述写得好不好。参数组装阶段。模型根据用户的原始输入提取出 Skill 定义里要求的字段按照输入约束把它们拼装起来。这一步最容易出错比如用户说把这篇报道总结成 200 字摘要模型可能把200字识别成摘要长度也可能理解成摘要语言完全取决于字段名称和描述是否足够生动具体。调用执行阶段。框架将组装好的结构化参数传给执行代码代码运行后返回一个结果对象。这个阶段耗时主要看你的逻辑复杂度——如果是轻量文本处理基本是毫秒级如果涉及外部接口调用就要看网络状况了。结果回填阶段。模型拿到执行结果将其组织成自然语言回复如果结果里带数据表或 JSON模型也能做进一步解析和总结。我在实际项目里看到的绝大多数自定义 Skill 问题都出在第一和第二阶段不是代码跑不起来而是模型压根没在正确的时机调用或者传参传得七扭八歪。这就引出一个技巧Skill 的描述文档里建议用当用户需要……时这种条件句来引导对比干巴巴的功能描述命中率能高出不少。2.3 为什么说描述即代码很多开发者把精力全放在执行函数上对描述文本敷衍了事这是一个非常普遍的误区。我甚至敢说在 Skill 开发里描述文本的重要性和代码是五五开有时候甚至更高。模型就像一个阅读能力极强但社会经验为零的新员工它只能靠你写的说明去理解工具用在何处。你描述得越贴近真实使用语境它就越能在关键时刻做出准确选择。另外描述文本里还应包含明确的边界提示比如本 Skill 不适用于……场景当用户提供的信息不足时应要求补充……这种约束性语句。不要小看这里模型对大段自由文本里的否定句和条件句其实非常敏感这些内容能明显降低误调用率。这算是我自己总结的一个小偏方写描述时多花十分钟后面能省掉大量反复调试。3. 实操从零实现一个可落地的自定义 Skill3.1 选定一个实用的练手场景为了把流程讲透我挑一个非常常见、几乎每个做内容或数据的人都用得上场景写一个长文本结构化提取的 Skill。这个 Skill 接收一段长篇文本自动提取其中的核心信息比如主题、关键人物、时间线、行动项最终输出一个结构化的 Markdown 报告。选这个场景有两个理由第一它逻辑清晰前中后期都好验证第二它对输入文本没有严苛格式要求方便你自己捏造几段测试数据跑通全流程。在动手前要先把这个 Skill 的边界想好。它做什么——提取信息并按固定结构输出它不做什么——不做情感分析、不做语言翻译、不做摘要改写。这个边界在后期写描述时会统一体现。3.2 Skill 定义文件怎么写在 OpenSkills 框架里一个 Skill 通常用一个目录来组织目录里包括一个描述文件和一个执行脚本。我们先用一个名为skill_info.md的描述文件来说明这个文件名不同版本稍有差异但语义一致。内容可以直接套用下面这个模板--- name: text_info_extractor description: 从用户提供的长文本中提取核心信息输出结构化 Markdown 报告。当用户需要整理会议纪要、快速了解一篇文章要点、提取访谈记录中的行动项时调用该技能。 input: - name: source_text type: string required: true description: 需要提取信息的原始文本建议直接提供全文不要提前压缩。 - name: language type: string required: false default: chinese description: 输出报告的语言支持 chinese 和 english默认为 chinese。 --- # 使用说明 使用该技能时应直接将原始文本完整传入不要对文本进行截断或改写。若用户提供的文本明显不足无法提取出足够信息则提示用户补充更多原文。 # 输出要求 以 Markdown 格式输出以下结构 1. 主题概述用三到五句话概括文本核心内容 2. 关键人物/角色列出文中重要的人或组织简要说明角色 3. 时间线按时间顺序排列的重要事件 4. 行动项若文本中提到了待办事项列为可执行清单 5. 疑问与缺失信息列出文本中未交代清楚的细节供后续追问这个模板看起来简单但每一个字段都是有明确目的的。name是全局唯一标识框架靠它把 Skill 注册到可调用列表里description是触发匹配的核心依据我特意在开头就写了提取核心信息然后在后面补了三个高频触发场景input清单则规范了参数结构尤其要把语言设置成可选项并给默认值这样既能减少模型传参的出错率又不影响主流程输出。3.3 执行模块的实现与参数绑定描述文件定了规范真正的处理逻辑放在执行脚本里。以 Python 为例一个最小可用的执行模块长这样import re from datetime import datetime def extract_dates(text): # 简易日期模式匹配支持 2025-02-13、2025年2月13日 等常见格式 date_patterns [ r(\d{4})[-/年](\d{1,2})[-/月](\d{1,2})日?, r(\d{1,2})月(\d{1,2})日 ] dates [] for pattern in date_patterns: matches re.findall(pattern, text) dates.extend(matches) return dates def main(source_text: str, language: str chinese) - str: key_dates extract_dates(source_text) # 这里可以继续补充实体识别、关键词提取等逻辑 result_sections { source_length: len(source_text), dates_found: key_dates, preview: source_text[:200] } if language english: return render_english_report(result_sections) return render_chinese_report(result_sections) def render_chinese_report(data) - str: lines [## 提取报告, ] lines.append(f- 原文长度{data[source_length]} 字) lines.append(f- 识别到的日期{, .join(data[dates_found]) if data[dates_found] else 未识别到明确日期}) lines.append() lines.append(### 原文预览) lines.append(data[preview].replace(\n, )) return \n.join(lines) def render_english_report(data) - str: status No explicit dates found if not data[dates_found] else , .join(data[dates_found]) lines [## Extracted Report, ] lines.append(f- Source length: {data[source_length]} characters) lines.append(f- Dates detected: {status}) lines.append() lines.append(### Preview) lines.append(data[preview].replace(\n, )) return \n.join(lines)在这个示例里我用正则做日期提取只是一个演示真正的核心是让你看清楚参数进入执行模块的流向。source_text和language这两个字段会在运行时自动绑定用户在对话里提供的信息用户不需要关心这个函数叫什么、文件在哪只需要描述清楚需求即可。3.4 注册 Skill 到项目并触发验证执行模块写完还需要把 Skill 挂载到主项目上。挂载步骤通常在项目的配置入口里完成。这样理解主工程像是一个 App StoreSkill 是一个个 App你把它上架了智能体运行时才能检索到它。在 OpenSkills 里挂载通常是这样一段代码from open_skills import SkillRegistry, load_skill_from_directory registry SkillRegistry() skill load_skill_from_directory(skills/text_info_extractor) registry.register(skill)注册之后你可以直接用一条模拟对话来验证触发流程。比如在调试控制台里发一句话下面这段文字是今天上午的会议记录请你帮我提取一下核心要点和待办事项。段落内容见附件。模型在收到这条消息后会对候选 Skill 做意图匹配这个新挂载的 Skill 会出现在候选列表里并且因为描述命中而被选中进而走完参数组装、执行、回填流程。验证时的关键观察点是模型是否真的把完整文本传给了source_text而不是只传了一小段截取内容。如果模型总是传不完整一种有效的调整策略是在描述里增加一个强调调用时必须完整传入原始文本不得截断或自行概括原文。3.5 增加一层前置校验来提升健壮性在实际业务中模型传过来的参数有时候会很不规范比如source_text字段是空字符串language字段传了英文而不是english。与其指望模型永远不出错不如在自己的代码里加一层防御机制。我在生产项目里习惯给每个 Skill 的执行入口加一个参数校验函数逻辑大概是这样def validate_params(source_text: str, language: str): if not source_text or len(source_text.strip()) 20: response 提供的文本过短或为空无法提取有效信息请补充更完整的原文。 return False, response normalized_lang language.lower().strip() if normalized_lang in (chinese, 中文, zh, cn): normalized_lang chinese elif normalized_lang in (english, 英文, en, eng): normalized_lang english else: normalized_lang chinese return True, normalized_lang这一层的作用是兜底它不会影响正常路径的执行效率但能显著提高用户对 Skill 的感知质量。模型传参不规范时至少不会直接抛异常给用户而是能优雅地返回一条提示。这类防御性设计在你面向非技术用户部署时尤其重要。4. 自定义 Skill 的进阶设计上下文、依赖与执行边界4.1 上下文感知让 Skill 不只是无状态工具基础版 Skill 可以理解成一个无状态函数独立运行完就直接返回结果。但实际业务场景里用户的输入往往依赖更完整的上下文。比如你写了一个周报生成的 Skill用户直接说汇报本周内容模型虽然在意图识别阶段能匹配到但因为消息里没有具体的工作事项生成的周报就会非常空泛。这种时候与其让 Skill 硬着头皮输出废话不如把上下文不足检测写进技能里。在定义文件里可以声明一个前置检查项如果用户消息中缺乏必要信息则要求模型先追问而不是急于输出。这个处理逻辑可以写进描述文件的使用说明中也可以在执行模块里做成一个可选的require_context开关。我在实践中把两者结合起来描述负责提示模型信息不足时反问代码负责对输入再次校验双保险。4.2 依赖隔离与轻量打包自定义 Skill 最大的隐患之一就是依赖管理失控。每个 Skill 如果都往全局环境里装一堆包最终项目会变得非常臃肿甚至出现两个 Skill 依赖同一个包但版本冲突的尴尬局面。我的习惯做法是给每个 Skill 创建独立的虚拟环境依赖清单并在挂载时声明它依赖哪些第三方库。框架如果支持依赖声明机制就明确写进 Skill 目录下的依赖文件里这样做的好处是后续如果某个技能废弃清理时也能连依赖一并移除不会留下垃圾。另外我还是建议尽量少依赖重型框架能用标准库解决的就不要拉第三方包。就以文本提取为例re能处理批量匹配标准库的 JSON 和字符串方法能覆盖 80% 的格式化需求。轻依赖意味着更快的加载速度和更少的兼容性问题在异构部署环境中尤其划算。4.3 多步骤 Skill如何衔接后续动作有些任务只调一次 Skill 是不够的。举个例子一个竞品动态追踪的技能它可能需要先抓取网页然后抽取关键信息再和昨天的结果做对比最后生成报告。这一整条链路如果拆成三个 Skill让模型自己判断每一步去调哪个会非常不可控。更好的方案是定义成一个复合 Skill内部按顺序执行多个处理步骤只在最后给模型返回一个总结性的执行结果。我见过不少框架允许 Skill 内部做多阶段处理然后通过一个统一的入口暴露给模型。这个设计能显著降低模型的决策负担。它的本质是把确定性任务全部压制在代码层只把真正的意图判断留在模型层。这样既保留了大模型的灵活性又把业务逻辑的确定性牢牢握在工程手里。4.4 与外部接口结合时的超时控制现实中不少自定义 Skill 会涉及调用第三方 API。这个时候有一个专门坑很多的地方超时和异常处理。模型在聊天窗口里等着如果底层 API 卡了 30 秒没返回对话体验基本就毁了。每一次对外部接口的调用都要显式设置超时时间并准备降级方案。比如你在 Skill 里调用一个外部翻译接口就要考虑如果接口失败是返回一个翻译服务暂时不可用的提示还是回退到本地简易词典翻译这些逻辑虽然不是模型能看到的但它最终会变成用户体验的一部分。我在实际项目里就把超时时间设得比较短宁可偶尔失败重试也不愿意让用户对着一个转圈的小图标发呆。5. 常见问题与排查技巧实录5.1 问题速查表我把自定义 Skill 开发中最常遇到的几个问题整理成一张速查表方便你对照排查问题现象根本原因处理方法模型从不在对话中调用这个 Skill描述文件过于模糊或触发场景覆盖率太低重写描述增加具体触发场景使用当用户需要……时句式Skill 被调用但参数总是缺失输入字段描述不清晰或 required 标记不正确在描述中补充字段说明并强调必须提供完整字段模型返回的结果格式混乱输出规范未写清或执行模块返回自由文本让执行模块严格返回结构化数据并在描述里明确输出格式Skill 执行出错对话就中断执行函数缺少异常捕获在 main 入口包一层 try-except异常时返回友好提示项目加载后找不到新写的 Skill路径不对或未重新初始化注册表检查挂载路径确认注册函数执行顺序同一段文本被多个 Skill 重复处理边界重叠描述中缺乏排除条件在描述中明确该技能不处理……的限制条件5.2 排查示例模型假装调用但没真正走通这里分享一次真实的排查过程。有一次我写了一个数据清洗的 Skill发现对话里模型会回复好的我帮你清洗了数据但返回的结果明显不对。起初我以为是参数传错后来把日志打开才发现模型根本没有调用 Skill它是在空想。为什么会这样因为我把 Skill 的名字和描述写得像一个普通对话建议模型觉得凭自己的常识就能回答不需要调工具。解决方式是把描述改成更工具化的表达明确说明这是一个数据处理工具必须调用后才能得到准确结果同时把执行模块的返回结果通过框架的提示系统回传让模型意识到外部工具输出和自身生成内容是两码事。这个问题其实非常典型尤其在那些模型知识覆盖较全的领域里容易发生。工具描述与模型能力边界一旦模糊模型就会自作聪明。5.3 调试技巧如何用最小样本定位问题自定义 Skill 的调试往往没有现成的交互式断点那么方便我自己常用的手法是把执行函数做成可独立运行的脚本在脚本里用写死的参数调用核心逻辑。这样做有几个好处第一可以绕过整个模型链路快速判断是不是自己代码的逻辑问题第二方便做回归测试改完一个地方直接云跑一遍旧用例防止副作用。在独立调试时我会构造三类测试输入正常完整参数、缺字段参数、超长文本参数。这三种类型基本能覆盖绝大部分执行崩溃的场景。等代码稳了再挂回模型做端到端验证这时候如果还出问题就可以把锅精准地甩给意图识别或参数组装而不是去怀疑底层逻辑。5.4 独门避坑技巧给 Skill 加预产检最后分享一个我目前最依赖的实践我给它起名叫预产检——每次在模型真正调用 Skill 之前先用一小段示例文本对执行模块做一轮冒烟测试。具体做法是在注册 Skill 的时候附带一组内置测试用例注册完成后由框架自动跑一遍测试通过才把它标记为可用。这样能在项目启动阶段就发现大量低级问题比如字段名拼写错误、依赖缺失、路径找不到等等。这个机制做起来成本其实很低但是在做交付时候的价值很高尤其是那些要给同事或客户使用的项目它能直接把运行时炸掉的概率压到非常低。如果你的框架不支持自动预跑你也可以在注册脚本里手动调用一次执行函数的测试模式逻辑是一样的。不要小看这一步我非常确定地说很多看起来像模型很笨的问题其实根源是执行模块里一个低级异常被模型错误地绕过去了。6. 从一场比赛项目中得到的一点经验我在一个模拟项目上完整用过自定义 Skill 这套方案。项目的任务是做一个智能面试官需要在对话中识别候选人的回答并实时给出评估建议。表面上看这活儿直接让模型判断就行但真正落地时发现模型对评分维度和记录结构的处理非常不稳定。我最后把整个行为拆成两个自定义 Skill一个负责按预设维度解析面试对话并输出结构化评分另一个负责将评分结果换算成推荐建议。第一个 Skill 的代码做全部解析和打分计算第二个 Skill 再把数据映射成语义化建议最后由模型做人性化总结。整体跑下来打分一致性大幅提升回复质量也稳定了不止一个档次。这个项目的经验让我对自定义 Skill 有了一个更务实理解模型负责说什么代码负责怎么算。大部分你看上去是智能的事情其实底层都是稳定的规则加计算真正属于模型的只是一层表达层。把这一层边界把握好项目质量就能上去一大截而且可测试、可维护、可迁移。自定义 Skill 的后续扩展空间也很大你可以基于这个模式继续做定时触发版本、多模型协同版本甚至把它改造成一个跨项目通用的公共组件。做这些东西并不需要更高的魔法就是一步一步把确定性强的东西从模型手里接过来放到代码里。希望这篇能帮你少踩几个坑。
1. 自定义 Skill 的价值与设计思路我一直觉得OpenSkills 这类框架对 Skill 的定义其实和一个团队招人非常像。你看一个新人进来首先得知道他是干什么的、擅长什么、在什么场景下能帮上忙。框架里的 Skill 也一样它本质上是给智能体配置的一种专业能力外包服务——把我们平时做业务时重复调用模型、处理文本、转格式、调接口这类固定动作封装成一个模型可以主动识别并调用的独立模块。这是一个非常聪明的设计模型不擅长的事情交给代码去做代码不擅长理解意图的地方交给模型去判断二者各管一段。这一篇我们实操的是自定义 Skill。很多人会用框架自带的 Skill但一说到自己写就觉得门槛很高。其实自定义 Skill 的核心没有那么玄乎主要就三件事第一搞清楚 Skill 这个外壳长得什么样第二把输入输出的结构设计好第三把什么时候该触发这个边界条件写清楚。只要把这三件事做扎实你写出来的 Skill 在项目里就是妥妥的外挂。而且我可以负责任地说自己写 Skill 的收益通常远超调现成的因为业务里最核心的专属逻辑往往就在这些别人替不了你的流程里。这个能力适合谁简单来说只要你手头有一个用 OpenSkills 搭起来的智能体应用不管是做内容处理、数据清洗还是对接内部接口都有必要把高频重复的环节抽成自定义 Skill。它能帮你把一个会聊天的模型变成一个能干活的执行者。这篇文章我会从设计、结构、代码实现到问题排查完整走一遍代码也会给出可以直接抄作业的版本你照着跑一遍就能看出效果。2. 自定义 Skill 的核心结构与实现机制2.1 Skill 的三个关键组成部分在动手写之前先把 Skill 的骨架子摸清楚。OpenSkills 框架里一个 Skill 的常规组成可以归纳为三个部分元信息描述、上下文约束和执行模块。第一部分是元信息描述。这一块负责告诉智能体这个 Skill 叫什么、是干什么用的、什么情况下你应该想起来用它。它相当于一份使用说明书加上触发条件清单。Description 写得好不好直接影响模型能不能在恰当的时候把 Skill 捞出来。如果你写得过于宽泛模型会在不该调用的场景下强行调用写得过于狭窄模型又会视而不见。这中间的度是第一个要磨的细节。第二部分是上下文约束。这里主要定义 Skill 接收什么格式的数据需要哪些前置信息。比如一个文本摘要的 Skill它需要接收原文、语言偏好、摘要长度上限一个定时任务提醒的 Skill它可能需要接收截止时间、任务描述和通知渠道。把输入边界定义清楚模型就不会把乱七八糟的东西塞给你。第三部分是执行模块。这是真正干活的代码。它接收模型传过来的结构化参数执行具体的逻辑最后把结果返回到对话流里。这里的返回结果最好是一个干净的结构化数据方便模型基于结果做进一步的解释或追问。我之前见过有人在执行模块里返回一大堆日志和调试信息结果模型直接被带偏在回答中反复提及这些无关细节非常影响体验。2.2 Skill 被调用的完整生命周期理解 Skill 什么时候被调用、调用过程中发生了什么比单纯拼代码更关键。用一句话概括整个生命周期模型先做意图判断再按 Skill 定义拼参数拼好参数后调用执行模块拿到结果后整理成回复。详细拆开看一次完整的 Skill 调用是这样一个链路意图识别阶段。用户发出请求模型先基于当前对话历史比对候选 Skill 的元信息描述判断当前这个问题是不是该用某个 Skill 来做。这一步完全依赖描述写得好不好。参数组装阶段。模型根据用户的原始输入提取出 Skill 定义里要求的字段按照输入约束把它们拼装起来。这一步最容易出错比如用户说把这篇报道总结成 200 字摘要模型可能把200字识别成摘要长度也可能理解成摘要语言完全取决于字段名称和描述是否足够生动具体。调用执行阶段。框架将组装好的结构化参数传给执行代码代码运行后返回一个结果对象。这个阶段耗时主要看你的逻辑复杂度——如果是轻量文本处理基本是毫秒级如果涉及外部接口调用就要看网络状况了。结果回填阶段。模型拿到执行结果将其组织成自然语言回复如果结果里带数据表或 JSON模型也能做进一步解析和总结。我在实际项目里看到的绝大多数自定义 Skill 问题都出在第一和第二阶段不是代码跑不起来而是模型压根没在正确的时机调用或者传参传得七扭八歪。这就引出一个技巧Skill 的描述文档里建议用当用户需要……时这种条件句来引导对比干巴巴的功能描述命中率能高出不少。2.3 为什么说描述即代码很多开发者把精力全放在执行函数上对描述文本敷衍了事这是一个非常普遍的误区。我甚至敢说在 Skill 开发里描述文本的重要性和代码是五五开有时候甚至更高。模型就像一个阅读能力极强但社会经验为零的新员工它只能靠你写的说明去理解工具用在何处。你描述得越贴近真实使用语境它就越能在关键时刻做出准确选择。另外描述文本里还应包含明确的边界提示比如本 Skill 不适用于……场景当用户提供的信息不足时应要求补充……这种约束性语句。不要小看这里模型对大段自由文本里的否定句和条件句其实非常敏感这些内容能明显降低误调用率。这算是我自己总结的一个小偏方写描述时多花十分钟后面能省掉大量反复调试。3. 实操从零实现一个可落地的自定义 Skill3.1 选定一个实用的练手场景为了把流程讲透我挑一个非常常见、几乎每个做内容或数据的人都用得上场景写一个长文本结构化提取的 Skill。这个 Skill 接收一段长篇文本自动提取其中的核心信息比如主题、关键人物、时间线、行动项最终输出一个结构化的 Markdown 报告。选这个场景有两个理由第一它逻辑清晰前中后期都好验证第二它对输入文本没有严苛格式要求方便你自己捏造几段测试数据跑通全流程。在动手前要先把这个 Skill 的边界想好。它做什么——提取信息并按固定结构输出它不做什么——不做情感分析、不做语言翻译、不做摘要改写。这个边界在后期写描述时会统一体现。3.2 Skill 定义文件怎么写在 OpenSkills 框架里一个 Skill 通常用一个目录来组织目录里包括一个描述文件和一个执行脚本。我们先用一个名为skill_info.md的描述文件来说明这个文件名不同版本稍有差异但语义一致。内容可以直接套用下面这个模板--- name: text_info_extractor description: 从用户提供的长文本中提取核心信息输出结构化 Markdown 报告。当用户需要整理会议纪要、快速了解一篇文章要点、提取访谈记录中的行动项时调用该技能。 input: - name: source_text type: string required: true description: 需要提取信息的原始文本建议直接提供全文不要提前压缩。 - name: language type: string required: false default: chinese description: 输出报告的语言支持 chinese 和 english默认为 chinese。 --- # 使用说明 使用该技能时应直接将原始文本完整传入不要对文本进行截断或改写。若用户提供的文本明显不足无法提取出足够信息则提示用户补充更多原文。 # 输出要求 以 Markdown 格式输出以下结构 1. 主题概述用三到五句话概括文本核心内容 2. 关键人物/角色列出文中重要的人或组织简要说明角色 3. 时间线按时间顺序排列的重要事件 4. 行动项若文本中提到了待办事项列为可执行清单 5. 疑问与缺失信息列出文本中未交代清楚的细节供后续追问这个模板看起来简单但每一个字段都是有明确目的的。name是全局唯一标识框架靠它把 Skill 注册到可调用列表里description是触发匹配的核心依据我特意在开头就写了提取核心信息然后在后面补了三个高频触发场景input清单则规范了参数结构尤其要把语言设置成可选项并给默认值这样既能减少模型传参的出错率又不影响主流程输出。3.3 执行模块的实现与参数绑定描述文件定了规范真正的处理逻辑放在执行脚本里。以 Python 为例一个最小可用的执行模块长这样import re from datetime import datetime def extract_dates(text): # 简易日期模式匹配支持 2025-02-13、2025年2月13日 等常见格式 date_patterns [ r(\d{4})[-/年](\d{1,2})[-/月](\d{1,2})日?, r(\d{1,2})月(\d{1,2})日 ] dates [] for pattern in date_patterns: matches re.findall(pattern, text) dates.extend(matches) return dates def main(source_text: str, language: str chinese) - str: key_dates extract_dates(source_text) # 这里可以继续补充实体识别、关键词提取等逻辑 result_sections { source_length: len(source_text), dates_found: key_dates, preview: source_text[:200] } if language english: return render_english_report(result_sections) return render_chinese_report(result_sections) def render_chinese_report(data) - str: lines [## 提取报告, ] lines.append(f- 原文长度{data[source_length]} 字) lines.append(f- 识别到的日期{, .join(data[dates_found]) if data[dates_found] else 未识别到明确日期}) lines.append() lines.append(### 原文预览) lines.append(data[preview].replace(\n, )) return \n.join(lines) def render_english_report(data) - str: status No explicit dates found if not data[dates_found] else , .join(data[dates_found]) lines [## Extracted Report, ] lines.append(f- Source length: {data[source_length]} characters) lines.append(f- Dates detected: {status}) lines.append() lines.append(### Preview) lines.append(data[preview].replace(\n, )) return \n.join(lines)在这个示例里我用正则做日期提取只是一个演示真正的核心是让你看清楚参数进入执行模块的流向。source_text和language这两个字段会在运行时自动绑定用户在对话里提供的信息用户不需要关心这个函数叫什么、文件在哪只需要描述清楚需求即可。3.4 注册 Skill 到项目并触发验证执行模块写完还需要把 Skill 挂载到主项目上。挂载步骤通常在项目的配置入口里完成。这样理解主工程像是一个 App StoreSkill 是一个个 App你把它上架了智能体运行时才能检索到它。在 OpenSkills 里挂载通常是这样一段代码from open_skills import SkillRegistry, load_skill_from_directory registry SkillRegistry() skill load_skill_from_directory(skills/text_info_extractor) registry.register(skill)注册之后你可以直接用一条模拟对话来验证触发流程。比如在调试控制台里发一句话下面这段文字是今天上午的会议记录请你帮我提取一下核心要点和待办事项。段落内容见附件。模型在收到这条消息后会对候选 Skill 做意图匹配这个新挂载的 Skill 会出现在候选列表里并且因为描述命中而被选中进而走完参数组装、执行、回填流程。验证时的关键观察点是模型是否真的把完整文本传给了source_text而不是只传了一小段截取内容。如果模型总是传不完整一种有效的调整策略是在描述里增加一个强调调用时必须完整传入原始文本不得截断或自行概括原文。3.5 增加一层前置校验来提升健壮性在实际业务中模型传过来的参数有时候会很不规范比如source_text字段是空字符串language字段传了英文而不是english。与其指望模型永远不出错不如在自己的代码里加一层防御机制。我在生产项目里习惯给每个 Skill 的执行入口加一个参数校验函数逻辑大概是这样def validate_params(source_text: str, language: str): if not source_text or len(source_text.strip()) 20: response 提供的文本过短或为空无法提取有效信息请补充更完整的原文。 return False, response normalized_lang language.lower().strip() if normalized_lang in (chinese, 中文, zh, cn): normalized_lang chinese elif normalized_lang in (english, 英文, en, eng): normalized_lang english else: normalized_lang chinese return True, normalized_lang这一层的作用是兜底它不会影响正常路径的执行效率但能显著提高用户对 Skill 的感知质量。模型传参不规范时至少不会直接抛异常给用户而是能优雅地返回一条提示。这类防御性设计在你面向非技术用户部署时尤其重要。4. 自定义 Skill 的进阶设计上下文、依赖与执行边界4.1 上下文感知让 Skill 不只是无状态工具基础版 Skill 可以理解成一个无状态函数独立运行完就直接返回结果。但实际业务场景里用户的输入往往依赖更完整的上下文。比如你写了一个周报生成的 Skill用户直接说汇报本周内容模型虽然在意图识别阶段能匹配到但因为消息里没有具体的工作事项生成的周报就会非常空泛。这种时候与其让 Skill 硬着头皮输出废话不如把上下文不足检测写进技能里。在定义文件里可以声明一个前置检查项如果用户消息中缺乏必要信息则要求模型先追问而不是急于输出。这个处理逻辑可以写进描述文件的使用说明中也可以在执行模块里做成一个可选的require_context开关。我在实践中把两者结合起来描述负责提示模型信息不足时反问代码负责对输入再次校验双保险。4.2 依赖隔离与轻量打包自定义 Skill 最大的隐患之一就是依赖管理失控。每个 Skill 如果都往全局环境里装一堆包最终项目会变得非常臃肿甚至出现两个 Skill 依赖同一个包但版本冲突的尴尬局面。我的习惯做法是给每个 Skill 创建独立的虚拟环境依赖清单并在挂载时声明它依赖哪些第三方库。框架如果支持依赖声明机制就明确写进 Skill 目录下的依赖文件里这样做的好处是后续如果某个技能废弃清理时也能连依赖一并移除不会留下垃圾。另外我还是建议尽量少依赖重型框架能用标准库解决的就不要拉第三方包。就以文本提取为例re能处理批量匹配标准库的 JSON 和字符串方法能覆盖 80% 的格式化需求。轻依赖意味着更快的加载速度和更少的兼容性问题在异构部署环境中尤其划算。4.3 多步骤 Skill如何衔接后续动作有些任务只调一次 Skill 是不够的。举个例子一个竞品动态追踪的技能它可能需要先抓取网页然后抽取关键信息再和昨天的结果做对比最后生成报告。这一整条链路如果拆成三个 Skill让模型自己判断每一步去调哪个会非常不可控。更好的方案是定义成一个复合 Skill内部按顺序执行多个处理步骤只在最后给模型返回一个总结性的执行结果。我见过不少框架允许 Skill 内部做多阶段处理然后通过一个统一的入口暴露给模型。这个设计能显著降低模型的决策负担。它的本质是把确定性任务全部压制在代码层只把真正的意图判断留在模型层。这样既保留了大模型的灵活性又把业务逻辑的确定性牢牢握在工程手里。4.4 与外部接口结合时的超时控制现实中不少自定义 Skill 会涉及调用第三方 API。这个时候有一个专门坑很多的地方超时和异常处理。模型在聊天窗口里等着如果底层 API 卡了 30 秒没返回对话体验基本就毁了。每一次对外部接口的调用都要显式设置超时时间并准备降级方案。比如你在 Skill 里调用一个外部翻译接口就要考虑如果接口失败是返回一个翻译服务暂时不可用的提示还是回退到本地简易词典翻译这些逻辑虽然不是模型能看到的但它最终会变成用户体验的一部分。我在实际项目里就把超时时间设得比较短宁可偶尔失败重试也不愿意让用户对着一个转圈的小图标发呆。5. 常见问题与排查技巧实录5.1 问题速查表我把自定义 Skill 开发中最常遇到的几个问题整理成一张速查表方便你对照排查问题现象根本原因处理方法模型从不在对话中调用这个 Skill描述文件过于模糊或触发场景覆盖率太低重写描述增加具体触发场景使用当用户需要……时句式Skill 被调用但参数总是缺失输入字段描述不清晰或 required 标记不正确在描述中补充字段说明并强调必须提供完整字段模型返回的结果格式混乱输出规范未写清或执行模块返回自由文本让执行模块严格返回结构化数据并在描述里明确输出格式Skill 执行出错对话就中断执行函数缺少异常捕获在 main 入口包一层 try-except异常时返回友好提示项目加载后找不到新写的 Skill路径不对或未重新初始化注册表检查挂载路径确认注册函数执行顺序同一段文本被多个 Skill 重复处理边界重叠描述中缺乏排除条件在描述中明确该技能不处理……的限制条件5.2 排查示例模型假装调用但没真正走通这里分享一次真实的排查过程。有一次我写了一个数据清洗的 Skill发现对话里模型会回复好的我帮你清洗了数据但返回的结果明显不对。起初我以为是参数传错后来把日志打开才发现模型根本没有调用 Skill它是在空想。为什么会这样因为我把 Skill 的名字和描述写得像一个普通对话建议模型觉得凭自己的常识就能回答不需要调工具。解决方式是把描述改成更工具化的表达明确说明这是一个数据处理工具必须调用后才能得到准确结果同时把执行模块的返回结果通过框架的提示系统回传让模型意识到外部工具输出和自身生成内容是两码事。这个问题其实非常典型尤其在那些模型知识覆盖较全的领域里容易发生。工具描述与模型能力边界一旦模糊模型就会自作聪明。5.3 调试技巧如何用最小样本定位问题自定义 Skill 的调试往往没有现成的交互式断点那么方便我自己常用的手法是把执行函数做成可独立运行的脚本在脚本里用写死的参数调用核心逻辑。这样做有几个好处第一可以绕过整个模型链路快速判断是不是自己代码的逻辑问题第二方便做回归测试改完一个地方直接云跑一遍旧用例防止副作用。在独立调试时我会构造三类测试输入正常完整参数、缺字段参数、超长文本参数。这三种类型基本能覆盖绝大部分执行崩溃的场景。等代码稳了再挂回模型做端到端验证这时候如果还出问题就可以把锅精准地甩给意图识别或参数组装而不是去怀疑底层逻辑。5.4 独门避坑技巧给 Skill 加预产检最后分享一个我目前最依赖的实践我给它起名叫预产检——每次在模型真正调用 Skill 之前先用一小段示例文本对执行模块做一轮冒烟测试。具体做法是在注册 Skill 的时候附带一组内置测试用例注册完成后由框架自动跑一遍测试通过才把它标记为可用。这样能在项目启动阶段就发现大量低级问题比如字段名拼写错误、依赖缺失、路径找不到等等。这个机制做起来成本其实很低但是在做交付时候的价值很高尤其是那些要给同事或客户使用的项目它能直接把运行时炸掉的概率压到非常低。如果你的框架不支持自动预跑你也可以在注册脚本里手动调用一次执行函数的测试模式逻辑是一样的。不要小看这一步我非常确定地说很多看起来像模型很笨的问题其实根源是执行模块里一个低级异常被模型错误地绕过去了。6. 从一场比赛项目中得到的一点经验我在一个模拟项目上完整用过自定义 Skill 这套方案。项目的任务是做一个智能面试官需要在对话中识别候选人的回答并实时给出评估建议。表面上看这活儿直接让模型判断就行但真正落地时发现模型对评分维度和记录结构的处理非常不稳定。我最后把整个行为拆成两个自定义 Skill一个负责按预设维度解析面试对话并输出结构化评分另一个负责将评分结果换算成推荐建议。第一个 Skill 的代码做全部解析和打分计算第二个 Skill 再把数据映射成语义化建议最后由模型做人性化总结。整体跑下来打分一致性大幅提升回复质量也稳定了不止一个档次。这个项目的经验让我对自定义 Skill 有了一个更务实理解模型负责说什么代码负责怎么算。大部分你看上去是智能的事情其实底层都是稳定的规则加计算真正属于模型的只是一层表达层。把这一层边界把握好项目质量就能上去一大截而且可测试、可维护、可迁移。自定义 Skill 的后续扩展空间也很大你可以基于这个模式继续做定时触发版本、多模型协同版本甚至把它改造成一个跨项目通用的公共组件。做这些东西并不需要更高的魔法就是一步一步把确定性强的东西从模型手里接过来放到代码里。希望这篇能帮你少踩几个坑。
