Skip to content
Skills Library
AI & agents · Automation

workflow

/workflow

Run a multi-step skill workflow declared in a workflow YAML file. Use when the user asks to "run the workflow at <path>", "execute workflow <name>", "run the <name> workflow", "chain these skills", "compose <skill-a> and <skill-b>", or supplies a path to a `.yaml` workflow definition. Arguments follow a `key=value` grammar: the first positional value is the workflow file path, remaining `key=value` pairs are workflow inputs. The runner executes steps strictly in order, halts on the first non-zero exit, and writes a summary JSON to the workflow directory.

Licence
MIT
Last repository change
24.09.2026

Assessment and security

95/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content30 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
2
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 24.09.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Run a multi-step skill workflow declared in a workflow YAML file. Use when the user asks to "run the workflow at <path>", "execute workflow <name>", "run the <name> workflow", "chain these skills", "compose <skill-a> and <skill-b>", or supplies a path to a `.yaml` workflow definition. Arguments follow a `key=value` grammar: the first positional value is the workflow file path, remaining `key=value` pairs are workflow inputs. The runner executes steps strictly in order, halts on the first non-zero exit, and writes a summary JSON to the workflow directory.

Triggers from the description

run the workflow at <path>execute workflow <name>run the <name> workflowchain these skillscompose <skill-a> and <skill-b>
Original author description

Run a multi-step skill workflow declared in a workflow YAML file. Use when the user asks to "run the workflow at <path>", "execute workflow <name>", "run the <name> workflow", "chain these skills", "compose <skill-a> and <skill-b>", or supplies a path to a `.yaml` workflow definition. Arguments follow a `key=value` grammar: the first positional value is the workflow file path, remaining `key=value` pairs are workflow inputs. The runner executes steps strictly in order, halts on the first non-zero exit, and writes a summary JSON to the workflow directory.

How it works

  1. Task Tracking
  2. Phase 1: Parse arguments
  3. Phase 2: Load and validate workflow YAML
  4. Phase 3: Resolve the step plan
  5. Phase 4: Execute steps sequentially
  6. Phase 5: Write summary and report
Original SKILL.md headings · 551 lines, 2,315 words
SKILL.md preview
---
name: workflow
description: >
  Run a multi-step skill workflow declared in a workflow YAML file.
  Use when the user asks to "run the workflow at <path>", "execute
  workflow <name>", "run the <name> workflow", "chain these skills",
  "compose <skill-a> and <skill-b>", or supplies a path to a `.yaml`
  workflow definition. Arguments follow a `key=value` grammar: the
  first positional value is the workflow file path, remaining
  `key=value` pairs are workflow inputs. The runner executes steps
  strictly in order, halts on the first non-zero exit, and writes a
  summary JSON to the workflow directory.
tools: Bash, PowerShell, Read, Write, Glob, Grep, Agent, TaskCreate, TaskUpdate
---

# Workflow Runner

