Skip to main content
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:
FieldPurpose
nameRequired slug. It matches the script directory name.
display-nameOptional user-facing title with spaces and punctuation.
descriptionRequired description used for discovery and display.
argumentsOptional ordered list of script input names.
argument-hintOptional metadata for script inputs, including type, default, description, and UI hints.
disable-model-invocationPrevents the agent from auto-invoking the script unless referenced explicitly.
always-includeIncludes the full SKILL.md in the agent’s context on every prompt turn.
metadata.idStable 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:
ExpressionResolves 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 modeFrontmatter updateEffect
Not Includeddisable-model-invocation: true and always-include: nullScript not included in context, but searchable by the agent.
Description Includeddisable-model-invocation: false and always-include: nullAgent will read the script if description is relevant.
Script Includedalways-include: true and disable-model-invocation: nullThe 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 expressionMeaning
0 9 * * *Every day at 9:00 AM
0 9 * * 1Every 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.