Execute by script path and revision
Choose an active skill, pin a revision when reproducibility matters, and name a component whose type is script. Execution requires memory:write and returns a typed execution envelope.
Public MCP tool
execute_cloud_skill
Purpose
Execute one declared script component from an active Cloud Skill through the isolated SandboxExecutionEngine.
When to use
- Run a deterministic Python or Bash script component from a skill after selecting the intended revision.
- Pass a bounded JSON input object and consume the typed execution result, including status and output data.
- Use the skill's reusable procedure as an executable component rather than copying code into an agent prompt.
When NOT to use
- Do not execute a reference, example, template, document, or artifact component; only type='script' is accepted.
- Do not rely on unsafe local fallback in production: without a working bubblewrap isolation driver, the default is fail-closed SANDBOX_UNAVAILABLE.
- Do not use it for arbitrary host commands, network access, or unbounded jobs; the sandbox applies namespace, environment, timeout, process, memory, and output controls.
- Do not omit revision pinning when reproducible execution matters; an explicit revision prevents running a different published snapshot.
Required scope
- memory:write is required on the MCP surface because execution is an authorized skill operation.
- The skill must resolve inside the authenticated personal or team scope; cross-scope skill IDs return ACCESS_DENIED.
Parameters
| Name | Type | Description |
|---|---|---|
script_path | string | Logical path or component ID of the script component to execute. |
slug | string · default: empty | Skill slug used to resolve the active skill. |
skill_id | string · default: empty | Stable skill identity alternative to slug. |
revision_id | string · default: empty | Optional revision pin; otherwise the published revision, then latest revision, is selected. |
input_args | object · default: empty object | JSON-compatible values encoded to the script's stdin. |
timeout_seconds | integer · default: 30 | Execution timeout constrained by ExecutionLimits to 1–60 seconds. |
Return schema
A JSON CloudSkillResponseEnvelope with kind='execution' and data containing execution_id, skill_id, revision_id, script_path, runtime, status, exit_code, stdout, stderr, truncation flags, optional output_data, duration_ms, memory_peak_bytes, cpu_time_ms, timestamps, and error_kind.
Examples
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
})Errors
- ACCESS_DENIED, SKILL_NOT_FOUND, or SKILL_ARCHIVED: the skill cannot be resolved in the caller's scope.
- REVISION_NOT_FOUND: the requested revision does not belong to the skill or no active revision exists.
- SCRIPT_NOT_FOUND or INVALID_COMPONENT_TYPE: the path is absent or names a non-script component.
- SANDBOX_UNAVAILABLE: the host has no working bubblewrap isolation driver and unsafe fallback is disabled.
- EXECUTION_TIMEOUT, RESOURCE_EXHAUSTED, or SCRIPT_EXECUTION_ERROR: the watchdog, resource limits, or script exit status ended execution.
Related tools
- recall_cloud_skill — Discover the skill and pin the revision/resource before executing.
- save_cloud_skill — Create the procedure and script component that can be executed.
- recall_context — Assemble bounded agent context around the execution task.
Source: Cloud Skills