Execution Methods

The Skills Protocol provides two methods for executing code: execute_skill to run a skill's entrypoint, and run_code for LLM-written custom code.

execute_skill

Run a skill's entrypoint in an ephemeral sandbox.

{
  "jsonrpc": "2.0",
  "id": "4",
  "method": "execute_skill",
  "params": {
    "name": "salesforce.leads.sync",
    "version": "0.1.0",
    "args": {
      "sheet_blob": "blob:sheet-123",
      "env": "prod"
    },
    "input_blobs": ["blob:sheet-123"],
    "timeout_ms": 300000
  }
}

{
  "jsonrpc": "2.0",
  "id": "4",
  "result": {
    "status": "completed",
    "run_id": "run_9f2a",
    "summary": "Synced 742 leads (5 failed).",
    "output": {
      "updated_count": 742,
      "failed_count": 5
    },
    "output_blobs": [
      "blob:sync-log-42",
      "blob:failed-rows-1"
    ],
    "logs_preview": "Connected to Salesforce...\nSynced 742 leads...\n"
  }
}

{
  "jsonrpc": "2.0",
  "id": "4",
  "result": {
    "status": "failed",
    "run_id": "run_9f2a",
    "summary": "Invalid credentials.",
    "error": {
      "type": "AuthenticationError",
      "message": "Invalid Salesforce API key"
    },
    "logs_preview": "Connecting to Salesforce...\nAuth failed...\n"
  }
}

Execution flow

1. Runtime loads the skill's entrypoint module
2. Creates an isolated sandbox with resource limits
3. Mounts specified blobs and skills
4. Calls the export function with the provided args
5. Captures return value, stdout, stderr, and any created blobs
6. Tears down the sandbox

Output requirements

• output MUST be kept small (≤ 4KB serialized). Larger data MUST be written to blobs.
• logs_preview SHOULD be truncated to ≤ 2KB.

run_code

Execute LLM-written code in a sandbox with mounted skills and blobs.

{
  "jsonrpc": "2.0",
  "id": "5",
  "method": "run_code",
  "params": {
    "language": "python",
    "code": "from skills.salesforce.leads.sync import sync_leads\nfrom runtime import blobs\n\ndef main(args):\n    data = blobs.read_text(args['sheet_blob'])\n    result = sync_leads(data, env='prod')\n    return result",
    "entrypoint": "main",
    "args": {
      "sheet_blob": "blob:sheet-123"
    },
    "mount_skills": [
      "salesforce.leads.sync"
    ],
    "input_blobs": [
      "blob:sheet-123"
    ],
    "limits": {
      "timeout_ms": 300000
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": "5",
  "result": {
    "status": "completed",
    "run_id": "run_abcd",
    "summary": "Processed and synced 142 leads.",
    "output": {
      "synced": 142,
      "failed": 0
    },
    "output_blobs": [
      "blob:sync-log-42"
    ],
    "logs_preview": "Starting sync...\nProcessed 142 records...\n"
  }
}

Execution flow

1. Runtime creates a fresh sandbox
2. Mounts requested skills and blobs
3. Saves the code as a temporary module
4. Imports the module and calls the entrypoint function with args
5. Captures return value, logs, and created blobs
6. Tears down the sandbox

Available imports

Code can import:

• Mounted skills: from skills.<name> import <function>
• Runtime helpers: from runtime import blobs, log

Runtime helpers

blobs.read_text(blob_id: str) -> str
blobs.write_text(content: str) -> str
blobs.write_json(obj: dict) -> str

log.info(msg: str)
log.error(msg: str)

Response format

Both methods return the same response structure on success:

Error handling

There are two types of errors:

Protocol-level errors (RPC error)

{
  "jsonrpc": "2.0",
  "id": "5",
  "error": {
    "code": -32602,
    "message": "Invalid params"
  }
}

Examples:

• Invalid method name
• Missing required parameters
• Skill not found
• Authorization failure

Execution-level errors (in result)

{
  "jsonrpc": "2.0",
  "id": "5",
  "result": {
    "status": "failed",
    "run_id": "run_9f2a",
    "summary": "Skill execution failed.",
    "error": {
      "type": "RuntimeError",
      "message": "Traceback...: Invalid API key"
    }
  }
}

Examples:

• Skill code raises an exception
• Timeout exceeded
• Validation error in skill arguments

Limitations

Output size

• output field: max 4KB after serialization
• logs_preview: typically max 2KB
• Larger data MUST be written to blobs using runtime.blobs.write_text() or create_blob

Execution time

• Default timeout: runtime-specific (typically 5-10 minutes)
• Can be overridden with timeout_ms parameter
• Execution is terminated if timeout is exceeded

Resource constraints

Sandboxes enforce:

• CPU limits
• Memory limits
• Network restrictions (based on skill permissions)
• No filesystem access outside /workspace/

Next Steps