sky-workflow-authoring

name: sky-workflow-authoring description: Complete reference for authoring a valid Skylence .sky workflow — four-delimiter format, every meta and node option, all trigger types, the variable/template grammar, MUST/MUST NOT rules, and the full SKY-WF-* lint-code table. Use when writing or fixing a .sky file. category: skylence tags: [skylence, sky, workflow, authoring, lint, dag, reference]

Authoring a .sky Workflow

A .sky file defines a DAG of execution nodes plus trigger metadata. The parser uses four Unicode delimiter blocks; every opener and closer must be alone on its line. This skill is self-contained — no marketplace plugin is required to author or lint a workflow. It mirrors the machine-readable language surface emitted by skyway describe --format json.

Two Audiences (read this first)

A .sky file is written for two readers with opposite priorities. Get this right and everything else follows.

• The workflow body — ∆ prompt blocks, config keys, node ids — is for the AI that runs the node. Optimize purely for the model executing the task correctly. Be terse, telegraphic, machine-oriented. Do not care whether a human can read it, and do not pad or soften it for human eyes — the end user never reads the prompt body, by design. It only has to work. (Keep it English; see Language below.)
• The ※※ comment blocks are for the human. The exact opposite goal: a person should open the file and immediately understand what it does, why, and how the pieces connect. Optimize hard for human comprehension — clear prose and, when a picture helps, a diagram.

When the two pull in different directions, keep the prompt body machine-optimal and move every human-oriented explanation into a ※※ block.

Prompt body (wrong, AI defaults to this):

Steps:
1. Read the file at {{path}}.
2. Check each function for error handling gaps.
3. For each gap found, note the function name and what is missing.
4. Output a summary of your findings.

Prompt body (correct):

Read {{path}}. For each function missing error handling, note its name and what's missing. Output a summary.

Same instruction, one line, no ceremony. The model executes it identically.

Per-node ※※ annotations use the typed opener so the block is associated with a specific node. Body: one terse prose sentence describing the node's purpose, followed by the edges it carries (only edges that exist; never list absent ones). No key/value lists, no "Step N" prefixes.

Wrong (lists absent edges, uses list format):

※resolve※
Entry node. No LLM. Normalizes the issue reference.
depends_on: none (DAG root).
trigger_rule: n/a.
chain_from: none.
when: none.
※※

Correct:

※resolve※
Bash root node. Normalizes the issue reference into $SKY_OUTPUT_RESOLVE so all downstream nodes read it the same way regardless of trigger path.
※※

Only mention depends_on, trigger_rule, chain_from, when, or loop when they are actually set on the node.

Delimiter Blocks

⊕meta⊕   ⊕⊕     workflow metadata; required, exactly one per file
§<id>§   §§     DAG node config; <id> is the node identifier
∆<id>∆   ∆∆     node prompt body; pairs with §<id>§ by matching id; Claude receives it verbatim
※※       ※※     doc / comment block; content is discarded by the parser

Minimal Example

⊕meta⊕
name = "smoke-test"
description = "Manual smoke test"
output_style = "terse"
⊕⊕

§work§
bash = "echo 'hello'"
§§

⊕meta⊕ — Workflow Options

MCP Servers & Transports

mcp_servers is a JSON object; each entry picks a transport via type: stdio (subprocess), http (streamable HTTP, the modern remote transport), or sse (deprecated, do not use).

mcp_servers = {"remote": {"type": "http", "url": "http://localhost:9000/mcp"}, "local": {"type": "stdio", "command": "npx", "args": ["-y", "pkg", "mcp"]}}

Each node is a fresh Claude session, so transport choice is mostly about startup cost, not per-message latency:

http and in-process servers pay no per-session startup. stdio spawns a fresh subprocess on every node (cold-start cost), and parallel nodes spawning the same stdio server contend. Never use sse.

stdio + allowed_tools waits before the first turn. When a node both restricts tools (allowed_tools) and uses a stdio server, the runner holds the first prompt ~10s (SKY_MCP_READY_DELAY_MS) so the server finishes connecting first; otherwise the still-connecting tool is filtered from the model's view and reported "not available." http and in-process servers have no such wait. One more reason to prefer a shared http daemon for any server hit by multiple nodes.

