Skip to main content

​
Scripts

Scripts are the executable implementation behind skills. A script does focused work. A skill defines the workflow around that work.

​
Why scripts exist

Agents need a stable product surface. Builders need executable code. Scripts let OS keep both clean. 
agent sees skill
builder maintains script
OS connects them through the portal
This keeps users from thinking about file paths, command flags, runtime details, or implementation-specific helper tools.

​
Script responsibilities

A script should:
  • accept structured input
  • read context through approved OS services
  • return structured output
  • create artifacts through the artifact layer
  • respect capability checks
  • report safe errors
  • include trace metadata when OS provides it
A script should not bypass artifact tracking, approval guardrails, or execution logging for important work.

​
Script runtime

The product runtime target is Bun and TypeScript. Local OS should be able to install, run, and update scripts without requiring Docker. Hosted OS should run through the regular OpenSaaS deployment path first.

​
Script output

Scripts should return data OS can record.
OutputPurpose
statusWhether the script completed, paused, or failed.
summaryHuman-readable result.
artifactsArtifact records created or updated.
sourceRefsStructured records used.
approvalHuman decision request when needed.
errorSafe error code and message.

​
Local scripts

Local scripts may write temporary files while working, but durable outputs should become artifacts. Temporary output belongs in the OS temp or cache area. Durable output belongs in the artifact layer.

​
Builder guidance

When adding a script, also define or update the skill contract, required capabilities, result shape, artifact behavior, approval behavior, local validation command, and failure examples.