hallow-windmill

Use when running `wmill` CLI commands — `script preview/run`, `flow run`, `job get/list/logs`, `workspace`, `version`. Triggers on "run the script", "check the job", "preview vs run", inspecting failures via `wmill job`, "wmill generate-metadata no scripts found", "wmill bootstrap", "wmill --workspace", "active workspace footgun", "script preview wrong worker tag". Covers preview-vs-run decision (no push — sync banned at Hallow), workspace flags, JSON output handling, bootstrap-before-generate-metadata for hand-written scripts, `wmill script preview` ignoring sidecar tag (nondeterministic worker routing).

MUST use when opening the Windmill dev page / visual preview of a flow, script, or app. Triggers on words like preview, open, navigate to, visualize, see the flow/app/script, and after writing a flow/script/app for visual verification.

Use when creating a Windmill **raw app** — single-file HTML/JS UI served from Windmill, not a low-code App Editor app. Triggers on "raw app", "html app in windmill", "single-page app on windmill", custom JS dashboards. NOT for: low-code App Editor apps, flow construction (use write-flow).

Use when creating, reading, or wiring a Windmill **resource** — typed credential/connection (DB, API, S3, OAuth) stored in the workspace and referenced from scripts/flows. Triggers on "add a resource", "database credentials in windmill", "resource type", `.resource.yaml`, `.resource-type.yaml`, "change resource_type", "resource_type immutable", "apify Cloud only", "linked secret variable", "auto-linked variable", "apify_api_key". Covers resource types, secret fields, referencing from script main signatures, `resource_type` immutability (delete-recreate procedure), two flavors of secret storage (standalone `f/platform_secrets/<domain>__<name>` vs auto-linked at resource path), Cloud-only OAuth RTs vs `*_api_key` self-host variants (apify).

Use when configuring a Windmill **schedule** — cron-based or interval trigger that runs a script/flow on a timer. Triggers on "schedule a script", "run every X minutes", "cron in windmill", `.schedule.yaml`, "schedule churns on every push", "perpetual ~ modify diff", "email field reverts", "cron_version v2", "ws_error_handler_muted", "Invalid range for Days of Week", "schedule deployer-stamped". Covers cron syntax (6-field, name-based DOW ranges), timezone, payload binding, enabled/disabled state, the three churn-preventing fields (cron_version + ws_error_handler_muted + email), deployer-stamped `email`/`permissioned_as`, multi-segment underscore filenames. NOT for: webhook/event triggers (use triggers skill).

Use when configuring a Windmill **trigger** — HTTP route, webhook, WebSocket, Postgres CDC, MQTT, or SQS entry point that invokes a script or flow on Hallow's customized-OSS Windmill. Triggers on "webhook in windmill", "http route", "sqs trigger", "websocket trigger", "postgres cdc", `.trigger.yaml`, "trigger 404 / not found", "trigger ACL", "permissioned_as", "headers in preprocessor", "create disabled trigger", "is_static_website required". Covers trigger types + availability matrix (SQS enabled via Hallow fork deviation; Kafka/NATS/GCP/Azure/email still EE-blocked), payload mapping, auth, retry, folder-ACL gating on route lookup, workspaced URL form (`/api/r/<ws>/<route>`), deployer-stamped `permissioned_as`, create-then-disable for staged rollout, multi-segment underscore filenames. NOT for: time-based runs (use schedules skill), Kafka/NATS/GCP/Azure/email triggers (EE-only, still not available on Hallow).

