Reference

execute_cloud_skill

Run one declared script component from an active Cloud Skill through the isolated execution engine.

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

Run one 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
})

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.

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