创建、发布和维护业务 Skill

当一套业务规则需要反复告诉 Agent，或者希望团队成员都按同一种方式操作时，可以把它整理成业务 Skill。

这篇文档带你从一个本地草稿开始：先发布个人版并自己验证，再提交公司版审核；以后规则变化时，继续在同一个本地目录维护和更新。

TIP

先选择发布范围

个人版（personal）：默认发布方式。只有你自己能看到，发布后不需要审核，适合开发和验证。 公司版（company）：公司成员都能使用，但每次发布新版本都需要管理员审核。提交成功后暂不生效，审核通过后才会出现在成员的可安装列表中。 推荐顺序：先发布个人版并完成验证，再提交公司版。不要直接用未经验证的草稿申请公司级发布。

确定 Skill 编码和操作类型

先给 Skill 取一个稳定的英文编码（skillCode）。使用小写字母、数字和连字符，例如 invoice-review。这个编码用于识别和更新 Skill，发布后不要修改。

再确认 Skill 会不会改变业务数据：

• read：只查询、汇总或核对，不创建、不修改业务数据。
• write：会创建、修改、删除、发送、上传、发布或推动状态流转。

如果不能确定，先把实际操作列出来。只要其中一步会改变业务状态，就选择 write。

创建本地 Skill 草稿

只查询数据时执行：

lovrabet skill create --name <skillCode> --type read

会改变业务数据时执行：

lovrabet skill create --name <skillCode> --type write

命令会生成 .agents/skills/<skillCode>/。这一步只创建本地文件，不会上传，也不会让其他人看到。

填写 Agent 识别 Skill 所需的信息

打开目录中的 SKILL.md，按顺序完成下面四项：

1. 保留 name，确保它和创建时填写的 skillCode 完全一致。
2. 增加 displayName，填写用户能看懂的中文名称。
3. 把 description 的占位内容改成触发说明：这个 Skill 能做什么、用户在什么情况下会用、什么情况不要用。
4. 取消 example 前面的注释，填写一句用户可以直接发送的典型需求。

---
name: invoice-review
displayName: 发票检查
description: "检查发票字段是否完整、金额是否一致；上传发票并要求核对时使用，不用于修改财务系统数据。"
example: "检查一下这张发票"
metadata:
  type: read
---

补全 Skill 的执行规则

继续填写模板正文中的占位内容。至少写清楚：

• 开始执行前，用户必须提供哪些资料。
• Agent 按什么顺序操作，每一步看到什么结果才继续。
• 哪些情况必须停下来询问用户，不能自行扩大操作范围。
• 最后返回什么结果，怎样判断任务完成。

如果选择了 write，还要写清楚正式执行前如何预览和确认、执行后如何读回检查、失败后如何恢复。

不要在 Skill 中写入 AccessKey、Cookie、密码、测试账号或个人电脑的绝对路径。

检查本地 Skill

保存文件后执行：

lovrabet skill validate --dir .agents/skills/<skillCode>

看到检查通过后再继续发布。warning 表示有推荐信息未填写；虽然不一定阻断发布，也应先检查并补齐。error 会直接阻断发布，必须修复。

预览并发布个人版

先做发布预览。这一步会运行平台检查，但不会创建版本：

lovrabet skill push --dir .agents/skills/<skillCode> --dry-run

没有 error 后，正式发布个人版：

lovrabet skill push --dir .agents/skills/<skillCode>

如果命令展示 warning 并停止，先逐条核对。确认是误报、且原内容不需要修改时，再执行：

lovrabet skill push --dir .agents/skills/<skillCode> --confirm-warnings

个人版发布后立即可用，不需要管理员审核。其他普通成员看不到，也不能安装。

安装并验证个人版

先确认云端已经存在个人版：

lovrabet skill list --scope personal --code <skillCode>

再安装到本机：

lovrabet skill install --scope personal --code <skillCode>

回到 Agent 对话，发送 example 中那句典型需求，检查 Agent 是否正确识别 Skill、按规则执行并返回预期结果。发现问题时，回到本地目录修改，不要继续提交公司版。

提交公司版审核

个人版验证通过后，先预览公司级发布：

lovrabet skill push --scope company --dir .agents/skills/<skillCode> --dry-run

确认没有 error 后，正式提交：

lovrabet skill push --scope company --dir .agents/skills/<skillCode> --confirm-warnings

看到提交成功，只表示版本已经进入审核。此时公司成员还看不到新版本。管理员审核通过后，公司版才会生效。

审核通过后检查公司版

管理员通知审核通过后，查看公司版：

lovrabet skill list --scope company --code <skillCode>

列表中出现生效版本后，成员可以执行：

lovrabet skill install --scope company --code <skillCode>

如果发布者本机还装有同名个人版，个人版仍然优先生效。其他没有个人版的公司成员会使用审核通过的公司版。

更新已经发布的 Skill

业务规则变化时，继续维护原来的 .agents/skills/<skillCode>/ 目录，不要新建另一个编码。

1. 修改 SKILL.md 和需要一起发布的 references、scripts 或 assets。
2. 执行 lovrabet skill validate --dir .agents/skills/<skillCode>。
3. 先用个人版 push --dry-run 检查，再正式 push。
4. 重新执行 lovrabet skill install --code <skillCode>，并在 Agent 对话中验证。
5. 需要同步给公司时，再用 push --scope company 提交新版本审核。

公司版每次更新都需要重新审核。新版本审核通过前，成员继续使用上一个已经生效的公司版。

没有本地源文件时再这样处理

如果本地草稿目录已经丢失，可以先安装目标 Skill，再从本机已安装内容确认现有规则：

lovrabet skill install --code <skillCode>

安装目录是 Agent 使用的产物，不建议直接长期编辑。需要修改公司版时，先在工作目录建立个人副本，验证后再提交公司版审核；不要直接覆盖已经生效的公司版本。

遇到问题时这样检查

**同事看不到我的个人版？**这是正常的。个人版只对发布者本人和企业管理员可见。要给同事使用，必须提交公司版并通过审核。

**公司版提交成功，同事仍然安装不到？**先确认审核是否已经通过。提交成功和审核通过是两个状态。

**我更新了公司版，自己的 Agent 还是旧行为？**运行 lovrabet skill list --local --scope all，检查是否存在同名个人版。个人版优先于公司版。

**扫描提示有密码或密钥？**立即从 Skill 中删除，并轮换已经暴露的凭证。不要使用 --confirm-warnings 跳过真实的安全问题。