Workflow

Build automated pipelines with reusable components, data flow between nodes, and state management.

Security Scan

The skill's content generally matches a local, shell-based workflow runner, but there are notable inconsistencies around secret access and declared requirements (e.g., macOS keychain usage and notification tokens are used but not declared), so review before installing.

Purpose & Capability

The name/description (build automated pipelines) matches the instructions and many example flow scripts. The required binaries (jq, yq, curl, uuidgen, flock) are reasonable for this purpose. However, the docs repeatedly reference the macOS `security` keychain tool, fswatch/inotifywait, and runtime env vars like PUSHOVER_TOKEN/PUSHOVER_USER which are not listed in the declared required binaries or required env vars — this mismatch is unexpected.

Instruction Scope

SKILL.md and the component files instruct the agent to read secrets (via macOS keychain 'security') and to make network calls to arbitrary external services (e.g., api.example.com, pushover endpoints). Those actions are consistent with a workflow integrator, but the instructions also assume access to local keychain and to environment variables without declaring them. The webhook and webhook-server.sh example will write incoming payloads into the workspace and spawn background runs — this can cause external data to be stored and executed locally and should be audited for any workflows you add.

Install Mechanism

This is instruction-only with no install spec or remote downloads, so there is no additional install-time code being written or executed by the skill bundle itself.

Credentials

The skill does not declare any required environment variables but references runtime secrets in two forms: environment variables (e.g., PUSHOVER_TOKEN, PUSHOVER_USER) and OS keychain secrets accessed via `security find-generic-password`. Relying on the system keychain without declaring that requirement (nor including the `security` binary in required bins) is an incoherence. Requesting access to system-stored secrets is proportionate for an integration skill only if documented; here that documentation is inconsistent.

Persistence & Privilege

always:false (normal). The skill is instruction-only and does not request permanent platform privileges or to modify other skills or system-wide agent settings. It instructs workflows to create files under the workspace (workflows/...), which is expected for this kind of tool.

What to consider before installing

This skill describes a local, shell-based workflow system and will (by design) read secrets and call external APIs. Before installing: 1) Verify how you will supply secrets — the docs use macOS keychain (`security`) and also expect env vars like PUSHOVER_TOKEN; ensure those are intentional and available. 2) Inspect any workflow folders (workflows/flows/*) and each run.sh before running — run.sh executes curl and other commands and may call external endpoints. 3) If you are on Linux, check how secrets should be stored (the docs assume macOS keychain). 4) Be cautious about enabling incoming webhooks: the webhook example writes incoming payloads into the workspace and executes run.sh in the background. 5) If you need least privilege, limit network access and review/approve any external service credentials used by workflows. The skill appears to implement what it claims, but the omissions around declared binaries and env vars are reasons to inspect and harden before use.

Architecture

Workflows live in workflows/ with components and flows:

workflows/
├── index.md                 # Inventory with tags
├── components/
│   ├── connections/         # Auth configs
│   ├── nodes/               # Reusable operations
│   └── triggers/            # Event sources
└── flows/{name}/
    ├── flow.md              # Definition
    ├── config.yaml          # Parameters
    ├── run.sh               # Executable
    ├── state/               # Persistent between runs
    └── logs/

Quick Reference

Topic	File
Directory layout, naming, formats	structure.md
Data passing between nodes	data-flow.md
Cursor, seen set, checkpoint	state.md
Retry, rollback, idempotency	errors.md
Connections, nodes, triggers	components.md
Create, test, update, archive	lifecycle.md

Requirements

• jq — JSON processing
• yq — YAML config parsing
• curl — HTTP requests
• flock — Lock files to prevent concurrent runs
• Secrets in macOS Keychain (security find-generic-password)

Data Storage

• Location: workflows/ in workspace root
• State: flows/{name}/state/ — cursor.json, seen.json, checkpoint.json
• Logs: flows/{name}/logs/ — JSONL per run
• Data: flows/{name}/data/ — intermediate files between nodes

Core Rules

1. Data Flow Pattern

Each node writes output to data/{NN}-{name}.json. Next node reads it.

curl ... > data/01-fetch.json
jq '...' data/01-fetch.json > data/02-filter.json

Breaking this pattern = nodes can't communicate.

2. Error Declaration

Every node in flow.md MUST declare:

• On error: retry(N) | fail | continue | alert
• On empty: skip | continue | fail

Undefined behavior = unpredictable workflow.

3. Lock Files

Prevent concurrent runs:

LOCKFILE="/tmp/workflow-${NAME}.lock"
exec 200>"$LOCKFILE"
flock -n 200 || exit 0

4. State Files

File	Purpose
cursor.json	"Where did I leave off?"
seen.json	"What have I processed?"
checkpoint.json	"Multi-step recovery"

5. Component Reuse

Before creating new connections/nodes/triggers:

ls workflows/components/connections/
ls workflows/components/nodes/

Use existing. Update "Workflows Using This" when adding.

---

Related: For LLM-driven multi-phase processes, see the cycle skill.