企业官网建设流程全解析

聊个最近社区里讨论比较多的话题——如何在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分钟做设计，画个简单的“输入-处理-输出”流程分析，明确以下问题：

1. 这个Skill解决什么问题？用户是谁？
2. 触发条件怎么定？是关键词、正则、还是意图匹配？
3. 需要哪些参数？哪些必填、哪些可选？边界值是什么？
4. 执行逻辑分成几步？有没有分支？
5. 返回格式是什么？用户怎么理解？
6. 异常情况怎么处理？参数缺失、调用失败、超时？

把这六个问题写在纸上或文档里，再进行编码，你会发现写代码的过程就是照着设计稿填内容，不纠结。

我通常还会写一段伪代码来帮助梳理逻辑。比如：

IF 用户输入命中"提醒"意图 THEN 抽取时间参数 若时间参数为空： 反问用户期望的时间 否则： 创建提醒 返回确认消息 END

这段伪代码直接对应后面实际代码里的主体结构，调试的时候思路非常清晰。

3. 手写第一个核心Skill：筛选优质文章

纸上谈兵说够了，直接进入实操。我挑一个适合练手的场景来演示：编写一个帮助用户筛选优质技术文章的Skill。它的功能是给定一个文章列表，根据标题、摘要和阅读时长筛选出值得深读的文章。

这个选例有三个考虑：功能独立，不依赖外部服务；逻辑有一定层次，涉及数据处理和条件判断；结果易于验证，你能直观看到Skill是否正常工作。

3.1 定义manifest配置

创建项目目录后，先写manifest.yaml：

name: 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_ascii=False, indent=2))

跑完测试后，检查以下几点：

• 结构化输入时，过滤条件是否正确？
• 非结构化文本输入时，抽取转换是否成功？
• 过滤后没有匹配项时，返回是否友好？
• 传入异常类型（比如数字而不是列表）时，是否返回error而不是抛异常？

这几类情况覆盖全面后，再把Skill在平台测试环境跑一遍，通常会顺利很多。

4.2 常见问题排查速查表

我在社区和交流群里看了很多人的问题，整理一个排查速查表，你遇到类似问题时可以直接对号入座。

排查时的核心思路是“逐层拆解”：先确认触发层有没有问题，再确认参数层，再确认逻辑层，最后确认返回层。不要一上来就怀疑代码逻辑，很多时候问题出现在上游的触发和参数抽取环节。

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崩溃，我才敢放心发布到社区。很多线上事故，都是栽在这些“正常人不会这么输入”的用例上。