Execute a workflow YAML file step-by-step. Each step runs one skill,
by default in a fresh subagent (`claude` type, or the step's `agent:`),
or in this conversation when the step sets `inline: true`. The runner
captures each step's output and threads it forward
through `${{ steps.<id>.output }}` interpolation. The full format is
specified in [`references/format.md`](../../references/format.md) —
read that file first if the user's workflow uses features that aren't
in the example below.

**This skill writes files.** It writes a `workflow-output.json` and
per-step output captures inside `$WORKFLOW_DIR` (default
`./.workflow-runs/<name>-<timestamp>/`). It does not modify the
workflow definition itself.

---

## Task Tracking

Before doing any work, call `TaskCreate` for each phase below. Call
`TaskUpdate` (status `in_progress`) when you begin a phase and
`TaskUpdate` (status `completed`) when you finish it.

- Parse arguments
- Load and validate workflow YAML
- Resolve inputs and step plan
- Execute steps sequentially
- Write summary and report

---

## Phase 1: Parse arguments

The invocation is one positional path (the workflow file) followed by
zero or more `key=value` pairs. Quote values that contain spaces with
double quotes.

```text
workflow path/to/document-and-deploy.yaml feature_count=5
```

Use the parser below — it is intentionally similar to the
`scaffold` skill's parser so contributors recognise the grammar.

```bash
python3 - <<'EOF'
import json, re, shlex, sys

# Substitute the user's invocation text below.
RAW = """<<USER_ARGS>>"""

result = {"workflow_path": None, "inputs": {}, "errors": []}
try:
    tokens = shlex.split(RAW)
except ValueError as e:
    result["errors"].append(f"Could not parse arguments — {e}. Quote values with spaces.")
    tokens = []

positional = []
for tok in tokens:
    if "=" in tok:
        key, _, value = tok.partition("=")
        if not re.match(r"^[a-z_][a-z0-9_]*$", key):
            result["errors"].append(f"Input name '{key}' must be lowercase letters/digits/underscores.")
            continue
        result["inputs"][key] = value
    else:
        positional.append(tok)

if not positional:
    result["errors"].append("Missing workflow file path. Usage: workflow <path.yaml> [key=value …]")
elif len(positional) > 1:
    result["errors"].append(f"Expected one positional workflow path; got {positional}.")
else:
    result["workflow_path"] = positional[0]

with open("/tmp/workflow-args.json", "w") as f:
    json.dump(result, f, indent=2)
print(json.dumps(result, indent=2))
EOF
```

If the parser reports any `errors`, stop and surface them. Do not
guess a path.

---

## Phase 2: Load and validate workflow YAML

Read the workflow file via the `Read` tool first so the user sees its
contents in the transcript, then parse and validate it with the
Python helper. The helper uses only the standard library — no
`pyyaml` dependency, the parser only needs to handle the workflow
subset of YAML described in `references/format.md`.

```bash
python3 - <<'EOF'
import json, re, sys

args = json.load(open("/tmp/workflow-args.json"))
path = args["workflow_path"]
try:
    src = open(path).read()
except OSError as e:
    print(json.dumps({"errors": [f"Cannot read workflow file: {e}"]}))
    sys.exit(1)

# ───── Minimal YAML parser tailored to the workflow schema ─────
#
# Supports: top-level scalars, single-level `inputs:` list of maps,
# `steps:` list of maps with nested `args:` / `inputs:` maps. Quoted
# strings ("…", '…') survive verbatim; unquoted scalars are stripped.
# Comments (`# …`) and blank lines are ignored.

INDENT = re.compile(r"^( *)(.*)$")

def lines(text):
    out = []
    for raw in text.splitlines():
        m = INDENT.match(raw)
        if not m:
            continue
        indent, rest = m.group(1), m.group(2).rstrip()
        # Strip end-of-line comments unless inside a quoted string.
        in_quote = False; q = None; trimmed = []
        for ch in rest:
            if in_quote:
                trimmed.append(ch)
                if ch == q:
                    in_quote = False
            else:
                if ch in ('"', "'"):
                    in_quote = True; q = ch; trimmed.append(ch)
                elif ch == "#":
                    break
                else:
                    trimmed.append(ch)
        rest = "".join(trimmed).rstrip()
        if not rest:
            continue
        out.append((len(indent), rest))
    return out

def unquote(s):
    s = s.strip()
    if (len(s) >= 2) and ((s[0] == s[-1] == '"') or (s[0] == s[-1] == "'")):
        return s[1:-1]
    if s.lower() == "true":  return True
    if s.lower() == "false": return False
    if re.fullmatch(r"-?\d+", s):       return int(s)
    if re.fullmatch(r"-?\d+\.\d+", s):  return float(s)
    return s

def parse_block(tokens, start, base_indent):
    """Parse a YAML block starting at tokens[start] with given indent.
       Returns (value, next_index). Auto-detects map vs list."""
    if start >= len(tokens):
        return None, start
    indent, rest = tokens[start]
    if rest.startswith("- "):
        items = []
        i = start
        while i < len(tokens):
            ind, r = tokens[i]
            if ind != base_indent or not r.startswith("- "):
                break
            first_kv = r[2:].strip()
            # `- key: value` starts a map at indent base_indent+2
            if ":" in first_kv:
                key, _, val = first_kv.partition(":")
                pseudo = [(base_indent + 2, f"{key}:{val}")]
                # Pull in continuation lines that are children of this list item
                j = i + 1
                while j < len(tokens) and tokens[j][0] > base_indent:
                    pseudo.append(tokens[j])
                    j += 1
                item, _ = parse_block(pseudo, 0, base_indent + 2)
                items.append(item)
                i = j
            else:
                items.append(unquote(first_kv))
                i += 1
        return items, i
    # Map
    mapping = {}
    i = start
    while i < len(tokens):
        ind, r = tokens[i]
        if ind != base_indent or r.startswith("- "):
            break
        if ":" not in r:
            return None, i
        key, _, val = r.partition(":")
        key = key.strip()
        val = val.strip()
        if val == "":
            child, ni = parse_block(tokens, i + 1, ind + 2 if i + 1 < len(tokens) else ind)
            # if no child, treat as null
            mapping[key] = child if child is not None else None
            i = ni
        else:
            mapping[key] = unquote(val)
            i += 1
    return mapping, i

toks = lines(src)
parsed, _ = parse_block(toks, 0, 0)

# ───── Validation ─────
errors = []
if not isinstance(parsed, dict):
    errors.append("Top level of workflow YAML must be a map.")
else:
    for required in ("name", "description", "steps"):
        if required not in parsed:
            errors.append(f"Missing required top-level field: {required}.")
    steps = parsed.get("steps") or []
    if not isinstance(steps, list) or len(steps) == 0:
        errors.append("`steps` must be a non-empty list.")
    else:
        seen_ids = set()
        slug_re = re.compile(r"^[a-z][a-z0-9-]*[a-z0-9]$")
        for idx, step in enumerate(steps):
            if not isinstance(step, dict):
                errors.append(f"Step {idx} is not a map."); continue
            sid = step.get("id")
            if not sid or not slug_re.match(str(sid)):
                errors.append(f"Step {idx} has invalid id '{sid}'. Must be kebab-case.")
            elif sid in seen_ids:
                errors.append(f"Duplicate step id '{sid}'.")
            else:
                seen_ids.add(sid)
            if not step.get("skill"):
                errors.append(f"Step '{sid or idx}' missing `skill`.")
            if "agent" in step and (not isinstance(step["agent"], str) or not step["agent"].strip()):
                errors.append(f"Step '{sid or idx}': `agent` must be a non-empty agent type name.")
            if "inline" in step and not isinstance(step["inline"], bool):
                errors.append(f"Step '{sid or idx}': `inline` must be true or false.")
            if step.get("inline") is True and "agent" in step:
                errors.append(f"Step '{sid or idx}': `inline: true` and `agent` are mutually exclusive.")

# ───── Resolve inputs ─────
defaults = {}
required_inputs = []
for inp in (parsed.get("inputs") or []):
    if not isinstance(inp, dict): continue
    nm = inp.get("name")
    if "default" in inp:
        defaults[nm] = inp["default"]
    else:
        required_inputs.append(nm)

supplied = args["inputs"]
resolved = {**defaults, **supplied}
for nm in required_inputs:
    if nm not in resolved:
        errors.append(f"Missing required input '{nm}'. Supply as `{nm}=...`.")

with open("/tmp/workflow-parsed.json", "w") as f:
    json.dump({"workflow": parsed, "inputs": resolved, "errors": errors}, f, indent=2)

print(json.dumps({"workflow": parsed, "inputs": resolved, "errors": errors}, indent=2))
if errors:
    sys.exit(1)
EOF
```

If validation fails, surface every error to the user and stop. Do not
attempt to execute a half-valid workflow.

---

## Phase 3: Resolve the step plan

For each step, build the concrete arguments object by substituting
every `${{ … }}` placeholder. Steps may only reference earlier steps;
forward references are a validation error.

```bash
python3 - <<'EOF'
import json, re, sys

data = json.load(open("/tmp/workflow-parsed.json"))
wf, inputs = data["workflow"], data["inputs"]
steps = wf["steps"]

EXPR = re.compile(r"\$\{\{\s*(.+?)\s*\}\}")

resolved_steps = []
output_store = {}  # step_id -> (placeholder — actual output filled later)

errors = []

def resolve_value(value, step_idx):
    if isinstance(value, dict):
        return {k: resolve_value(v, step_idx) for k, v in value.items()}
    if isinstance(value, list):
        return [resolve_value(v, step_idx) for v in value]
    if not isinstance(value, str):
        return value
    matches = list(EXPR.finditer(value))
    if not matches:
        return value
    # Whole-string substitution preserves type when value is exactly one expression.
    if len(matches) == 1 and matches[0].group(0) == value.strip():
        return resolve_expr(matches[0].group(1), step_idx, raw=True)
    # Embedded — stringify.
    out = []
    last = 0
    for m in matches:
        out.append(value[last:m.start()])
        out.append(str(resolve_expr(m.group(1), step_idx, raw=False)))
        last = m.end()
    out.append(value[last:])
    return "".join(out)

def resolve_expr(expr, step_idx, raw):
    parts = expr.split(".")
    head = parts[0]
    if head == "inputs":
        if len(parts) != 2:
            errors.append(f"Step {step_idx}: invalid inputs expression `{expr}`.")
            return ""
        return inputs.get(parts[1], "")
    if head == "steps":
        if len(parts) < 3 or parts[2] != "output":
            errors.append(f"Step {step_idx}: invalid steps expression `{expr}`.")
            return ""
        ref_id = parts[1]
        seen_before = any(s["id"] == ref_id for s in steps[:step_idx])
        if not seen_before:
            errors.append(f"Step {step_idx}: `${{{{ steps.{ref_id}.output }}}}` references step that has not run yet.")
            return ""
        # Marker — the executor replaces this at runtime with the captured output.
        if len(parts) == 3:
            return f"<<OUTPUT:{ref_id}>>"
        return f"<<OUTPUT:{ref_id}:{'.'.join(parts[3:])}>>"
    errors.append(f"Step {step_idx}: unknown expression head `{head}`.")
    return ""

for idx, step in enumerate(steps):
    args = step.get("args") or step.get("inputs") or {}
    resolved = resolve_value(args, idx)
    resolved_steps.append({
        "id": step["id"],
        "skill": step["skill"],
        "description": step.get("description", ""),
        "agent": step.get("agent") or "claude",
        "inline": step.get("inline") is True,
        "args": resolved,
    })

with open("/tmp/workflow-plan.json", "w") as f:
    json.dump({"plan": resolved_steps, "errors": errors}, f, indent=2)

print(json.dumps({"plan": resolved_steps, "errors": errors}, indent=2))
if errors:
    sys.exit(1)
EOF
```

If any errors come back, halt and report.

---

## Phase 4: Execute steps sequentially

Create the workflow directory once, then loop through the plan.

```bash
WF_NAME=$(python3 -c "import json; print(json.load(open('/tmp/workflow-parsed.json'))['workflow']['name'])")
TS=$(date -u +%Y%m%dT%H%M%SZ)
WORKFLOW_DIR=".workflow-runs/${WF_NAME}-${TS}"
mkdir -p "$WORKFLOW_DIR"
echo "$WORKFLOW_DIR" > /tmp/workflow-dir
echo "Workflow output directory: $WORKFLOW_DIR"
```

For each step in the plan, in order:

1. Read the resolved `args` from `/tmp/workflow-plan.json`. Replace
   every `<<OUTPUT:<id>[.<key>]>>` marker by reading
   `$WORKFLOW_DIR/<id>/output.json` (parse as JSON if possible,
   otherwise treat as raw text):

   ```bash
   STEP_ID="<step-id-from-plan>"
   mkdir -p "$WORKFLOW_DIR/$STEP_ID"
   STEP_OUTPUT="$WORKFLOW_DIR/$STEP_ID/output.json"
   STEP_STDOUT="$WORKFLOW_DIR/$STEP_ID/stdout.log"
   STEP_STDERR="$WORKFLOW_DIR/$STEP_ID/stderr.log"
   ```

2. Run the step. How depends on the plan entry's `inline` and `agent`:

   **Default (`inline: false`) — spawn a subagent** via the `Agent`
   tool with `subagent_type` set to the plan entry's `agent` (`claude`
   unless the step named another agent type). Never use the skill
   name as the agent type — skills are not agent types. A step sets
   `agent:` when a dedicated agent definition fits it better than the
   catch-all, e.g. one with a narrower tool list. Whatever the type,
   it must have the `Skill` tool, because the prompt below tells it
   to invoke the skill. Pass the resolved arguments in the prompt so
   the matching skill picks them up via the `Skill` tool. The agent
   gets `$WORKFLOW_OUTPUT=$STEP_OUTPUT` and `$WORKFLOW_DIR=$WORKFLOW_DIR`
   exported via the prompt context.

   The prompt template looks like:

   ```
   You are running step `<id>` of workflow `<wf_name>`.

   Invoke the `<skill>` skill using the Skill tool with these
   arguments (convert the JSON object to space-separated key=value
   pairs):
   <pretty-printed JSON of step.args>

   IMPORTANT: invoke the skill via the Skill tool — do NOT
   reimplement the skill's logic yourself. The skill has its own
   SKILL.md with specific instructions, scripts, and output formats
   that must be followed exactly. Reimplementing it inline produces
   incorrect results (wrong file formats, missing idempotence
   checks, skipped validation).

   Output convention:
   - Write a JSON summary to $WORKFLOW_OUTPUT=$STEP_OUTPUT.
   - If you cannot, your captured stdout will be used as the
     output value for downstream steps.

   Halt with a non-zero exit if you cannot complete the step.
   ```

   **`inline: true` — run the skill in this conversation.** Invoke
   the `Skill` tool yourself with the step's skill and its arguments
   as space-separated `key=value` pairs. No subagent is spawned, so
   the step costs no fresh context; use it for small, mechanical
   skills (a sync, a file rewrite). Shell state does not persist
   between tool calls, so start **every** shell command you run for
   the skill with the concrete paths, e.g.
   `export WORKFLOW_OUTPUT="<STEP_OUTPUT path>" WORKFLOW_DIR="<WORKFLOW_DIR path>"; …`
   (PowerShell: `$env:WORKFLOW_OUTPUT = "<path>"; …`). The skill's own
   `$WORKFLOW_OUTPUT` checks then work unchanged.

   When the skill finishes, write its final report (the text you would
   otherwise have printed as the step's result) to `$STEP_STDOUT`, so
   the stdout fallback in step 3 has something to capture when the
   skill wrote no `output.json`. Then return to this loop: the next
   action is step 3 below, not anything the skill's own report
   suggests. If the skill fails, write the error to `$STEP_STDERR` and
   treat it exactly like a subagent that exited non-zero.

3. After the step returns, capture its output:

   ```bash
   if [ -s "$STEP_OUTPUT" ]; then
     echo "Step $STEP_ID produced structured output."
   else
     # Fallback: copy stdout into output.json as a stringified field.
     python3 - "$STEP_STDOUT" "$STEP_OUTPUT" <<'EOF'
   import json, sys, pathlib
   src, dst = sys.argv[1], sys.argv[2]
   text = pathlib.Path(src).read_text() if pathlib.Path(src).exists() else ""
   pathlib.Path(dst).write_text(json.dumps({"stdout": text}))
   EOF
   fi
   ```

4. If the step failed (agent exited non-zero, or the inline skill failed), stop the loop immediately. Record
   the failure for the summary in Phase 5.

Steps must run **strictly sequentially** — do not request parallel
execution. v1 of the format reserves parallelism for a future
revision.

---

## Phase 5: Write summary and report

Write `$WORKFLOW_DIR/workflow-output.json` and print a concise
markdown summary.

```bash
python3 - <<'EOF'
import json, datetime, pathlib, os, sys

wf = json.load(open("/tmp/workflow-parsed.json"))["workflow"]
plan = json.load(open("/tmp/workflow-plan.json"))["plan"]
inputs = json.load(open("/tmp/workflow-parsed.json"))["inputs"]
workflow_dir = open("/tmp/workflow-dir").read().strip()

steps_summary = []
status = "success"
for step in plan:
    out = pathlib.Path(workflow_dir) / step["id"] / "output.json"
    err = pathlib.Path(workflow_dir) / step["id"] / "stderr.log"
    if not out.exists():
        status = "failed"
        steps_summary.append({
            "id": step["id"], "skill": step["skill"], "status": "skipped"
        })
        continue
    summary = {
        "id": step["id"], "skill": step["skill"],
        "status": "success", "output_path": f"{step['id']}/output.json",
    }
    if err.exists() and err.stat().st_size > 0:
        summary["status"] = "failed"
        summary["stderr"] = err.read_text()[:2048]
        status = "failed"
    steps_summary.append(summary)

report = {
    "workflow": wf.get("name"),
    "status": status,
    "started_at": datetime.datetime.utcnow().replace(microsecond=0).isoformat() + "Z",
    "finished_at": datetime.datetime.utcnow().isoformat() + "Z",
    "inputs": inputs,
    "steps": steps_summary,
}
pathlib.Path(workflow_dir, "workflow-output.json").write_text(json.dumps(report, indent=2))
print(json.dumps(report, indent=2))
EOF
```

### Report format (printed back to the user)

```
## Workflow — <name>

Status: <success | failed>
Run directory: <WORKFLOW_DIR>
Inputs:
  - <name>: <value>

Steps:
  ✓ <id>  (<skill>) — output at <id>/output.json
  ✗ <id>  (<skill>) — failed, see <id>/stderr.log
  - <id>  (<skill>) — skipped (earlier step failed)
```

### Do not:

- Suggest re-running the workflow with a different definition. The
  workflow file is the user's contract; the runner only executes.
- Modify the workflow YAML itself. Even if it has cosmetic issues,
  surface them as warnings; the user fixes them in their own PR.
- Run subsequent steps after a failure. Halt immediately so the user
  sees the failure before any compensating work has run.
Files in this package (2)
  • SKILL.md 20 KB
  • evals/evals.json 8 KB

Versions

RepositoryScoreLicence
This page · dan323/easier-life-skills95MIT
jeremylongshore/tons-of-skills-marketplace100MIT
SimHacker/moollm100MIT
mlophez/polix-ai100Apache-2.0
stellarie/minimal-agent-kit100MIT
waynesutton/builder-skills100Apache-2.0
claude-world/director-mode-lite100MIT
DawitLemmaBalcha/agent-workflow100MIT
zhinkgit/embeddedskills100MIT

Database snapshot: 13.11.2026 · package version e6e5cfad1eec (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 98skills-workflow
    Interactive skills workflow for chaining multiple skills where the output of step i becomes the input of step i-1. Use when you need to: (1) Chain multiple skills together in a specific order, (2) Pass outputs between skills as inputs, (3) Execute complex multi-step workflows…
  • 90agent-workflow
    Create, update, run, resume, or continue agent workflows. Use when the user asks to create or fix workflow JSON, execute an existing workflow, run a workflow with a prompt, resume a workflow run, or continue the next node in a waiting multi-step workflow.
  • 100workflow-runner
    在 Claude Code / OpenClaw / Cursor 中直接运行 agency-orchestrator YAML 工作流——无需 API key,使用当前会话的 LLM 作为执行引擎。当用户提供 .yaml 工作流文件或要求多角色协作完成任务时触发。
  • 100conductor
    Validate, run, and execute workflows; creating new workflows when explicitly asked. Use when orchestrating AI agents via YAML workflow files, executing an existing workflow, debugging execution, configuring routing between agents, setting up human-in-the-loop gates, or…
  • 92create-workflow
    Conversational guide for creating valid YAML workflow definitions. Use when asked to "create a workflow", "new workflow definition", "build a workflow", "workflow YAML", "define workflow steps", or "workflow from template".
  • 92create-workflow
    Conversational guide for creating valid YAML workflow definitions. Use when asked to "create a workflow", "new workflow definition", "build a workflow", "workflow YAML", "define workflow steps", or "workflow from template".

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.