skill-template/references/ACTIONS.md

Skill Action Manifest（匠厂宿主）

本文件说明 assets/actions.json 与 scripts/main.py CLI 的对应关系，供 Agent 编排与宿主 Skill Action Runtime 使用。

边界： 用户市场说明见根目录 README.md；CLI 参数与错误码细节见 CLI.md。

模板严格规范 vs 宿主向后兼容

角色	定位
skill-template	新技能推荐的严格规范：必填字段、明确类型、additionalProperties: false
宿主运行时	向后兼容的历史 manifest 解析器：可能接受部分缺省字段（如 description、placements、entrypoint.args、input property type）

新技能不应依赖宿主缺省行为。 复制模板后按 assets/schemas/skill-actions.schema.json 与本文完整填写 manifest。

JSON Schema 使用 additionalProperties: false 表达模板严格边界；这与宿主共享类型中的可选字段并不矛盾——宿主为兼容旧技能可能更宽松，模板为防漂移要求更严。

Action 是否必需

Action 是可选能力：

• 没有宿主直接操作需求的技能，可以不提供 actions.json。
• 需要出现在数据管理按钮、技能详情、定时任务或 Agent 直接调用中的技能，必须提供 assets/actions.json。

文件位置

{skill_root}/assets/actions.json

宿主扫描路径示例：

~/.openclaw/skills/your-skill-slug/assets/actions.json

顶层结构

字段	必填	说明
schemaVersion	是	当前固定为 1
skill	是	必须与 SKILL.md 的 metadata.openclaw.slug 一致
actions	是	Action 数组，每项 id 唯一

模板最小示例见 assets/actions.json；JSON Schema 见 assets/schemas/skill-actions.schema.json。

Phase 1 当前稳定支持（新技能应只使用这些）

层级	稳定字段 / 能力
顶层	schemaVersion、skill、actions
action	id、label、description、placements、entrypoint；可选 inputSchema、confirmation
entrypoint	type = cli、command、args（必填 JSON 数组，项为 string / number / boolean）
placements	toolbar、skill-detail、agent、cron
inputSchema	根 type: object；properties 使用 string / number / boolean；支持 enum、default、required、sensitive
confirmation	{ "message": "..." }

预留能力（当前不可当作已实现能力）

以下在宿主共享类型或 Schema 枚举中可能出现，但 Phase 1 Runtime 尚未完整支持，新模板示例不得使用：

类别	预留项	说明
placements	row、batch	行内 / 批量入口，未来扩展
action 字段	bind、concurrency、locks	绑定、并发与锁控制，宿主后续实现
inputSchema	array、nested object、oneOf 等	复杂表单与联合类型，不属于当前推荐模板范围

可以在文档或 Schema 枚举中保留这些值供未来对齐，但不要让技能作者误以为它们已经可执行。

执行模型

宿主将 action 转为 argv，再执行：

python {skill_root}/scripts/main.py <command> <args...>

• entrypoint.type 当前只支持 cli
• entrypoint.command → CLI 子命令（须真实存在）
• entrypoint.args → 子命令参数（必须为 JSON 数组）
• {{fieldName}} → 来自 inputSchema 用户输入的简单模板替换

完整子命令定义见 scripts/cli/app.py。

CLI 输出契约

技能 CLI 必须：

• 使用稳定的退出码
• 成功时输出可解析的结构化结果
• 失败时输出稳定错误信息
• 对可预期错误提供稳定错误码
• 对用户可处理的问题提供 HINT
• 不依赖 Agent 连续对话才能完成
• 不自行实现宿主任务中心
• 长时间任务允许异步执行，由宿主任务中心承载状态
• 不在 CLI 中硬编码宿主安装目录
• 不直接依赖某个具体 UI 页面

建议错误输出格式：

ERROR:<CODE>: <message>
HINT: <next step>

placements（入口位置）

值	含义
toolbar	数据管理第一排技能按钮
skill-detail	技能详情或技能市场详情页
agent	Agent 可直接调用
cron	定时任务可直接调用

预留能力（当前宿主可能尚未完整支持，模板示例请勿使用）：

值	说明
row	行内操作（未来扩展）
batch	批量操作（未来扩展）

可以在 manifest 中作为未来扩展值定义，但不要让技能作者误以为 row / batch 已经完整可用。

inputSchema 与参数表单

当前宿主稳定支持：

• object / string / number / boolean
• enum / default / required / sensitive
• 简单模板替换（{{fieldName}}）

示例：

{
  "inputSchema": {
    "type": "object",
    "required": ["query"],
    "properties": {
      "query": {
        "type": "string",
        "title": "查询条件"
      },
      "limit": {
        "type": "number",
        "title": "返回数量",
        "default": 50
      }
    }
  }
}

约定：

• boolean 在宿主中渲染为开关
• enum 在宿主中渲染为选择框
• required 字段在提交前校验
• sensitive 字段不得出现在低信任入口
• 需要确认的副作用操作使用 confirmation.message
• 模板参数使用 {{fieldName}}，且必须在 inputSchema.properties 中声明
• entrypoint.args 项当前只允许 string、number、boolean；不允许对象或 null
• 不要在当前模板中宣传 nested object、oneOf、复杂数组等尚未稳定支持的能力

风险与入口配置

• 查询、诊断、版本检查可以放到 skill-detail 或 agent
• 低风险、常用动作才考虑放 toolbar
• 会修改本地数据、访问外部系统、执行长时间任务的动作必须谨慎配置
• 有副作用的动作应添加 confirmation.message
• 高风险动作不应默认出现在 toolbar
• 含 sensitive 参数的 action 不应放入 toolbar 或 cron，除非有明确安全设计
• 不要为了「按钮多」而暴露所有 CLI 子命令
• 一个 CLI 命令可以拆成多个语义清晰的 action，但每个 action 必须有明确语义

模板示例 action 一览

id	CLI	placements	说明
health	health	skill-detail, agent	运行环境检查
version	version	skill-detail	版本 JSON
config-path	config-path	skill-detail	配置路径 JSON

复制为新技能后，请按业务需要增删 action；不需要宿主入口时可删除整个 actions.json。

与宿主 API（参考）

宿主 API	用途
GET /api/skill-actions/{skillSlug}	读取 manifest
POST /api/skill-actions/run	{ skillSlug, actionId, input?, source? }
GET /api/skill-actions/jobs	任务中心

具体路径与字段以宿主实现为准；技能侧只需保证 manifest 与 CLI 契约稳定。