slice icon Context Slice

Sauna Runtime Environment

Understanding the runtime helps you write skills that execute correctly.

File Paths at Runtime

After skill installation, files are located at:

./skills/sauna/{skillId}/
├── SKILL.md                           # Main skill instructions
├── scripts/{codeId}.js                # Code bullets (executable)
├── references/{sliceId}.md            # Knowledge files (slices)
├── references/recipes/{taskId}.md     # Task files
├── references/skills/{depId}/         # Nested dependencies
├── cache/                             # Cached data (user IDs, etc.)
└── PREFERENCES.md                     # User preferences for this skill

Session Files

The ./session/ directory holds ephemeral files for the current task. Code writes structured JSON here; inference reads and interprets it. Files are auto-deleted after task completion—no manual cleanup needed.

Pattern: Code step → writes to session folder → Inference step reads it

Connections

Sauna uses Pipedream for integrations, supporting OAuth, API keys, and custom auth across 2000+ services. Skills declare required connections via metadata.discovery.connections: [gmail, slack]. The executor uses connect_account to establish them before running code.

Always verify connections before making API calls—code receives tokens as PLACEHOLDER_TOKEN when credentials are injected.

Executor Constraints

The executor agent follows compiled markdown literally. Key limitations:

  • No source access — Cannot read original YAML, only compiled output
  • No improvisation — Cannot recover from errors autonomously
  • Package declaration required — All npm/pip packages must be in code metadata
  • Args must be explicit — Missing args cause execution failure

Write defensively: assume the executor has only your compiled output and cannot fill in gaps.

File References in Output

When referencing files users can open, use the file:// protocol with relative paths. Format: file:// followed by the path, optionally with line number (:42) or line and column (:42:10). This enables clickable links in the Sauna UI.

PREFERENCES.md

Each skill can have a PREFERENCES.md file containing user preferences. This file is automatically loaded when the agent reads SKILL.md. Skills should READ preferences but NOT modify them—the preference watcher agent handles updates.