Triggers

Set exactly one. With no trigger block, the workflow is manual — run via skyway run <name> (pass inputs with --var key=value). trigger.manual = true is tolerated and means the same thing.

Schedule timezone & DST. Schedule times resolve against an explicit IANA timezone — never the host's OS-local zone. Resolution order: trigger.schedule.timezone → the daemon's SKY_SCHEDULE_TIMEZONE config default → UTC. Because resolution uses IANA names, DST is handled by wall-clock: 0 3 * * * fires at 03:00 local in both winter and summer (the UTC offset shifts, the hour does not). At a spring-forward gap the run advances to the next valid time; at a fall-back overlap it fires once. Use a region name like Europe/Brussels, not a fixed offset or Local (rejected by SKY-WF-098). Note: trigger.cron (top-level) is not a trigger — the key is trigger.schedule.cron.

Node Common Keys (any node kind)

Node Kinds

Exactly one execution kind per node (more than one → SKY-WF-024; none → SKY-WF-022). loop is a modifier that wraps the body kind.

DAG Shape & Data Flow

depends_on defines edges; nodes with no path between them run in parallel. A diagram explains a non-trivial DAG far better than a node list:

          trigger  (manual | github | sky_event)
                       │
                       ▼
                  ┌─────────┐
                  │ classify│  haiku → JSON
                  └─────────┘
                 ╱     │      ╲      depends_on = ["classify"]   ← fan-out, run in parallel
                ▼      ▼       ▼     (each reads $SKY_OUTPUT_CLASSIFY)
            ┌──────┐┌──────┐┌──────┐
            │  a   ││  b   ││  c   │
            └──────┘└──────┘└──────┘
                 ╲     │      ╱      depends_on = ["a","b","c"]  ← join
                  ▼    ▼     ▼       trigger_rule = "one_success"
                  ┌───────────┐
                  │ synthesize│
                  └───────────┘
                       │  chain_from = "synthesize"  ← resumes the same Claude session
                       ▼
                  ┌─────────┐
                  │   fix   │ ⟲  loop.until.bash = "make test"   ← repeats body until exit 0 (loop.max)
                  └─────────┘
                       │  emit = { name = "fixed" }  → fires any workflow with trigger.sky_event.event = "fixed"
                       ▼
                     done

• Edge = depends_on. Upstream output reaches a node as $SKY_OUTPUT_<ID>.
• Parallel = sibling nodes sharing a dependency; trigger_rule decides when the join fires (all_done default, one_success, …).
• Session reuse = chain_from (solid intent, not a new edge — must also be in depends_on).
• Loop = ⟲, a modifier on the body kind.
• Fan-out to workers inside one node = spawn / council (not separate DAG nodes).

Diagram the flow when a picture beats words. When a workflow branches, fans out, loops, or gates — or any time a diagram conveys it faster than prose — put one in a ※※ comment block. Pick the most pragmatic form for the case, not a fixed one:

• ASCII (boxes/arrows, like the DAG above) — renders everywhere: terminals, plain diffs, any viewer. Default for structural DAG shape.
• Mermaid ```mermaid flowchart``` — renders on GitHub and most docs; best for larger branching graphs.
• Mermaid sequenceDiagram — when ordering and hand-offs between nodes/services matter more than the graph shape.
• Swimlanes (ASCII columns or Mermaid) — when responsibilities split across actors (e.g. workflow vs. GitHub vs. a human approver).

Choose whatever a human grasps fastest, and optimize the diagram for that human — this lives in a ※※ block, the human-facing half of the file. ※※ content is discarded by the parser, so any diagram costs nothing at runtime.

Templates & Variables

{{var}} expansion runs in prompt, http, and eval node fields — not in bash, script, or loop.until.bash (use $SKY_* env vars there).

