聊个最近社区里讨论比较多的话题——如何在WorkBuddy里编写一个能真正用起来的技能Skill。我看了不少人在社区发帖问Skill到底是什么和普通对话提示词有什么区别还有人照着模板写了一个Skill结果装上去完全不触发也不知道从哪里排查。这些问题我早期都踩过今天把整个流程从头到尾梳理一遍从核心概念到文件结构从第一个能跑的Skill到调试发布一次聊透。WorkBuddy里的Skill本质上就是给智能助手装上一个可复用的能力模块。它不是一个普通提示词而是一个包含参数定义、执行逻辑、返回格式和触发条件的完整程序单元。写Skill的人不需要懂复杂的底层架构但需要理解它的运行机制——Skill怎么被触发、参数怎么传进去、结果怎么返回来这三件事搞清楚了剩下的就是具体场景的逻辑实现。这篇内容适合三类人一是想在WorkBuddy里实现个性化功能的新手二是已经在写Skill但总遇到触发或格式问题的进阶用户三是想把自己做的Skill发布到社区赚取认可和反馈的贡献者。我会用大量实际示例和踩坑记录来说明尽量让每个环节都能直接照着做。注意文中涉及的平台路径和界面名称可能随版本迭代有调整但核心逻辑和文件结构是通用的。1. 理解Skill的核心概念与运行机制1.1 Skill到底是什么一句话概括Skill是智能助手的技能插件它让你的助手不只是“会聊天”而是“会办事”。拿生活场景来类比。你雇了一个全能助理他什么都会但如果你不对他说清楚你要什么、用什么方式给他、期望他怎么做他就只能泛泛而谈。Skill就像是给这个助理写的一本操作手册什么情况下触发他、需要哪些信息、按什么步骤执行、最后怎么把结果汇报给你。在WorkBuddy中一个Skill由以下部分组成触发条件trigger定义了什么时候激活这个技能可能是关键词、意图匹配或特定参数组合。参数定义parameters说明这个技能需要哪些输入每个输入的格式、默认值、取值范围。执行逻辑action真正干活的代码或调用逻辑负责处理参数、产出结果。返回结构response定义结果返回给用户时的格式方便下游继续处理。理解这一点很重要Skill不是替代对话而是在对话流程中嵌入可执行逻辑。它解决的问题是“让助手从说到做”并且让这个“做”的过程是可复用、可分享、可迭代的。1.2 Skill的工作流程我画了一条完整的工作链路描述形式不用图帮你把每个环节对应到实际开发中用户输入一段话 → WorkBuddy平台的解析层先做意图识别 → 命中某个Skill的触发条件后进入该Skill的上下文 → 从用户输入中抽取参数 → 执行定义的逻辑 → 生成结构化返回 → 平台把返回渲染成用户可读的内容。这里容易忽略的细节是参数抽取不一定发生在执行逻辑内部。WorkBuddy的Skill机制允许你声明一套抽取规则平台解析层会先把用户原话里的信息填进参数槽位再交给逻辑层。这意味着即使你的执行逻辑只是简单输出一段文本只要参数定义完善Skill依然能适配千变万化的用户说法。举个例子。你想做一个“设置提醒”的Skill用户可能说“明天下午3点提醒我开会”也可能说“15分钟后叫我喝水”还可能说“每天晚上10点提醒我打卡”。这三句话语义差异很大但都可以抽取出“时间”和“事项”两个参数。参数抽取规则定义得好不好直接决定Skill的泛化能力。1.3 为什么用Skill而不是直接写死逻辑有人会问我把这些判断逻辑直接写进Prompt让模型每次动态决定不就行了吗为什么非要单独搞一个Skill我用实际感受来回答。早期我也试着在System Prompt里堆规则告诉模型“当用户提到提醒时就做X当用户提到计算时就做Y”结果有两个问题非常折磨人第一Prompt越长模型对规则的遵循度越不稳定。你加了10条规则它可能在处理第1条时表现优秀处理第7条时就忘掉了或者把两条冲突规则混合执行。第二所有逻辑混在一个代码块里每次要改一个功能都得小心翼翼生怕影响其他功能。Skill的模块化把这些问题从根本上解决。每个Skill是独立的单元触发它时才被装载参数和执行逻辑都是隔离的。如果你觉得某个Skill不好用可以直接替换它其他功能完全不受影响。这就好比你的工具箱里每个工具都有独立的卡槽不会因为换一把螺丝刀而把锤子弄坏。另外Skill天然适合共享。WorkBuddy社区的Skill是带版本、带说明、带评分体系的你把Skill发布出去别人导入就能用还能基于你的版本进行二次改进。这种协作方式是从零搭Prompt很难实现的。2. 开发环境准备与Skill文件结构2.1 环境准备进入WorkBuddy社区后在个人工作台找到“技能开发”入口就能创建和管理Skill。首次创建需要完成两个前置准备一是绑定你的开发者身份并启用API访问权限二是在本机准备一个可用的编辑器。我个人建议不要在平台网页上直接编写大量代码体验不太好。推荐把Skill项目克隆到本地用代码编辑器编辑然后用平台提供的命令行工具或Webhook方式同步测试。这样你可以用上本地的版本管理、代码高亮、语法检查效率会高很多。在正式动手前你还需要理解一个核心原则Skill是一个“声明实现”的结构。声明描述这个Skill是干什么的给平台解析层看实现描述具体怎么做给执行层看。两件事分开职责清晰这也是为什么Skill目录下会有不同类型的文件。具体环境要求如下操作系统无特定限制但命令行工具需要能正常工作。语言运行时环境如果Skill逻辑用Python编写需要对应版本解释器。API密钥与访问令牌用于调试时模拟请求。2.2 标准目录结构拆解一个规范的Skill目录结构通常如下my-skill/ ├── manifest.yaml ├── skill/ │ ├── __init__.py │ ├── skill.py │ ├── prompts/ │ │ ├── intent.md │ │ └── extract.md │ └── resources/ │ └── data.json ├── examples/ │ └── sample-inputs.json └── README.md逐个说下每个文件的职责。manifest.yaml是这个Skill的身份证所有元信息都在里面名称、版本、作者、描述、触发关键词、参数声明、权限需求。平台的Skill市场会读取这个文件让用户看到这是什么。manifest写得不规范可能导致Skill无法被索引。skill/skill.py是执行逻辑接收已经解析好的参数进行处理并返回结果。这里可以调用第三方库、发起网络请求、读取本地文件等。整个Skill的核心价值基本都在这个文件里。skill/prompts/目录存放提示词模板。有人会觉得奇怪Skill不是代替提示词吗怎么还要提示词其实Skill的内部逻辑可能需要借助大模型来完成某个子任务比如从用户输入中提取非结构化信息、生成一段自然语言回复。这些子任务的提示词可以单独放在这里便于调试和替换。examples/目录放示例输入方便自己测试和用户理解。README.md是人读的说明写清楚功能、使用方式、注意事项。2.3 编写前的设计思路先画逻辑再写代码很多新手上来就打开编辑器写代码写到一半发现触发条件覆盖不全或者返回格式不符合预期又回头改结构来回折腾。我的经验是先花20到30分钟做设计画个简单的“输入-处理-输出”流程分析明确以下问题这个Skill解决什么问题用户是谁触发条件怎么定是关键词、正则、还是意图匹配需要哪些参数哪些必填、哪些可选边界值是什么执行逻辑分成几步有没有分支返回格式是什么用户怎么理解异常情况怎么处理参数缺失、调用失败、超时把这六个问题写在纸上或文档里再进行编码你会发现写代码的过程就是照着设计稿填内容不纠结。我通常还会写一段伪代码来帮助梳理逻辑。比如IF 用户输入命中提醒意图 THEN 抽取时间参数 若时间参数为空 反问用户期望的时间 否则 创建提醒 返回确认消息 END这段伪代码直接对应后面实际代码里的主体结构调试的时候思路非常清晰。3. 手写第一个核心Skill筛选优质文章纸上谈兵说够了直接进入实操。我挑一个适合练手的场景来演示编写一个帮助用户筛选优质技术文章的Skill。它的功能是给定一个文章列表根据标题、摘要和阅读时长筛选出值得深读的文章。这个选例有三个考虑功能独立不依赖外部服务逻辑有一定层次涉及数据处理和条件判断结果易于验证你能直观看到Skill是否正常工作。3.1 定义manifest配置创建项目目录后先写manifest.yamlname: article-filter version: 1.0.0 description: 根据标题、摘要和阅读时长筛选值得深读的技术文章 author: community-dev trigger: keywords: - filter - 筛选 - quality-article intent_id: filter_article_intent parameters: articles: type: array required: true description: 待筛选的文章列表 min_rating: type: float required: false default: 4.0 description: 最低质量评分 max_read_minutes: type: int required: false default: 20 description: 最长可接受阅读时长分钟 permissions: network_access: false file_write: false这里有几个值得展开的点。触发关键词trigger这一段我写入了三个关键词和一个意图ID。关键词是给平台解析层做个快速匹配但是关键词匹配不太可靠所以还加了一个intent_id如果平台支持语义理解链路可以结合使用。注意关键词不是越多越好我见过有人写了几十个同义词结果产生大量误触发反而不如三到五个精准词加一个意图ID效果好。参数定义里articles类型是array这表示用户输入需要给到一个数组结构。但这里有个细节如果用户只是贴了一段文章文本而非结构化的数组参数解析层可能无法正确填入。为了兼容这种情况通常我们会用一个简单的提示词子任务把用户输入转换为标准JSON格式再进行筛选。这个过程我用下面一个章节来说明。3.2 执行逻辑实现接下来是核心代码放在skill/skill.py中。这里我直接给出一版相对完整、带注释的实现import json from typing import Any, Dict, List, Optional DEFAULT_MIN_RATING 4.0 DEFAULT_MAX_READ_MINUTES 20 def list_to_text(items: List[Any]) - str: 将列表结构转换为适合模型处理的文本形式 return \n.join( f标题{item.get(title, 未知)} f摘要{item.get(summary, 无)} f评级{item.get(rating, 0)} f阅读时长{item.get(read_minutes, 0)}分钟 for item in items ) def extract_articles_from_text(text: str) - List[Dict[str, Any]]: 当输入是非结构化文本时先将其转换为结构化JSON数组 prompt f 请从下面的文章中提取结构化信息以JSON数组格式返回。 每个元素包含字段 title、summary、rating、read_minutes。 只输出JSON不要其他解释文字。 输入内容 {text[:3000]} # 这里实际调用平台提供的大模型子任务能力获取返回的JSON # 假设存在一个 call_model_api 函数来提供这个能力 response_text call_model_api(prompt) try: articles json.loads(response_text) if not isinstance(articles, list): raise ValueError(返回结果不是数组) return articles except Exception: return [] def filter_articles(params: Dict[str, Any]) - Dict[str, Any]: 筛选文章的核心主逻辑。 接收平台解析层传过来的参数返回结构化结果。 raw params.get(articles) if isinstance(raw, str): articles extract_articles_from_text(raw) elif isinstance(raw, list): articles raw else: return { status: error, message: articles 参数必须是列表或文本 } min_rating params.get(min_rating, DEFAULT_MIN_RATING) max_read_minutes params.get(max_read_minutes, DEFAULT_MAX_READ_MINUTES) qualified [] for idx, article in enumerate(articles): try: rating float(article.get(rating, 0)) read_minutes int(article.get(read_minutes, 999)) except (TypeError, ValueError): continue if rating min_rating and read_minutes max_read_minutes: qualified.append({ index: idx 1, title: article.get(title, 未知标题), rating: rating, read_minutes: read_minutes, reason: f评分{rating}达标预计阅读{read_minutes}分钟 }) return { status: success, matched_count: len(qualified), matched_articles: qualified }逐段解释这段代码的关键逻辑。开头两个常量用于默认值兜底当用户未显式传入参数时使用默认值替代。这是一个很重要的容错设计因为平台解析层偶尔会漏掉某些可选参数执行逻辑必须有默认值处理。list_to_text和extract_articles_from_text两个函数解决“参数形态不一致”的问题。当用户给的是结构化数组直接走过滤用户只给了一段文章文本就先用大模型做一个抽取和转换再进入过滤环节。这就做到了结构化输入和非结构化输入都兼容。filter_articles是主入口。第一步检查articles参数的类型如果是字符串就调用抽取函数如果是列表就直接用两者都不是就返回错误信息。注意这里的错误返回也遵循结构化格式这是为了让平台能正确渲染错误提示而不是简单地抛个异常。过滤循环里有一个细节我把每个不达标的文章都进行continue不把它加进结果同时对rating和read_minutes做了类型转换转换失败则跳过。这个“宁可跳过也不崩溃”的设计在Skill开发里非常关键。reason字段是给用户看的简要说明为什么推荐这篇文章。这样返回结果不只是数据还带着可读性用户体验会好很多。3.3 返回结构设计与提示词模板编写平台会读取函数返回的字典结构根据字段内容渲染成不同形态的卡片或文本。我把返回结构设计成三种状态成功且有匹配、成功但无匹配、参数错误。成功且有匹配时返回matched_count和matched_articles数组平台端可以展示成文章列表卡片。无匹配时返回matched_count: 0和一句友好提示文案。参数错误时返回status: error和详细错误信息。这部分的提示词模板我放在skill/prompts/extract.md里内容大致如下你是一个信息抽取助手。用户会给你一段包含若干文章信息的文本你需要抽取以下字段 - title文章标题 - summary一句话摘要 - rating文章质量评分0到5之间的数字保留一位小数 - read_minutes预计阅读时长整数 输出要求 - 严格输出JSON数组不要包含任何额外文字 - 如果某项信息缺失使用 null 填充 - 最多抽取10篇文章这个提示词有个细节值得说明我明确写了“如果某项信息缺失使用 null 填充”而不是“留空”。因为JSON解析时null才能正确转为Python的None空字符串可能导致后续类型转换失败。4. 测试、调试方法与常见问题排查4.1 本地模拟测试拿到一个可以跑的Skill后第一件事不是在平台上点击启用而是先在本地模拟测试。我自己会在本地写一个简单的测试脚本模拟平台解析层传入不同参数的情况。# 模拟测试 test_cases [ { articles: [ {title: A, summary: 深入介绍, rating: 4.5, read_minutes: 15}, {title: B, summary: 基础入门, rating: 3.2, read_minutes: 30}, {title: C, summary: 实战经验, rating: 4.8, read_minutes: 45}, ], min_rating: 4.0, max_read_minutes: 20, }, { articles: 标题深度学习入门指南摘要适合初学者评分3.5阅读时长25分钟。标题模型优化实战摘要深入内存优化技巧评分4.7阅读时长18分钟。, }, ] for case in test_cases: result filter_articles(case) print(json.dumps(result, ensure_asciiFalse, indent2))跑完测试后检查以下几点结构化输入时过滤条件是否正确非结构化文本输入时抽取转换是否成功过滤后没有匹配项时返回是否友好传入异常类型比如数字而不是列表时是否返回error而不是抛异常这几类情况覆盖全面后再把Skill在平台测试环境跑一遍通常会顺利很多。4.2 常见问题排查速查表我在社区和交流群里看了很多人的问题整理一个排查速查表你遇到类似问题时可以直接对号入座。现象可能原因排查思路Skill根本没有被触发关键词不匹配、意图定义不够精准检查manifest里的触发条件试试输入包含确切关键词触发后返回参数缺失用户输入缺少某些参数或抽取规则未定义在参数定义中增加默认值或者增加一条反问逻辑非结构化文本总是解析失败JSON解析异常、大模型返回了多余文字在提示词中强调“只输出JSON”并在代码里做健壮性容错过滤结果为空阈值设置不合理或者数据本身不达标先降低阈值测试确认逻辑链路是否正常耗时太长非结构化文本长度过大调用模型超时截断输入文本限制最长处理长度依赖库找不到运行时环境未安装对应依赖在Skill配置文件里声明依赖并确认运行环境版本排查时的核心思路是“逐层拆解”先确认触发层有没有问题再确认参数层再确认逻辑层最后确认返回层。不要一上来就怀疑代码逻辑很多时候问题出现在上游的触发和参数抽取环节。4.3 平台端联调与日志观察本地测试通过后在WorkBuddy平台创建测试会话导入Skill输入预置测试用例观察返回结果。平台会提供一份执行日志记录每一层的输入输出包括触发决策、参数输出、逻辑执行结果和耗时。联调过程中有一个很有意思的场景在测试环境Skill工作正常但到正式环境就失效了。这个问题我遇到过几次原因通常是正式环境的权限配置更严格。比如我这个文章筛选Skill只涉及本地数据处理不涉及网络访问但如果你在代码里隐藏了一些网络请求逻辑比如加载远程数据正式环境下会因为权限不足而静默失败。所以务必在manifest中准确声明权限并且在测试时主动测试“最小权限”条件下的行为。还有一个容易被忽略的点返回结果的超时限制。如果Skill的某个分支需要调用外部大模型子任务而这个子任务耗时不稳定可能超出平台限制。我的建议是凡是耗时操作尽量设置一个内部超时上限超时后快速返回一个兜底应答而不是让用户一直等待。5. 进阶优化与发布到社区5.1 让Skill更聪明引入上下文状态基础Skill已经能完成单次任务但很多实际场景需要多轮交互。比如用户说“帮我筛选文章”你反问“请提供文章内容”用户分了几条消息发过来怎么把这些散落的片段拼起来这就要用到WorkBuddy的上下文记忆机制。在Skill的执行逻辑中可以把未处理完的中间状态写到上下文中。当用户再次发起含相关信息的输入时平台会把历史上下文合并传入Skill可以从上下文中取回上次存下的部分数据完成信息拼接。我的实现思路是在参数不完整时不直接返回错误而是返回一个“询问信息”的结构同时在上下文中保留临时数据。下次再触发时先读取上下文合并新参数再执行逻辑。这样设计的好处是用户觉得你在“连续对话”而不是在“状态机里跳转”。5.2 权限边界与安全设计Skill越做越复杂时安全很重要。我给Skill开发者的权限设计提几条实用建议最小权限原则在manifest中只声明需要的能力不需要网络访问就明确关闭。输入校验任何用户传来的参数在执行前都做类型、范围、枚举校验。输出清理如果Skill会生成文本要过滤掉可能造成注入风险的特殊字符。资源限制限制最大输入长度、最大输出长度、最大循环次数。这四条是底线不是为了多数用户而是为了守护少数恶意输入。Skill一旦发布到社区被别人导入使用你就对你的代码负有责任。写得保守一点不容易出问题。5.3 发布与持续迭代发布到社区之前先把README.md写好这个文件不仅仅是给人看的平台也会按照一定的结构抽取其中的描述信息用于展示和检索。我习惯在README.md里包含以下内容功能一句话说明适用场景和不适用的边界参数表格说明两个以上的示例输入输出常见问题与解答发布后不要想着一次写好就完事。社区用户会在使用中发现你没预料到的边角情况比如特殊输入、格式异常、需求变更。保持一个小原则如果用户反馈某个问题出现两次以上就值得在下个版本里根治如果只出现一次先记录下来观察。我在社区里维护的每个Skill基本上都经历过至少三个版本的迭代。第一个版本往往是非常粗糙的“能用”第二版本根据自己使用痛点调整第三版本根据社区反馈优化。迭代本身也是提升Skill排名的因素之一社区算法一般会优先展示有活跃更新记录的Skill。写在最后我自己用过不少Skill也从零写过好几个最大的体会是写Skill和写普通代码不一样它更像是在设计一个小型产品你要考虑用户怎么说、平台怎么解析、逻辑怎么容错、结果怎么展示。四个环节环环相扣任何一环处理得粗心最终效果都会打折扣。如果只记一句话那就是触发条件多验证参数抽取多兜底返回结构多打磨。这三个点做扎实你的Skill受欢迎程度基本就有保障了。最后再分享一个我常用的测试小技巧每次写完一个Skill我会准备一个“用户乱说话”的测试集里面放一些完全不着边际的输入比如空文本、纯标点、十几种语言的混排。只有确保这些乱输入不至于让Skill崩溃我才敢放心发布到社区。很多线上事故都是栽在这些“正常人不会这么输入”的用例上。
聊个最近社区里讨论比较多的话题——如何在WorkBuddy里编写一个能真正用起来的技能Skill。我看了不少人在社区发帖问Skill到底是什么和普通对话提示词有什么区别还有人照着模板写了一个Skill结果装上去完全不触发也不知道从哪里排查。这些问题我早期都踩过今天把整个流程从头到尾梳理一遍从核心概念到文件结构从第一个能跑的Skill到调试发布一次聊透。WorkBuddy里的Skill本质上就是给智能助手装上一个可复用的能力模块。它不是一个普通提示词而是一个包含参数定义、执行逻辑、返回格式和触发条件的完整程序单元。写Skill的人不需要懂复杂的底层架构但需要理解它的运行机制——Skill怎么被触发、参数怎么传进去、结果怎么返回来这三件事搞清楚了剩下的就是具体场景的逻辑实现。这篇内容适合三类人一是想在WorkBuddy里实现个性化功能的新手二是已经在写Skill但总遇到触发或格式问题的进阶用户三是想把自己做的Skill发布到社区赚取认可和反馈的贡献者。我会用大量实际示例和踩坑记录来说明尽量让每个环节都能直接照着做。注意文中涉及的平台路径和界面名称可能随版本迭代有调整但核心逻辑和文件结构是通用的。1. 理解Skill的核心概念与运行机制1.1 Skill到底是什么一句话概括Skill是智能助手的技能插件它让你的助手不只是“会聊天”而是“会办事”。拿生活场景来类比。你雇了一个全能助理他什么都会但如果你不对他说清楚你要什么、用什么方式给他、期望他怎么做他就只能泛泛而谈。Skill就像是给这个助理写的一本操作手册什么情况下触发他、需要哪些信息、按什么步骤执行、最后怎么把结果汇报给你。在WorkBuddy中一个Skill由以下部分组成触发条件trigger定义了什么时候激活这个技能可能是关键词、意图匹配或特定参数组合。参数定义parameters说明这个技能需要哪些输入每个输入的格式、默认值、取值范围。执行逻辑action真正干活的代码或调用逻辑负责处理参数、产出结果。返回结构response定义结果返回给用户时的格式方便下游继续处理。理解这一点很重要Skill不是替代对话而是在对话流程中嵌入可执行逻辑。它解决的问题是“让助手从说到做”并且让这个“做”的过程是可复用、可分享、可迭代的。1.2 Skill的工作流程我画了一条完整的工作链路描述形式不用图帮你把每个环节对应到实际开发中用户输入一段话 → WorkBuddy平台的解析层先做意图识别 → 命中某个Skill的触发条件后进入该Skill的上下文 → 从用户输入中抽取参数 → 执行定义的逻辑 → 生成结构化返回 → 平台把返回渲染成用户可读的内容。这里容易忽略的细节是参数抽取不一定发生在执行逻辑内部。WorkBuddy的Skill机制允许你声明一套抽取规则平台解析层会先把用户原话里的信息填进参数槽位再交给逻辑层。这意味着即使你的执行逻辑只是简单输出一段文本只要参数定义完善Skill依然能适配千变万化的用户说法。举个例子。你想做一个“设置提醒”的Skill用户可能说“明天下午3点提醒我开会”也可能说“15分钟后叫我喝水”还可能说“每天晚上10点提醒我打卡”。这三句话语义差异很大但都可以抽取出“时间”和“事项”两个参数。参数抽取规则定义得好不好直接决定Skill的泛化能力。1.3 为什么用Skill而不是直接写死逻辑有人会问我把这些判断逻辑直接写进Prompt让模型每次动态决定不就行了吗为什么非要单独搞一个Skill我用实际感受来回答。早期我也试着在System Prompt里堆规则告诉模型“当用户提到提醒时就做X当用户提到计算时就做Y”结果有两个问题非常折磨人第一Prompt越长模型对规则的遵循度越不稳定。你加了10条规则它可能在处理第1条时表现优秀处理第7条时就忘掉了或者把两条冲突规则混合执行。第二所有逻辑混在一个代码块里每次要改一个功能都得小心翼翼生怕影响其他功能。Skill的模块化把这些问题从根本上解决。每个Skill是独立的单元触发它时才被装载参数和执行逻辑都是隔离的。如果你觉得某个Skill不好用可以直接替换它其他功能完全不受影响。这就好比你的工具箱里每个工具都有独立的卡槽不会因为换一把螺丝刀而把锤子弄坏。另外Skill天然适合共享。WorkBuddy社区的Skill是带版本、带说明、带评分体系的你把Skill发布出去别人导入就能用还能基于你的版本进行二次改进。这种协作方式是从零搭Prompt很难实现的。2. 开发环境准备与Skill文件结构2.1 环境准备进入WorkBuddy社区后在个人工作台找到“技能开发”入口就能创建和管理Skill。首次创建需要完成两个前置准备一是绑定你的开发者身份并启用API访问权限二是在本机准备一个可用的编辑器。我个人建议不要在平台网页上直接编写大量代码体验不太好。推荐把Skill项目克隆到本地用代码编辑器编辑然后用平台提供的命令行工具或Webhook方式同步测试。这样你可以用上本地的版本管理、代码高亮、语法检查效率会高很多。在正式动手前你还需要理解一个核心原则Skill是一个“声明实现”的结构。声明描述这个Skill是干什么的给平台解析层看实现描述具体怎么做给执行层看。两件事分开职责清晰这也是为什么Skill目录下会有不同类型的文件。具体环境要求如下操作系统无特定限制但命令行工具需要能正常工作。语言运行时环境如果Skill逻辑用Python编写需要对应版本解释器。API密钥与访问令牌用于调试时模拟请求。2.2 标准目录结构拆解一个规范的Skill目录结构通常如下my-skill/ ├── manifest.yaml ├── skill/ │ ├── __init__.py │ ├── skill.py │ ├── prompts/ │ │ ├── intent.md │ │ └── extract.md │ └── resources/ │ └── data.json ├── examples/ │ └── sample-inputs.json └── README.md逐个说下每个文件的职责。manifest.yaml是这个Skill的身份证所有元信息都在里面名称、版本、作者、描述、触发关键词、参数声明、权限需求。平台的Skill市场会读取这个文件让用户看到这是什么。manifest写得不规范可能导致Skill无法被索引。skill/skill.py是执行逻辑接收已经解析好的参数进行处理并返回结果。这里可以调用第三方库、发起网络请求、读取本地文件等。整个Skill的核心价值基本都在这个文件里。skill/prompts/目录存放提示词模板。有人会觉得奇怪Skill不是代替提示词吗怎么还要提示词其实Skill的内部逻辑可能需要借助大模型来完成某个子任务比如从用户输入中提取非结构化信息、生成一段自然语言回复。这些子任务的提示词可以单独放在这里便于调试和替换。examples/目录放示例输入方便自己测试和用户理解。README.md是人读的说明写清楚功能、使用方式、注意事项。2.3 编写前的设计思路先画逻辑再写代码很多新手上来就打开编辑器写代码写到一半发现触发条件覆盖不全或者返回格式不符合预期又回头改结构来回折腾。我的经验是先花20到30分钟做设计画个简单的“输入-处理-输出”流程分析明确以下问题这个Skill解决什么问题用户是谁触发条件怎么定是关键词、正则、还是意图匹配需要哪些参数哪些必填、哪些可选边界值是什么执行逻辑分成几步有没有分支返回格式是什么用户怎么理解异常情况怎么处理参数缺失、调用失败、超时把这六个问题写在纸上或文档里再进行编码你会发现写代码的过程就是照着设计稿填内容不纠结。我通常还会写一段伪代码来帮助梳理逻辑。比如IF 用户输入命中提醒意图 THEN 抽取时间参数 若时间参数为空 反问用户期望的时间 否则 创建提醒 返回确认消息 END这段伪代码直接对应后面实际代码里的主体结构调试的时候思路非常清晰。3. 手写第一个核心Skill筛选优质文章纸上谈兵说够了直接进入实操。我挑一个适合练手的场景来演示编写一个帮助用户筛选优质技术文章的Skill。它的功能是给定一个文章列表根据标题、摘要和阅读时长筛选出值得深读的文章。这个选例有三个考虑功能独立不依赖外部服务逻辑有一定层次涉及数据处理和条件判断结果易于验证你能直观看到Skill是否正常工作。3.1 定义manifest配置创建项目目录后先写manifest.yamlname: article-filter version: 1.0.0 description: 根据标题、摘要和阅读时长筛选值得深读的技术文章 author: community-dev trigger: keywords: - filter - 筛选 - quality-article intent_id: filter_article_intent parameters: articles: type: array required: true description: 待筛选的文章列表 min_rating: type: float required: false default: 4.0 description: 最低质量评分 max_read_minutes: type: int required: false default: 20 description: 最长可接受阅读时长分钟 permissions: network_access: false file_write: false这里有几个值得展开的点。触发关键词trigger这一段我写入了三个关键词和一个意图ID。关键词是给平台解析层做个快速匹配但是关键词匹配不太可靠所以还加了一个intent_id如果平台支持语义理解链路可以结合使用。注意关键词不是越多越好我见过有人写了几十个同义词结果产生大量误触发反而不如三到五个精准词加一个意图ID效果好。参数定义里articles类型是array这表示用户输入需要给到一个数组结构。但这里有个细节如果用户只是贴了一段文章文本而非结构化的数组参数解析层可能无法正确填入。为了兼容这种情况通常我们会用一个简单的提示词子任务把用户输入转换为标准JSON格式再进行筛选。这个过程我用下面一个章节来说明。3.2 执行逻辑实现接下来是核心代码放在skill/skill.py中。这里我直接给出一版相对完整、带注释的实现import json from typing import Any, Dict, List, Optional DEFAULT_MIN_RATING 4.0 DEFAULT_MAX_READ_MINUTES 20 def list_to_text(items: List[Any]) - str: 将列表结构转换为适合模型处理的文本形式 return \n.join( f标题{item.get(title, 未知)} f摘要{item.get(summary, 无)} f评级{item.get(rating, 0)} f阅读时长{item.get(read_minutes, 0)}分钟 for item in items ) def extract_articles_from_text(text: str) - List[Dict[str, Any]]: 当输入是非结构化文本时先将其转换为结构化JSON数组 prompt f 请从下面的文章中提取结构化信息以JSON数组格式返回。 每个元素包含字段 title、summary、rating、read_minutes。 只输出JSON不要其他解释文字。 输入内容 {text[:3000]} # 这里实际调用平台提供的大模型子任务能力获取返回的JSON # 假设存在一个 call_model_api 函数来提供这个能力 response_text call_model_api(prompt) try: articles json.loads(response_text) if not isinstance(articles, list): raise ValueError(返回结果不是数组) return articles except Exception: return [] def filter_articles(params: Dict[str, Any]) - Dict[str, Any]: 筛选文章的核心主逻辑。 接收平台解析层传过来的参数返回结构化结果。 raw params.get(articles) if isinstance(raw, str): articles extract_articles_from_text(raw) elif isinstance(raw, list): articles raw else: return { status: error, message: articles 参数必须是列表或文本 } min_rating params.get(min_rating, DEFAULT_MIN_RATING) max_read_minutes params.get(max_read_minutes, DEFAULT_MAX_READ_MINUTES) qualified [] for idx, article in enumerate(articles): try: rating float(article.get(rating, 0)) read_minutes int(article.get(read_minutes, 999)) except (TypeError, ValueError): continue if rating min_rating and read_minutes max_read_minutes: qualified.append({ index: idx 1, title: article.get(title, 未知标题), rating: rating, read_minutes: read_minutes, reason: f评分{rating}达标预计阅读{read_minutes}分钟 }) return { status: success, matched_count: len(qualified), matched_articles: qualified }逐段解释这段代码的关键逻辑。开头两个常量用于默认值兜底当用户未显式传入参数时使用默认值替代。这是一个很重要的容错设计因为平台解析层偶尔会漏掉某些可选参数执行逻辑必须有默认值处理。list_to_text和extract_articles_from_text两个函数解决“参数形态不一致”的问题。当用户给的是结构化数组直接走过滤用户只给了一段文章文本就先用大模型做一个抽取和转换再进入过滤环节。这就做到了结构化输入和非结构化输入都兼容。filter_articles是主入口。第一步检查articles参数的类型如果是字符串就调用抽取函数如果是列表就直接用两者都不是就返回错误信息。注意这里的错误返回也遵循结构化格式这是为了让平台能正确渲染错误提示而不是简单地抛个异常。过滤循环里有一个细节我把每个不达标的文章都进行continue不把它加进结果同时对rating和read_minutes做了类型转换转换失败则跳过。这个“宁可跳过也不崩溃”的设计在Skill开发里非常关键。reason字段是给用户看的简要说明为什么推荐这篇文章。这样返回结果不只是数据还带着可读性用户体验会好很多。3.3 返回结构设计与提示词模板编写平台会读取函数返回的字典结构根据字段内容渲染成不同形态的卡片或文本。我把返回结构设计成三种状态成功且有匹配、成功但无匹配、参数错误。成功且有匹配时返回matched_count和matched_articles数组平台端可以展示成文章列表卡片。无匹配时返回matched_count: 0和一句友好提示文案。参数错误时返回status: error和详细错误信息。这部分的提示词模板我放在skill/prompts/extract.md里内容大致如下你是一个信息抽取助手。用户会给你一段包含若干文章信息的文本你需要抽取以下字段 - title文章标题 - summary一句话摘要 - rating文章质量评分0到5之间的数字保留一位小数 - read_minutes预计阅读时长整数 输出要求 - 严格输出JSON数组不要包含任何额外文字 - 如果某项信息缺失使用 null 填充 - 最多抽取10篇文章这个提示词有个细节值得说明我明确写了“如果某项信息缺失使用 null 填充”而不是“留空”。因为JSON解析时null才能正确转为Python的None空字符串可能导致后续类型转换失败。4. 测试、调试方法与常见问题排查4.1 本地模拟测试拿到一个可以跑的Skill后第一件事不是在平台上点击启用而是先在本地模拟测试。我自己会在本地写一个简单的测试脚本模拟平台解析层传入不同参数的情况。# 模拟测试 test_cases [ { articles: [ {title: A, summary: 深入介绍, rating: 4.5, read_minutes: 15}, {title: B, summary: 基础入门, rating: 3.2, read_minutes: 30}, {title: C, summary: 实战经验, rating: 4.8, read_minutes: 45}, ], min_rating: 4.0, max_read_minutes: 20, }, { articles: 标题深度学习入门指南摘要适合初学者评分3.5阅读时长25分钟。标题模型优化实战摘要深入内存优化技巧评分4.7阅读时长18分钟。, }, ] for case in test_cases: result filter_articles(case) print(json.dumps(result, ensure_asciiFalse, indent2))跑完测试后检查以下几点结构化输入时过滤条件是否正确非结构化文本输入时抽取转换是否成功过滤后没有匹配项时返回是否友好传入异常类型比如数字而不是列表时是否返回error而不是抛异常这几类情况覆盖全面后再把Skill在平台测试环境跑一遍通常会顺利很多。4.2 常见问题排查速查表我在社区和交流群里看了很多人的问题整理一个排查速查表你遇到类似问题时可以直接对号入座。现象可能原因排查思路Skill根本没有被触发关键词不匹配、意图定义不够精准检查manifest里的触发条件试试输入包含确切关键词触发后返回参数缺失用户输入缺少某些参数或抽取规则未定义在参数定义中增加默认值或者增加一条反问逻辑非结构化文本总是解析失败JSON解析异常、大模型返回了多余文字在提示词中强调“只输出JSON”并在代码里做健壮性容错过滤结果为空阈值设置不合理或者数据本身不达标先降低阈值测试确认逻辑链路是否正常耗时太长非结构化文本长度过大调用模型超时截断输入文本限制最长处理长度依赖库找不到运行时环境未安装对应依赖在Skill配置文件里声明依赖并确认运行环境版本排查时的核心思路是“逐层拆解”先确认触发层有没有问题再确认参数层再确认逻辑层最后确认返回层。不要一上来就怀疑代码逻辑很多时候问题出现在上游的触发和参数抽取环节。4.3 平台端联调与日志观察本地测试通过后在WorkBuddy平台创建测试会话导入Skill输入预置测试用例观察返回结果。平台会提供一份执行日志记录每一层的输入输出包括触发决策、参数输出、逻辑执行结果和耗时。联调过程中有一个很有意思的场景在测试环境Skill工作正常但到正式环境就失效了。这个问题我遇到过几次原因通常是正式环境的权限配置更严格。比如我这个文章筛选Skill只涉及本地数据处理不涉及网络访问但如果你在代码里隐藏了一些网络请求逻辑比如加载远程数据正式环境下会因为权限不足而静默失败。所以务必在manifest中准确声明权限并且在测试时主动测试“最小权限”条件下的行为。还有一个容易被忽略的点返回结果的超时限制。如果Skill的某个分支需要调用外部大模型子任务而这个子任务耗时不稳定可能超出平台限制。我的建议是凡是耗时操作尽量设置一个内部超时上限超时后快速返回一个兜底应答而不是让用户一直等待。5. 进阶优化与发布到社区5.1 让Skill更聪明引入上下文状态基础Skill已经能完成单次任务但很多实际场景需要多轮交互。比如用户说“帮我筛选文章”你反问“请提供文章内容”用户分了几条消息发过来怎么把这些散落的片段拼起来这就要用到WorkBuddy的上下文记忆机制。在Skill的执行逻辑中可以把未处理完的中间状态写到上下文中。当用户再次发起含相关信息的输入时平台会把历史上下文合并传入Skill可以从上下文中取回上次存下的部分数据完成信息拼接。我的实现思路是在参数不完整时不直接返回错误而是返回一个“询问信息”的结构同时在上下文中保留临时数据。下次再触发时先读取上下文合并新参数再执行逻辑。这样设计的好处是用户觉得你在“连续对话”而不是在“状态机里跳转”。5.2 权限边界与安全设计Skill越做越复杂时安全很重要。我给Skill开发者的权限设计提几条实用建议最小权限原则在manifest中只声明需要的能力不需要网络访问就明确关闭。输入校验任何用户传来的参数在执行前都做类型、范围、枚举校验。输出清理如果Skill会生成文本要过滤掉可能造成注入风险的特殊字符。资源限制限制最大输入长度、最大输出长度、最大循环次数。这四条是底线不是为了多数用户而是为了守护少数恶意输入。Skill一旦发布到社区被别人导入使用你就对你的代码负有责任。写得保守一点不容易出问题。5.3 发布与持续迭代发布到社区之前先把README.md写好这个文件不仅仅是给人看的平台也会按照一定的结构抽取其中的描述信息用于展示和检索。我习惯在README.md里包含以下内容功能一句话说明适用场景和不适用的边界参数表格说明两个以上的示例输入输出常见问题与解答发布后不要想着一次写好就完事。社区用户会在使用中发现你没预料到的边角情况比如特殊输入、格式异常、需求变更。保持一个小原则如果用户反馈某个问题出现两次以上就值得在下个版本里根治如果只出现一次先记录下来观察。我在社区里维护的每个Skill基本上都经历过至少三个版本的迭代。第一个版本往往是非常粗糙的“能用”第二版本根据自己使用痛点调整第三版本根据社区反馈优化。迭代本身也是提升Skill排名的因素之一社区算法一般会优先展示有活跃更新记录的Skill。写在最后我自己用过不少Skill也从零写过好几个最大的体会是写Skill和写普通代码不一样它更像是在设计一个小型产品你要考虑用户怎么说、平台怎么解析、逻辑怎么容错、结果怎么展示。四个环节环环相扣任何一环处理得粗心最终效果都会打折扣。如果只记一句话那就是触发条件多验证参数抽取多兜底返回结构多打磨。这三个点做扎实你的Skill受欢迎程度基本就有保障了。最后再分享一个我常用的测试小技巧每次写完一个Skill我会准备一个“用户乱说话”的测试集里面放一些完全不着边际的输入比如空文本、纯标点、十几种语言的混排。只有确保这些乱输入不至于让Skill崩溃我才敢放心发布到社区。很多线上事故都是栽在这些“正常人不会这么输入”的用例上。
