Resources and scripts – Docs

Applies to: StablEdge Desktop 0.4.4 and later

Besides SKILL.md, a Skill directory can hold reference documents, templates, assets, and scripts. They are the third of the three loading levels: they are used only when the Agent explicitly reads, copies, or runs them.

Directory layout

my-skill/
├── SKILL.md
├── reference.md          Reference document: read into the context on demand
├── references/           One file per topic when reference documents are many
│   ├── api.md
│   └── schema.md
├── scripts/              Scripts: only scripts here can be run by run_script
│   └── extract.py
└── assets/               Templates and assets: copy into the Workspace before use
    └── report-template.docx

Apart from scripts/, which is required for running scripts, the other directory names are conventions you can adjust as needed. Keep bundled files to what the task really needs, and leave out documents written for people, such as READMEs, installation notes, and change logs.

How the Agent accesses bundled files

Skills are installed in the StablEdge data directory, not in the Workspace. The Agent cannot reach these files with the general file or terminal tools, only through the skill tool:

Action	Purpose	Limits
`list_files`	List bundled files and their sizes; files with a declared resource role are labeled with it	Paged, at most 200 per page. Skips files and directories starting with `.`, `__pycache__`, `node_modules`, symbolic links, and the `SKILL.md` at the root.
`read_file`	Read a text file into the context, using `offset` / `limit` to read by line	Read as UTF-8; a file whose first 8 KB contain null bytes is treated as binary and rejected.
`copy_file`	Copy a file into the current Workspace; `dest` is a path relative to the Workspace, defaulting to the same relative path the file has in the Skill	A single file must not exceed 20 MB; writing into the Workspace goes through the host's security checks.
`run_script`	Run scripts under `scripts/` in the Sandbox, executed by the host	See Running scripts below.

When it loads a Skill, StablEdge hands the Agent the bundled file list (the first 20 items at most) together with these ways of reading them. So when you reference a bundled file in the body, just write a path relative to the Skill directory, for example reference.md or scripts/extract.py. Paths must stay inside the Skill directory: absolute paths, paths starting with ~, drive-letter paths, and paths that leave the directory with .. or symbolic links are all rejected.

Declaring resources

A Progressive Skill can declare bundled files and their resource roles in the resources part of the frontmatter. The following is excerpted from the built-in pdf Skill (builtin/pdf/SKILL.md, excerpt):

resources:
  - path: reference.md
    role: reference
  - path: scripts/extract_text.py
    role: executable
  - path: scripts/merge_pdfs.py
    role: executable

Validation rules for each item:

path: a path relative to the Skill directory; backslashes are converted to /; it cannot be empty, cannot be an absolute path or a drive-letter path, and cannot contain ..;
path cannot be SKILL.md, and the same path cannot be declared twice;
The declared file must really exist in the Skill directory;
role must be one of the four values in the table below.

Any non-compliant item makes the whole Progressive validation fail; for how that is handled, see Validation and fallback.

resources is parsed only when the frontmatter also has progressive; in a regular Skill it has no effect. Files that are not declared can still be listed, read, and copied: declaring them validates upfront that the files exist and marks their roles in the file list.

Resource roles

role	What fits here	How the Agent usually uses it
`reference`	Reference material such as API docs, data structures, and detailed specifications	`read_file` to read it into the context
`executable`	Scripts under `scripts/`	`run_script` to run them
`template`	Templates used to generate output from, such as document templates and project skeletons	`copy_file` into the Workspace, then edit
`asset`	Assets used directly in the output, such as images, fonts, and sample files	`copy_file` into the Workspace

Roles are labels for the Agent and do not change the limits of the actions themselves. For example, a file marked executable that is not under scripts/ still cannot be run with run_script.

Running scripts

For operations that need to be stable and repeatable (format conversion, batch processing, data extraction), writing a script into scripts/ fits better than having the Agent rewrite code every time. When the body says "run scripts/xxx.py with python", the Agent turns it into a run_script call that the host executes, rather than handing it to the shell.

Runtimes

The host picks its bundled runtime by file extension:

Extension	Runtime
`.py`	The Python bundled with the host (isolated mode, UTF-8)
`.js`, `.mjs`, `.cjs`	The Node.js bundled with the host
`.ts`, `.mts`, `.cts`	Node.js + tsx
`.sh`, `.bash`	Bash (Bash must be findable on the system)
No extension	Detected from the shebang on the first line: `python`, `python3`, `node`, `bash`, `sh`

Other types (including executable programs) are not supported.

Limits

Item	Limit
Script path	Must be inside the Skill's `scripts/` directory
Timeout	1–300 seconds, 60 seconds by default
Arguments	Passed one by one through `argv`, at most 64 items of no more than 8 KB each
Network	Uses the domains declared in the frontmatter by default; you can also specify them at call time with `network_hosts`, up to 16, accepting only exact HTTPS domains (no IPs, ports, wildcards, or URLs); pass an empty list to run offline
Workspace	Requires an available local Workspace for the current conversation, otherwise `SKILL_SCRIPT_WORKSPACE_UNAVAILABLE` is returned

Safety mechanisms

Every script run needs its own user confirmation, and the confirmation card shows the network domains that will be allowed;
The host first takes a snapshot of the Skill directory and checks its content hash, and runs the script only after confirming it matches what the Agent loaded, so the script cannot be swapped during the run;
Scripts run in the operating system Sandbox, with the current Workspace as the working directory;
Scripts of built-in Skills can run only after that Skill has been loaded;
Results come back to the Agent as status, exit_code, duration_ms, truncated, stdout, and stderr.

During install preview, a Skill that contains scripts or executable files is marked as high-risk (SKILL_INSTALL_EXECUTABLE_CONTENT), reminding users to check the content first.

Writing tips

Read arguments from the command line and write results to standard output or to a file inside the Workspace; do not hard-code paths;
On error, return a non-zero exit code and write the reason to standard error, so the Agent can adjust;
Depend only on the libraries bundled with the runtime where you can, and do not download or install dependencies inside the script;
Run it for real once before publishing, and confirm the output is what you expect.