# Executing Scripts

> Markdown variant of <https://www.skillzdrive.com/docs/guides/executing-scripts>.

Run skill scripts in the cloud or locally — your agent handles the
details.

## Two ways to run scripts

When a skill has scripts (`hasScripts: true`), your agent can run
them in the cloud or download and execute them on your machine.

### Cloud execution (recommended)

Scripts run in an isolated cloud sandbox. Faster, safer, no local
setup. Dependencies are pre-installed automatically.

- **Cost**: credits per execution (5-min or 30-min sessions).
- **Speed**: fast — optimized containers with cached dependencies.
- **Safety**: fully isolated, destroyed after use.
- **Best for**: most tasks — data processing, file conversion, analysis.

Tools used: `skills_runScript`, `skills_readFile`,
`skills_closeSession`.

### Local execution (free)

Your agent downloads the script and runs it on your machine. Free,
but requires local dependencies and runs with your system
permissions.

- **Cost**: free — no credits charged.
- **Setup**: you manage dependencies (Python, pip packages, etc.).
- **Safety**: runs on your machine with your permissions.
- **Best for**: file uploads, local tools, cost-sensitive workflows.

Tools used: `skills_getScript` (or `skills_getScriptStream` if your
caller can't fetch signed URLs).

**Start with cloud execution.** It's the default for a reason. The
5-minute session is enough for most tasks. Use the 30-minute
session for long-running jobs like large dataset processing.
Switch to local only when you need local file access or want to
avoid credit usage entirely.

## Cloud session options

|  | 5-Minute Session | 30-Minute Session |
|---|---|---|
| Cost | Lower credits | Higher credits |
| Timeout | 5 minutes of inactivity | 30 minutes of inactivity |
| Best for | Quick tasks: file conversion, formatting, simple analysis | Heavy processing: large datasets, multi-step pipelines, ML tasks |
| Default? | Yes — recommended for most tasks | Only when needed |

## The Golden Path for cloud execution

```
listScripts → runScript(reuseSession: true) → readFile → closeSession
```

1. `skills_listScripts(skillSlug)` — get exact script names. Never guess.
2. `skills_runScript(skillSlug, scriptName, reuseSession: true)` — returns `sessionId` and `exitCode`.
3. `skills_readFile(sessionId, "/tmp/last_run.out")` — get stdout. Use `/tmp/last_run.err` for stderr.
4. `skills_closeSession(sessionId)` — free the sandbox. Or pass `closeAfter: true` on the final readFile.

Output is **not** in the `runScript` response — always read it via
`readFile`. Default returns the first 200 lines; if `hasMore` is
true, paginate with `startLine` and `limit`.

## Real-world examples

### Process a file in the cloud

> "Merge these three PDFs into one document."
> Agent: finds PDF skill → runs merge script in cloud → merged PDF ready in seconds.

### Long-running analysis

> "Analyze this 500MB CSV and generate a summary report with charts."
> Agent: runs analysis script (30-min session) → processes data → returns report.

### Run locally for free

> "Upload this skill file to my SkillzDrive."
> Agent: downloads upload script → runs locally (free) → skill uploaded to your drive.

### Chain multiple scripts

> "Extract text from this PDF, then translate it to Spanish."
> Agent: runs extract script → runs translate script (same session via `reuseSession: true`) → translated text ready.

## API keys and credentials

Some skills need third-party API keys to work — for example, a
skill that generates images might need a Gemini or OpenAI key. Your
agent will tell you if a credential is missing and what's needed.

Add API keys in your **SkillzDrive Account Settings** under
Credentials. They're encrypted and securely passed to scripts at
runtime — never stored in the sandbox.

If a script has `requiredEnvVars`, the user must configure those
API keys in their SkillzDrive account first.

## When things go wrong

| Issue | What happens | What to do |
|-------|--------------|------------|
| Missing credential | Script can't access a required API | Add the key in Account Settings → Credentials |
| Script timeout | Task took longer than session allows | Ask your agent to use a 30-minute session |
| Script error | Bug in the script itself | Your agent shows the error — try different input or a different skill |
| Insufficient credits | Not enough credits for cloud execution | Top up credits or run locally for free |
| Session expired (`session_not_found`) | Sandbox reaped after TTL | Re-run script with `reuseSession: true` to get a fresh sandbox |

## Next steps

- [Discovering skills](https://www.skillzdrive.com/docs/guides/discovering-skills.md)
- [MCP tools reference](https://www.skillzdrive.com/docs/reference/tools.md): every `skills_*` tool with arguments and the error response shape.