Use when granting, revoking, or auditing **item-level access** on an existing Windmill entity — narrower than its containing folder's default ACL. Triggers on "who can access this resource", "give X write access to Y", "share this script with just", "narrow this to just the finance team", "revoke access from", "grant access to a single resource/script/flow/trigger", "extra permissions", "Share" (Windmill UI `⋮` menu). Covers the `extra_perms` mechanism across all 21 Windmill entity kinds (script, flow, app, raw_app, resource, variable, schedule, folder, group_, volume, and all 11 trigger types), its 3-state read/write semantics, the folder-owner precondition, and the `volume` creator-only exception. NOT for: creating a new entity (use `resources`/`triggers`/`schedules`/`write-flow`), durable department-level access boundaries (use a top-level folder — see `docs/folders-groups.md`), or workspace role assignment (admin/developer/operator — that's a workspace setting, not an item grant).

Front door for any QUESTION about Hallow's self-hosted Windmill — how it works, how to do something, why something behaves a certain way, or where the docs are. Triggers whenever the user mentions windmill, wmill, or windmill.platform.hallow.app and is ASKING rather than requesting a build/debug/setup action. Fires on "how do I ... in windmill", "does windmill support ...", "what's the deal with ... in windmill", "why does windmill ...", "explain windmill ...", "where are the windmill docs", "what is ... in our windmill", or similar question-shaped requests. Thin router — defers to windmill-build for "build me X", windmill-discover for "does a tool exist", windmill-debug for "my job failed", windmill-onboarding for first-time setup; otherwise points at the platform docs and the matching pattern skill. NOT for build/debug/discover/setup actions (those skills own them).

Capture a Windmill behavior, gotcha, or plugin-doc-contradiction discovered during development. Writes both a memory entry (tag windmill-plugin-update) and a scratchpad bullet in WINDMILL_LEARNINGS.md. Use after any session where Windmill behavior surprised you, a doc was wrong, or a CLI/API quirk needed a workaround. Triggers on phrases like "capture this learning", "windmill quirk", "doc was wrong", "this is a gotcha".

Diagnoses Windmill tool failures in plain language. Triggers when the user says their script/flow/app failed, errored, crashed, didn't run, returned nothing, hung, timed out, ran but did the wrong thing, "my tool is broken", "Windmill is throwing an error", "the job failed", "nothing happens when I click", "the schedule didn't fire". Fetches the most recent failing job, reads logs + result, summarizes the error in plain English, and suggests a concrete next step. Anchored on windmill / wmill. Does NOT diagnose dev-loop setup problems — `/hallow-windmill:wmill-doctor` owns that.

Catalogs existing Windmill tools so users can reuse instead of rebuild — and flags when no tool is needed at all. Triggers when the user asks what tools exist, what's already built, is there something that does X, does anyone have a script for Y, what's in the toolbox, "show me available tools", "list scripts in folder Z", "is there an atom for Slack/S3/Snowflake", "can I already do X", "what can I do with windmill", "what's on windmill.platform.hallow.app", or wants to find a tool by description on windmill / wmill. Combines the static toolbox catalog (curated, high-quality), live MCP listings (everything in the workspace), and the no-build path (direct read-only MCP tools for one-off pulls/exports/lookups) and returns a plain-English verdict the user can act on.

Reference and discovery skill for Hallow's Windmill onboarding. Loads when a new engineer says they want to set up Windmill, install wmill, connect to windmill.platform.hallow.app, mint a Windmill token, configure the Windmill MCP, get started with Hallow's Windmill instance, or asks any "I'm new and need to get up and running" question. Surfaces the authoritative procedure at `${CLAUDE_PLUGIN_ROOT}/docs/onboarding.md` and points the engineer at `/hallow-windmill:wmill-setup` to run it end-to-end and `/hallow-windmill:wmill-doctor` to verify it later.

Reference skill for Hallow Windmill usage and development patterns. Loads when an engineer is creating or modifying a Windmill script, flow, app, trigger, schedule, or resource in the Hallow `dev` workspace, asking about shared atoms (slack_post, error_to_slack, assert_principal), the `f/platform_secrets/` pattern, `wmill.yaml` sync rules, the local-yaml-first workflow, `permissioned_as` elevation, or any "how do I do X in our Windmill setup" question that isn't first-time onboarding. ALSO answers how-does-it-work questions about windmill / wmill — "how do windmill schedules handle timezones", "how does permissioned_as work", "why does my windmill script behave like this", "explain how our windmill setup works" — routing to the right pattern doc. Surfaces the authoritative procedure at `${CLAUDE_PLUGIN_ROOT}/docs/patterns.md` plus companion docs.

