参考MCP 工具execute_cloud_skill

Tool Reference

execute_cloud_skill

通过隔离的 execution engine 运行 active Cloud Skill 中声明的一个 script component。

按 script path 和 revision 执行

选择 active skill；需要可复现性时 pin 一个 revision，并指定 type 为 script 的 component。执行需要 memory:write，并返回 typed execution envelope。

公开 MCP 工具

execute_cloud_skill

用途

通过隔离的 SandboxExecutionEngine 执行 active Cloud Skill 中声明的一个 script component。

适用场景

  • 在选定目标 revision 后，运行 skill 中确定性的 Python 或 Bash script component。
  • 传入有界的 JSON input object，并使用包含 status 和 output data 的 typed execution result。
  • 将 skill 的可复用 procedure 作为 executable component 使用，而不是把代码复制到 agent prompt。

不适用场景

  • 不要执行 reference、example、template、document 或 artifact component；只接受 type='script'。
  • 生产环境不要依赖不安全的 local fallback：没有可用的 bubblewrap isolation driver 时，默认 fail-closed 为 SANDBOX_UNAVAILABLE。
  • 不要用于任意 host commands、network access 或无界 job；sandbox 会施加 namespace、environment、timeout、process、memory 和 output controls。
  • 当可复现执行很重要时不要省略 revision pinning；显式 revision 可以避免运行不同的 published snapshot。

所需权限范围

  • MCP surface 需要 memory:write，因为执行是经过授权的 skill operation。
  • skill 必须解析在认证的 personal 或 team scope 内；跨 scope 的 skill ID 会返回 ACCESS_DENIED。

参数列表

参数名类型描述
script_pathstring要执行的 script component 的 logical path 或 component ID。
slugstring · 默认值: empty用于解析 active skill 的 skill slug。
skill_idstring · 默认值: empty作为 slug 替代项的稳定 skill identity。
revision_idstring · 默认值: empty可选的 revision pin；否则依次选择 published revision，再选择 latest revision。
input_argsobject · 默认值: empty object编码后写入 script stdin 的 JSON-compatible values。
timeout_secondsinteger · 默认值: 30由 ExecutionLimits 限制为 1–60 秒的执行 timeout。

返回模式

JSON CloudSkillResponseEnvelope，kind='execution'，data 包含 execution_id、skill_id、revision_id、script_path、runtime、status、exit_code、stdout、stderr、truncation flags、可选 output_data、duration_ms、memory_peak_bytes、cpu_time_ms、timestamps 和 error_kind。

使用示例

运行一个 pinned script component
execute_cloud_skill({
  slug: "deployment-procedure",
  revision_id: "revision-id-from-root-recall",
  script_path: "scripts/check.py",
  input_args: { environment: "staging" },
  timeout_seconds: 30
})

错误信息

  • ACCESS_DENIED、SKILL_NOT_FOUND 或 SKILL_ARCHIVED：无法在 caller 的 scope 内解析 skill。
  • REVISION_NOT_FOUND：请求的 revision 不属于该 skill，或不存在 active revision。
  • SCRIPT_NOT_FOUND 或 INVALID_COMPONENT_TYPE：path 不存在，或指向非 script component。
  • SANDBOX_UNAVAILABLE：host 没有可用的 bubblewrap isolation driver，且不安全 fallback 已禁用。
  • EXECUTION_TIMEOUT、RESOURCE_EXHAUSTED 或 SCRIPT_EXECUTION_ERROR：watchdog、resource limits 或 script exit status 终止了执行。

来源: Cloud Skills