skill-template/references/ACTIONS.md

Skill Action Manifest（匠厂宿主）

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

权威运行时契约（sync/async、任务中心、编排范式）见 ../development/SKILL_ACTION_RUNTIME.md。

边界： 用户市场说明见根目录 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。
• 含浏览器 RPA / 长耗时任务的技能：必须提供至少一条 executionProfile: "async" 且 placements 含 agent 的 action（见 POLICY-SKILL-ACTION-001）。

文件位置

{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、executionProfile
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": "..." }
executionProfile	"sync" | "async"（模板要求显式写出）

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

以下在宿主共享类型或 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。

executionProfile（sync / async）

值	宿主行为	任务中心
sync	内联等待 CLI（默认约 30s）	不进
async	后台 Job，立即返回 jobId	进入
省略	宿主默认按 async	进入

• RPA / 浏览器 / 长耗时 → 必须 "async"，并建议加 confirmation。
• 数据管理 toolbar → 只挂 async action。
• 完整规则见 ../development/SKILL_ACTION_RUNTIME.md。

CLI 输出契约

技能 CLI 必须：

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

建议错误输出格式：

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

placements（入口位置）

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

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

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

Action 类型 × placements 矩阵

Action 类型	executionProfile	典型 placements	confirmation
health / version / config-path	sync	skill-detail, agent	无
统计 / 只读查询	sync	skill-detail, agent	无
导入 / 重置	sync	skill-detail, agent	可选
单条副作用 RPA	async	agent, skill-detail	必须
批量顺序 pick RPA	async	toolbar, cron, agent	必须

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
      }
    }
  }
}

批量 pick 参数约定（有队列表时）：

{
  "pickCount": {
    "type": "number",
    "title": "处理数量",
    "description": "从队列选取 pending 记录条数",
    "default": 1,
    "minimum": 1
  }
}

约定：

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

风险与入口配置

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

模板示例 action 一览

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

业务技能复制后，按需增加例如：

模式	id 示例	executionProfile	placements
单条 RPA	your-run	async	agent, skill-detail
队列 pick	your-run-pick	async	toolbar, cron, agent
统计	your-stats	sync	skill-detail, agent

不需要宿主入口时可删除整个 actions.json（无 RPA 长任务时）。

与宿主 API（参考）

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

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