• $SKY_OUTPUT_<ID> uppercases the node id and replaces - with _ (node code-review → $SKY_OUTPUT_CODE_REVIEW).
• Webhook payload keys flatten: issue.number → $SKY_ISSUE_NUMBER.
• --var foo=bar → {{foo}} in prompts, $SKY_FOO in bash.
• Filters (prompt/http/eval): {{var|json}} (quoted JSON value — required inside http.body JSON strings, else SKY-WF-047), {{var|urlencode}}.

when Grammar

• lhs == 'literal' / lhs != 'literal' — RHS must be single-quoted; a bareword silently never fires.
• Boolean literal: true | false | 1 | 0 (empty string = false).
• Source: evaluateCondition in the runner. Parse failure → SKY-WF-031; bad $node.output ref → SKY-WF-030.

Language

Write the workflow file entirely in English — name, every config key, all node ids, and every ∆ prompt body. A user's brief may arrive in any language; translate the intent, not the syntax. Only the ※※ comment blocks may be written in the user's spoken language.

MUST

• Lint before done: skyway lint <dir>/<file>.sky must pass. Errors are blocking.
• name matches the filename (kebab-case).
• Exactly one trigger (or none = manual).
• Quote the RHS of every when: when = "$x.output == 'value'".
• chain_from must appear in depends_on (SKY-WF-042) and target a prompt/command node (SKY-WF-043).
• Shell-quote every $SKY_* in bash: "$SKY_ISSUE_NUMBER", never bare.
• Declare every ${env:NAME} (used in mcp_servers/http) in secrets (SKY-WF-055).

MUST NOT

• Use {{var}} in bash, script, or loop.until.bash — use $SKY_* env vars.
• Use ${env:NAME} in prompt/bash/eval/script — it resolves only for mcp_servers/http (SKY-WF-057). In bash, read "$GITHUB_TOKEN" directly.
• Put a schedule under trigger.cron — the key is trigger.schedule.cron; a bare trigger.cron is not a recognized trigger.
• Use trigger.github_status: that key does not exist. For CI check-run failures use trigger.github.events = ["check_run.completed"] paired with trigger.github.check_run = { conclusion = "failure", name = "CI Name" }.
• Write output_format as a TOML inline table (output_format = { type = "object", ... }): the value must be a compact JSON string: output_format = {"type":"object","properties":{...}}.
• Write multi-line bash inline: use bash_file = "./scripts/<name>.sh" instead; triple-quoted strings cause a parse error.
• Commit secrets/tokens/.env.
• Change an output_format schema without updating the ∆ prompt that produces it.
• Run a destructive bash command without safety = "requires_permission" (SKY-WF-063).
• Add an emit that re-triggers a workflow already in the ancestor chain — the chain depth cap is 5 and over-cap dispatch is silently suppressed.
• Put Claude Code magic keywords — ultrathink, ultraplan, ultrareview, ultracode — in a ∆ prompt body. They are meant for interactive Claude Code, not workflow authoring. ultraplan/ultrareview are flagged by SKY-WF-061; ultrathink is not linted but still fires under skyway run (sky drives Claude via --input-format stream-json, not -p) — it injects a "reason thoroughly" nudge you did not intend and cannot control per-node. Express intent explicitly instead: write what you want the node to do, and set reasoning via effort = "..." or thinking = { ... } on the node, never via a keyword in the prose.

Lint Codes (SKY-WF-*)

Self-Check Before Finishing

1. Exactly one trigger (or none); name matches the filename.
2. Every ∆id∆ has a matching §id§; exactly one execution kind per node.
3. Every chain_from is in depends_on and targets a prompt/command node; every when RHS is quoted.
4. No {{var}} in bash/script/loop bodies; all $SKY_* shell-quoted; every ${env:NAME} declared in secrets.
5. If ui is set in ⊕meta⊕ or on any node, the referenced markdown file(s) exist relative to the .sky file (SKY-WF-103 warns when they do not). Workflow-level ui in ⊕meta⊕ additionally supports a changelog list (version, date, note) in its frontmatter.
6. skyway lint passes clean.