Script SDK
The helpers a script imports to call tools, return a result, or rule on a call.
A script that runs in the sandbox can import @skilder-ai/script-sdk. Skilder puts the module beside your script before it runs, so there is nothing to install and nothing to declare.
Where it reaches
| You are writing | Import | Languages |
|---|---|---|
| a skill script | @skilder-ai/script-sdk | TypeScript |
| a guardrail rule | @skilder-ai/script-sdk/guardrail | TypeScript, JavaScript |
The two halves never meet. A skill script cannot reach go(), and a guardrail rule cannot reach callTool().
A script in Python or Bash gets no SDK, and neither does a skill script in JavaScript. Those return their result by printing it, and a guardrail rule in those languages writes the contract below by hand.
In a skill script
import { callToolJson, getSkillContent, output } from '@skilder-ai/script-sdk';
const policy = await getSkillContent({ name: 'refund-policy' });
const orders = await callToolJson<{ id: string }[]>('list_orders', { status: 'open' });
output({ policy: policy.instructions, open: orders.length });| Function | What it does |
|---|---|
output(value) | Return the script's result, or declare a file the script returns by passing its path (see Files in and out). The sandbox collects these on their own channel, so console.log stays debug output. |
callTool(name, args) | Call one of the tools attached to the skill. callToolText returns the first text block, callToolJson parses it. |
delegate(context, options) | Hand a task to a sub-agent that calls the skill's tools, and read back what it did. delegateText and delegateJson unwrap the same way. |
execute(path, args) | Run another script by its skill path, such as /Refund Policy/transform.py, with CLI-style arguments. executeText and executeJson unwrap it. |
listSkillContent(...), getSkillContent(ref), updateSkillContent(ref, patch) | Read and patch the skill's own references, scripts and assets. Addressed by id, which changes every time the skill is published, or by name: the file's name, or /<path>/<name> for one in a folder. A name resolves in the skill that owns the running script unless you pass a skillId. A bare name looks at the skill's root first, then in its folders, and tracking finds tracking.md when no file is named tracking; a name still matching two files is refused, naming each. |
resolveAsset(path) | Check that you can read an asset, such as /Reports/logo.png, and return its path to pass to a tool: @skilder-file:/<Skill>/<path>/<name>, the same path learn shows. A reference or a script is refused: read its text with getSkillContent. Nothing is downloaded: the tool you pass it to fetches its own copy. To read the bytes in the script, take the asset as an argument (see Files in). downloadAsset(path) is a deprecated name for the same call. |
The tools a script can call
A skill script, and any sub-agent it delegates to, calls only the tools attached to the skill, read and write alike. To give a script a tool, connect it to the skill: there is no separate list for scripts.
- A call to any other tool is refused, and the error names the tools the skill has. The script editor warns about a tool name the script calls that the skill lacks, when the name is written out in the call.
- Skilder's own tools, such as
learnorread_skilder_file, cannot be attached, so a script or its sub-agent never calls them. The sub-agent starts with the skill's tools and nothing else. - When two enabled tools attached to the skill share a name, a call to that name is refused, and the error names their MCP servers. Detach all but one.
- A script run with
execute()calls the tools of the skill that owns it, not those of the script that ran it. - When you run your draft, the draft's tools apply.
Files in and out
A skill script can take files as arguments and return files to its caller. This works in every language, with or without the SDK.
Files in
An argument that is an @skilder-file: path reaches the script as a local path. Pass it as the whole argument, or as the value of --name=<path>. One inside a longer argument is passed as written.
- An asset's path is the one
learnshows. A reference or a script is never passed as a file: pass its content, or read it withgetSkillContent. - An asset arrives as a writable copy. Editing it in place changes no stored asset.
- A file the agent uploaded with
upload_skilder_file, or one another tool or script returned, arrives as a fresh copy for each run. Its path stays valid until the workspace's file retention removes the file.
Files out
Every script gets two environment variables: SKILDER_OUTPUT_DIR, and SKILDER_OUTPUT_PREFIX, which is unique to each call.
- Create the file as
$SKILDER_OUTPUT_DIR/$SKILDER_OUTPUT_PREFIX<name>, directly in that folder. Create it new, never overwrite. - Declare it. In Python, Bash or JavaScript, print its absolute path on a line of its own. In TypeScript, pass the path to
output(path):console.logis never read as a declaration.
import os
path = os.path.join(os.environ["SKILDER_OUTPUT_DIR"], os.environ["SKILDER_OUTPUT_PREFIX"] + "report.csv")
with open(path, "x") as f:
f.write("order,amount\n")
print(path)Skilder keeps the file in your workspace and the caller gets an @skilder-file:/<fileId>/report.csv path in place of that line, which the agent reads or passes on. The file keeps the name you chose, without the prefix.
Skilder refuses the whole result when a declared file:
- is not named with this call's
SKILDER_OUTPUT_PREFIX, as a file the script was handed is not: to return an edited input, write it to a new file under the prefix - sits in a subfolder, or is a symlink or reached through one
- does not exist, or is not a regular file
- is over the per-file size limit, 10 MB unless your workspace's sandbox sets another
- cannot be kept in your workspace, for example because it is over the workspace's file size limit
A run that fails returns no files at all.
In a guardrail rule
import { getInput, go, nogo, debug } from '@skilder-ai/script-sdk/guardrail';
const to = String(getInput('to') ?? '');
debug('recipient', to);
if (to.endsWith('@acme.com')) go();
else nogo('Only recipients inside the company are allowed.');| Function | What it does |
|---|---|
getPhase() | PRE or POST. A rule set to run before and after the call runs once per phase. |
getToolName() | The name of the tool being called. |
getInputs(), getInput(name) | The call's arguments, carrying any rewrite an earlier rule applied. |
getResult() | The result the agent would receive. POST only. |
getCall() | The whole input object, for the fields with no accessor of their own. |
setOutput(payload) | Stage a rewritten payload for the go() that follows. |
go(payload?) | Let the call through, optionally rewriting the arguments or the result. |
nogo(reason) | Refuse. The reason reaches the agent, so say what would satisfy the rule. |
debug(...values) | Print a line Skilder keeps as debug output instead of reading it as the verdict. |
The first ruling stands: a later go() or nogo() is ignored. A hand-written rule that prints two verdicts gets none.
The raw contract
A rule in any language reads one JSON object on standard input:
{
"phase": "PRE",
"tool": { "name": "send_email", "kind": "WRITE", "readOnlyHint": false },
"roleId": "0xr1",
"userId": "0xu1",
"input": { "to": "someone@acme.com" },
"result": null
}and prints one back:
{ "ruling": "NO_GO", "reason": "Only recipients inside the company are allowed." }{"ruling":"GO"} lets the call through, and a payload beside it replaces the arguments on PRE or the result on POST. Anything else is an evaluation error, which refuses the call when the rule is blocking.
To print without breaking the verdict, mark the line: print("#skilder:debug ...") in Python, echo "#skilder:debug ..." in Bash.
Python dependencies
A Python skill script can use third-party packages it declares. The sandbox installs them before the script runs. It never guesses them from your import lines.
Declare them in one of two places:
-
Inline, in a block at the top of the script (the standard PEP 723 format):
extract.py # /// script # dependencies = ["pypdf>=4"] # /// import pypdfOnly its
dependenciesare read: the script runs on the sandbox's Python whateverrequires-pythonsays. -
In a
requirements.txtreference added to the skill, in the standard pip format, one package per line. The name must be exactlyrequirements.txt. When the skill holds several, the script uses the one in its own folder, else another one in the skill.
When both exist, the script gets the packages from both. A package named in both must satisfy both: pypdf>=4 in one and pypdf<6 in the other installs a version in between, while pypdf<5 against pypdf>=5 cannot be installed and the run fails, naming both declarations. A script that declares neither runs on plain Python, with the standard library only.
The sandbox downloads and caches the packages, so the first run is slower. The install counts against the script's time limit (see Limits).
When a dependency is missing, the run fails with an error you can act on:
- A script that imports a package it did not declare names the missing module, and says how to declare it.
- A package that cannot be installed (an unknown name, a bad version, no network) returns the installer's own explanation.
This covers skill scripts, whether an agent runs them or you click Test Script. Guardrail rules get no install.
Limits
- Only a Python skill script gets dependencies installed, from what it declares. Every other script, and every guardrail rule, runs on the standard library and the SDK only.
- A skill script gets 30 seconds. Each SDK call that waits on Skilder resets that clock, and the whole run is capped at 5 minutes.
- Every guardrail rule covering one call shares 3 seconds per phase.
Next
- Test a script, to run one with your own arguments before an agent calls it.
- Build a skill, to add a script to a skill.

