Workflow builder

Skill jimezsa/opencolab/projects/SKILLS/workflow-builder

🐙 Accelerating Scientific Discovery — Turn your research into an always-on autonomous lab

Install

npx -y skills add jimezsa/opencolab --skill workflow-builder

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

11 stars11 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

Author, validate, run, and oversee OpenColab project workflows that coordinate multiple agents through bounded loops, decisions, and human gates.

SKILL.md

5.5 KB, as published. Nobody here has run it

Workflow Builder Skill

Use this skill when the user wants to compose multiple agents into a repeatable workflow such as draft → review → judge, judge-and-retry, parallel reviews followed by a merge, or any other bounded coordination of agents.

This skill authors and operates workflows through the OpenColab CLI. It is not the workflow engine itself. The CLI/runtime owns parsing, execution, persistence, and human gate handling.

Source of truth

Workflow definitions live at: projects/<project_id>/workflows/<workflow_id>/workflow.xml
Workflow runs live at: projects/<project_id>/workflows/<workflow_id>/runs/<run_id>/
Each run folder contains RUN.md (with YAML frontmatter), state.json, status.json, events.jsonl, inputs/initial.md, and steps/<step_id>/.

Never edit state.json, status.json, or events.jsonl by hand. They are written by the runtime.

Allowed step types

agent — runs one project agent with a generated prompt. Required: id, type="agent", agent, <prompt>. Optional: <output name="..." />.
decision — runs one project agent and expects a strict <workflow-decision action="..." next="..." reason="..." /> line in the response. Required: id, type="decision", agent, <prompt>, <choices>.
human_gate — pauses the run for human input. Required: id, type="human_gate", <prompt>. Optional: allow="approve,stop,retry,edit,branch".
merge — concatenates prior outputs into a single named value. Required: id, type="merge", at least one <input name="..." />, <output name="..." />.
terminate — explicitly ends the run with a status of success, failed, or stopped.

Loops must be bounded

Every <loop> requires at least one of:

maxIterations="<n>"
maxSteps="<n>"
maxRuntimeMinutes="<n>"

Unbounded loops are rejected during validation.

Prompt references

Inside any <prompt> you can use template variables:

${input.<name>} — values supplied when starting the run.
${<output_name>} — named outputs from prior steps (<output name="..." />).
${<step_id>.output> — fallback reference for any step's raw output text.

Author a workflow

Decide which project agents will play each role (drafter, reviewer, judge).
Pick a template:
- blank for an empty scaffold
- review-loop for draft → review → judge with a bounded loop
- judge-and-retry for draft → judge → retry-or-stop

Run:

opencolab workflow create --workflow-id <id> --from review-loop

Edit the generated projects/<project_id>/workflows/<id>/workflow.xml to reference real project agents, set the loop bound, and tighten prompts.

Validate before running:

opencolab workflow validate --workflow-id <id>

Run a workflow

opencolab workflow run --workflow-id <id> --input "<task text>"
# or
opencolab workflow run --workflow-id <id> --input-file inputs.json --wait true

--input <text> is shorthand for { "task": "<text>" }. For richer inputs, pass --input-file <path> or --input-json '{"foo":"bar"}'.

--wait true blocks the CLI until the run reaches a terminal or paused state and streams events as they happen.

Observe a run

Latest status snapshot:

opencolab workflow status --run-id <runId>

Tail events:

opencolab workflow logs --run-id <runId> --follow

List all runs:
```
opencolab workflow runs
```

Stop, resume, approve

opencolab workflow stop --run-id <runId> — cooperative stop.
opencolab workflow resume --run-id <runId> — resume a paused run.
opencolab workflow approve --run-id <runId> --decision continue|stop|retry|branch:<step>|edit — record a human gate decision. Use --values-json '{"task":"..."}' with --decision edit to update inputs before continuing.

Decision contract for `decision` steps

Decision agents must end their response with a single line that looks like:

<workflow-decision action="continue" next="draft" reason="The answer still misses two constraints." />

action: continue, stop, branch, needs_human, or fail.
next: target step id when action="continue" or action="branch".
reason: short justification; surfaced in events.jsonl and Studio.

You may use <choice name="..." /> blocks under <choices> to give the agent a fixed menu. The agent can pick a choice by name via:

<workflow-decision action="continue" choice="continue" />

If the decision block is missing or invalid, the run pauses for human review by default (or fails if onInvalid="fail" was declared on the step).

Memory isolation

Workflow steps do not pollute normal agent chat memory. The runtime uses a workflow-scoped session identity for every agent call and surfaces results through the workflow's run folder, not the agent's memory/Session/.

Things to avoid

Do not author workflows outside the project workflows directory.
Do not invent step types beyond the supported list — the validator rejects unknown tags and unsupported step type attributes.
Do not skip loop bounds. Bounded loops are mandatory.
Do not pretend this skill executes workflows. Always shell out to the CLI.