WorkBuddy 技能与专家包写作

概述

WorkBuddy 开放平台官方文档（open.workbuddy.cn/docs/skill、/docs/expert）给出了技能与专家包的格式规范；本 skill 补齐官方文档之外的部分——怎么写才不会被产品测试打回、不被审核驳回。全部提炼自真实提审与测试反馈：

1. 逐字段对账纪律：技能正文里的参数名、枚举值、过滤条件与工具实现不符，是最高频的翻车点（初稿大量虚构参数导致整批重写的事故）；
2. 专家包高频不合规清单：agentName 与文件名不匹配、头像缺失、缺依赖声明等 6 类，全部来自真实重建案例；
3. 市场文案硬性规范：displayDescription 中文字数、defaultInitPrompt 与 quickPrompts 一致性、tags/quickPrompts 固定数量等官方强制项的落地核对法；
4. 提审顺序与版本纪律：依赖方向决定提交顺序；驳回分话术类/功能类两条整改路径。

与 workbuddy-oauth-integration（连接器 OAuth 授权链路）配套，组成 WorkBuddy 对接系列。

生态角色与依赖方向

先分清四种交付物，依赖方向决定提审顺序：

连接器（connector）      MCP 服务入口，市场元信息 + mcp.json；可携带 skills/ 分发运行时技能
   ▲ 依赖
专家（expert）           人设化 Agent（plugin.json + agents/*.md），可通过 dependencies.connectors
   ▲                      声明依赖已上架连接器；用户召唤时先引导连接
专家团（expert team）     多 Agent 协作（leadAgent + memberAgents）
技能（skill）            Agent 执行知识（SKILL.md），可独立上架，也可随连接器分发

• 技能随连接器分发时（连接器包 skills/ 目录），专家包里不要再放同一批技能——技能会随连接器加载，放两处就是双份分发，且容易漂移；
• 专家依赖连接器必须显式声明 dependencies.connectors，否则用户召唤时没有连接引导卡片，专家等于废的。

何时使用

当用户：

• 要写一个 WorkBuddy 运行时技能（SKILL.md），尤其是调用 MCP 工具的业务技能；
• 要打包专家或专家团（plugin.json + agents/ + avatars/）；
• 要为已上架连接器写配套技能，或把已有技能改造成连接器分发版；
• 遇到：开放平台 zip 解析失败、审核驳回、产品测试反馈"参数不详细/参数不存在"、技能调用工具总是失败。

不适用：连接器 OAuth 授权链路（用 workbuddy-oauth-integration）；与 WorkBuddy 无关的通用提示词写作。

第一纪律：逐字段对账（最高频翻车点）

技能正文里的每一个参数名、枚举值、过滤条件、返回字段，都必须能在工具实现（或后端 DTO）里逐字段指认出来。 禁止凭记忆、凭猜测、凭"应该是这样"写参数。真实事故：某批初稿技能被产品测试整体打回，事后逐字段核对发现——

操作法：写技能前先读工具的入参 schema（zod/JSON Schema）与后端 DTO，列一张「参数 → 类型 → 枚举 → 必填」对照表；正文与对照表一一对应；工具面若做了字段裁剪（trim），裁剪后还剩什么字段必须与后端实际返回行字段核对，而不是凭旧契约记忆。

口径唯一事实源：工具口径（参数、枚举、出参字段清单）只维护一份事实源文档；技能是分发副本。上游改了先改事实源，再同步所有副本——两处各写各的必然漂移。

工作流程

第 1 步 — 确定交付物形态

独立技能 / 连接器配套技能 / 专家 / 专家团？依赖谁（连接器、内置 MCP）？据此确定包结构和提审顺序。

第 2 步 — 加载参考文档

• 写技能（SKILL.md）：读 references/skill-package.md（格式 + 正文写作规范）
• 打包专家/专家团：读 references/expert-package.md（plugin.json 全字段 + 依赖 + 头像 + 分类）
• 发前自检：读 references/submission-checklist.md
• 排障：读 references/pitfalls.md 按现象检索

第 3 步 — 对账

按第一纪律列参数对照表，逐字段核对工具实现。这一步没做完不许动笔写正文。

第 4 步 — 写作

技能正文是给 Agent 的执行指令，不是给用户的产品说明书：

• 开头写触发条件（何时用/何时不用），description 是市场与 Agent 的路由依据，要含触发词；
• 正文按步骤写，可执行、可验证；调用工具时写清参数名与取值；
• 口径边界如实写：不支持时间过滤就写"无法精确统计本周新增"，聚合口径就写"仅聚合无逐封明细"——用户问的就是 Agent 答不上的，提前写明省一轮对话；
• 依赖连接器的技能加「错误与恢复」节（401 等待自动续期/断开重连引导、403 检查授权与权限）和「连接器形态限制」节（哪些工具在哪些形态不可用）；
• 中英双语字段成对给全（description_zh/en、examples_zh/en）。

第 5 步 — 自检与打包

过 references/submission-checklist.md 的检查项，再打包 zip。zip 解析失败先按官方基础结构自查（SKILL.md 是否在包根、目录命名、frontmatter 必填字段）。

第 6 步 — 提审与整改

提审顺序：被依赖的连接器先上架，专家后提。驳回后按 references/submission-checklist.md 的分类整改（话术类改文案 / 功能类补代码升版本重打包）。

红线速查（Top 5，全文见 references/pitfalls.md）

参考文档索引