Technical reference

This section is for developers and technical operators. You do not need these details to build automations in Script.it, but they are useful if you want to inspect generated scripts, review changes, debug a run, or connect Script.it to internal systems.

Script file structure

Each script is stored as a small project with a SKILL.md definition, source files, and optional assets.

workspaces/<workspace_id>/my-script/
├── SKILL.md               # Script definition in Agent Skills format
├── scripts/               # Source files used by executable blocks
│   ├── fetch-data.py
│   └── process.sh
└── assets/                # Persistent files bundled with the script

The AI agent manages these files for you. You can still inspect them, export them, or version-control them if your workflow requires it.

Script definition

SKILL.md is the canonical Script.it script definition. It follows the Agent Skills format: YAML frontmatter at the top, followed by a Markdown body. Each fenced yaml block in the body declares one executable block or one Markdown block.

---
name: weekly-summary
description: Fetch report data and post a summary to Slack
disable-model-invocation: true
metadata:
  id: scr_xxxxxxxxxx
---

## About this script

Fetches the latest report data, creates a concise summary, and posts it to Slack.

```yaml
id: fetch-report
name: Fetch report data
description: Fetches source data and writes `report.json`.
source_file: ${{ src }}/fetch-report.py
output_directory: fetch/
```

```yaml
id: post-to-slack
name: Post summary to Slack
description: Posts the generated summary to Slack.
source_file: ${{ src }}/post-to-slack.py
output_directory: slack/
inputs:
  report_path: ${{ block.fetch-report.output_directory }}/report.json
```

Blocks run in document order. Prose between block fences is preserved as documentation in the script view.

Frontmatter fields

Common frontmatter fields:

Field	Purpose
`name`	Required slug. It matches the script directory name.
`display-name`	Optional user-facing title with spaces and punctuation.
`description`	Required description used for discovery and display.
`arguments`	Optional ordered list of script input names.
`argument-hint`	Optional metadata for script inputs, including type, default, description, and UI hints.
`disable-model-invocation`	Prevents the agent from auto-invoking the script unless referenced explicitly.
`always-include`	Includes the full `SKILL.md` in the agent’s context on every prompt turn.
`metadata.id`	Stable script ID assigned by Script.it. Do not edit it manually.

Legacy scripts may still contain flow.script.yaml, but new and migrated scripts use SKILL.md.

Path expressions

Use ${{ ... }} expressions in block fields and inputs:

Expression	Resolves to
`${{ src }}`	The script’s `scripts/` source directory.
`${{ script.assets }}`	The script’s persistent `assets/` directory.
`${{ session.data_files }}`	The current session’s runtime data directory.
`${{ builtins }}`	Built-in Script.it blocks.
`${{ inputs.name }}`	A script-level input value.
`${{ block.fetch.outputs.file }}`	A value returned by an earlier block.
`${{ block.fetch.output_directory }}`	The output directory for an earlier block.

Use script assets for persistent files. Use session data files and block output directories for run-specific output.

Runtime files

Script files and session files are separate:

Script files live with the script and are shared across sessions.
Script assets live in assets/ and persist across sessions.
Session files live in the session’s data_files/ directory and contain outputs from a specific run.
Runtime artifacts, logs, and block outputs belong to the session that produced them.

Each session runs in an isolated sandbox environment. That keeps concurrent sessions from reading or overwriting each other’s runtime files.

Agent context fields

Script.it uses SKILL.md frontmatter to control Agent context:

App mode	Frontmatter update	Effect
Not Included	`disable-model-invocation: true` and `always-include: null`	Script not included in context, but searchable by the agent.
Description Included	`disable-model-invocation: false` and `always-include: null`	Agent will read the script if description is relevant.
Script Included	`always-include: true` and `disable-model-invocation: null`	The full script content is included in the agent context.

See Agent context for user-facing guidance.

Trigger payloads

When a trigger starts a script, Script.it creates a new session and passes event data into that session.

Webhook triggers receive an HTTP POST body.
Integration event triggers receive event data from the connected tool.
Schedule triggers receive schedule metadata such as the scheduled time.

For scripts that need to read trigger data directly, the payload is available as a session file, commonly data_files/trigger_event.json.

Schedules and cron

Schedule triggers can use presets or a custom five-field cron expression:

minute  hour  day-of-month  month  day-of-week

Examples:

Cron expression	Meaning
`0 9 * * *`	Every day at 9:00 AM
`0 9 * * 1`	Every Monday at 9:00 AM
`/30 * * *`	Every 30 minutes

Cron expressions use the timezone configured on the trigger.

Integrations and credentials

Integrations use OAuth, API keys, or custom headers depending on the connected service. Script.it stores integration credentials in encrypted form and does not write them into script source files or chat history. Custom integrations use a two-layer model:

The integration type defines the API shape: base URL, auth mode, OAuth URLs, docs URL, logo, and schema.
The connection stores one user’s credentials for that type.

Connections and custom integration types can be shared with workspaces. Connection sharing delegates use of the owner’s upstream account. Custom type sharing exposes the API definition so each member can connect their own credentials.

Versioning

Script changes are tracked as version snapshots. If the agent changes a script and you want to go back, ask it to revert the last change or restore a previous version.

Get started

Scripts

Sessions

Triggers

Integrations

For developers

Account

Technical reference

Script file structure

Script definition

Frontmatter fields

Path expressions

Runtime files

Agent context fields

Trigger payloads

Schedules and cron

Integrations and credentials

Versioning

​Script file structure

​Script definition

​Frontmatter fields

​Path expressions

​Runtime files

​Agent context fields

​Trigger payloads

​Schedules and cron

​Integrations and credentials

​Versioning

Script file structure

Script definition

Frontmatter fields

Path expressions

Runtime files

Agent context fields

Trigger payloads

Schedules and cron

Integrations and credentials

Versioning