Use when creating a Windmill **flow** — multi-step orchestration of scripts via `flow.yaml`, with branches, loops, suspends, approvals, error handlers. Triggers on "build a flow", "chain scripts", "windmill workflow", `flow.yaml`, "tag fargate", "S3 step in flow", "AccessDenied cyclic structures", "early_return HTML", "inline script import", "rename inline script", "flow sync up to date but diff persists". Covers flow scaffolding (`wmill flow new`), preprocessor/failure modules, loops, branches, approvals, sync HTTP-trigger response shaping via `early_return`, sandbox S3 steps MUST set `tag: fargate` (Fargate task role has the IAM grant; EC2 default worker does not — symptom is a masked cyclic-structure error), no cross-inline relative imports, wmill-owned inline-script filenames (hand-rename is non-convergent). NOT for: single-script work (use write-script-* skill), code-defined workflows (use write-workflow-as-code).

Use when writing a Windmill TypeScript script on the **Bun runtime** with full npm ecosystem and `windmill-client` available. Default TS choice for fastest execution + npm imports (Hallow's primary script language, 63+ in production). Triggers on "windmill ts script", "bun script", uses `import` from npm packages, "runScriptAsync queued but never ran", "wmill.createToken is not a function", "WM_TOKEN env var", "dispatch flow vs script", "S3 step tag fargate". Covers main() shape, RT namespace for resource types, S3 helpers (loadS3File/writeS3File), preprocessor scripts, dispatch fn choice (`runScriptAsync` vs `runFlowAsync` — wrong fn = silent no-op against flow paths), worker-injected `process.env.WM_TOKEN` (no `wmill.createToken` on top-level SDK), sandbox S3 → flow module needs `tag: fargate`. Also fine for pure stdlib/fetch-only scripts — just skip the npm imports.

Use when writing a Windmill DuckDB script — in-process analytical SQL via the `duckdb` runtime. Triggers on "duckdb query", local-file analytics, CSV/Parquet inspection, "DuckLake catalog", "ATTACH ducklake", "duckdb $name bind", "duckdb %%name%% literal substitution", "DuckDB rejected bucket name with dash", "DuckLake on S3 fails". Covers attach syntax, parameter binding ($name vs %%name%% restrictions — both reject S3 paths in common positions), result shape, DuckLake catalog file CANNOT live on S3 (use Postgres/MySQL catalog), Hallow rule "DuckDB should be Python" (prefer python3 script + `import duckdb` for non-trivial work), sandbox-bucket jobs require `tag: fargate`.

Use when writing a Windmill PostgreSQL script — SQL targeting Postgres via the `postgresql` runtime. Triggers on "postgres query", "pg script", `RETURNING *`, `::jsonb`, `$1` param markers. Covers parameter binding, resource auth, and JSONB handling.

Use when writing a Windmill Python script (`.py`, python3 runtime). Triggers on "python script in windmill", `def main(...)`, `import wmill`, pip requirements in script header. Covers main signature, wmill SDK usage, dependency pinning, and wmill CLI lifecycle.

Use when writing or modifying a Windmill **Workflow-as-Code** (WAC) script — TS/Python scripts that orchestrate steps using `@workflow`, `@task`, `step`, `sleep`, `task_script`, `task_flow` decorators instead of `flow.yaml`. Triggers on `workflow()`, `@task`, `taskScript(...)`, `task_flow(...)`, checkpoint/replay semantics. NOT for: YAML flows (use write-flow), one-shot scripts without orchestration (use write-script-*).