From hallow-windmill
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.
How this skill is triggered — by the user, by Claude, or both
Slash command
/hallow-windmill:previewThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Use this skill any time the user wants to **see**, **open**, **navigate to**, **visualize**, or **preview** a flow, script, or app — and any time you've just finished writing one and want to offer visual verification.
Use this skill any time the user wants to see, open, navigate to, visualize, or preview a flow, script, or app — and any time you've just finished writing one and want to offer visual verification.
The Windmill dev page renders the flow graph / script editor, lets the user step through steps, and live-reloads on every save. It runs locally via wmill dev and is reached on a localhost port.
wmill dev runs in two modes; pick by asking what kind of URL whatever will display the preview needs.
--proxy-port <port>) — exposes the dev page on http://localhost:<port>/. Use it when the embedder you'll hand the URL to only accepts localhost URLs (most in-IDE / in-chat preview embedders do, because they sandbox cross-origin loads).wmill dev only runs the WebSocket back-channel for live reload. Use it when the URL will be opened in a regular browser tab.Default to direct unless you have a specific embedder that needs localhost.
wmill dev … (or wmill app dev …) yourself, capture the URL it prints, do whatever's next (open a tab, hand the URL to an embedder)..claude/launch.json. Some runtimes (currently the Claude Desktop / Claude Code MCP preview integration — tools prefixed with mcp__Claude_Preview__) can read a launch.json configuration and launch the dev server on demand when you invoke their preview tool. Only take this path if you actually have such a tool — otherwise nothing reads the file and wmill dev never starts.The two decisions compose. The common cases:
| Embedder | Needs localhost? | launch.json runtime? | What to do |
|---|---|---|---|
| Regular browser tab | No | n/a | Direct mode, you start it, give URL to user |
| IDE / chat preview pane that takes any URL | No | No | Direct mode, you start it, point the embedder at the printed URL |
| IDE / chat preview pane that only accepts localhost | Yes | No | Proxy mode, you start it, point the embedder at http://localhost:<port>/ |
| Claude Desktop / Code MCP preview | Yes | Yes | Proxy mode, write a launch.json entry, invoke the MCP tool |
Never start the proxy "just in case" — it adds the localhost hop for no benefit when no embedder needs it.
Use this when no launch.json-aware runtime is available, regardless of mode.
For flows / scripts:
# Direct mode — gives you the remote dev-page URL
wmill dev --path <wmill_path> --no-open
# Proxy mode — gives you a localhost URL that 302s to the remote dev page
wmill dev --proxy-port 4000 --path <wmill_path> --no-open
For apps:
cd <app_path>__raw_app && wmill app dev --no-open --port 4000
Each command prints the URL on stdout. Line shapes differ:
wmill dev --no-open (direct) prints Go to <url> with the full remote URL (workspace, token, path baked in).wmill dev --proxy-port prints Dev proxy listening on http://localhost:<port> — the URL to hand to an embedder is http://localhost:<port>/.wmill app dev --no-open prints 🚀 Dev server running at <url> — the local app server.Capture the URL with a loose match (the first https?://… token after startup) and either hand it to your embedder or relay it to the user: "Preview is running — open <url> in your browser." Don't construct the URL yourself; you don't have the workspace ID or auth token.
These commands are long-running — start them in the background, don't block waiting.
launch.json start the server (Claude Desktop / Code MCP only)Take this path when and only when an mcp__Claude_Preview__* MCP tool is exposed in your tool list. Skip it otherwise — without an MCP tool reading the file, wmill dev never starts.
Each flow / script / app gets its own named entry in the user's .claude/launch.json so multiple previews coexist without colliding — each entry pins a different port + path. Never reuse a generic "windmill" entry for different targets.
.claude/launch.jsonConvention: name the entry windmill: <wmill_path> (e.g. windmill: f/test/my_flow).
port for the next step.For flows / scripts:
{
"name": "windmill: f/test/my_flow",
"runtimeExecutable": "bash",
"runtimeArgs": ["-c", "wmill dev --proxy-port ${PORT:-4000} --path f/test/my_flow --no-open"],
"port": 4000,
"autoPort": true
}
For apps (*__raw_app/), wmill app dev is the equivalent — runs from the app folder, no --path:
{
"name": "windmill: f/test/my_app",
"runtimeExecutable": "bash",
"runtimeArgs": ["-c", "cd f/test/my_app__raw_app && wmill app dev --no-open --port ${PORT:-4001}"],
"port": 4001,
"autoPort": true
}
If .claude/launch.json doesn't exist yet, create it with the standard shell { "version": "0.0.1", "configurations": [...] }.
Point it at the entry you just added/found. Use http://localhost:<port>/ as the URL — the proxy's redirect at / is what appends the workspace ID, the auth token, and the path. Do NOT construct a /dev?... URL yourself.
The MCP tool launches the configuration on demand, so you don't need to start the wmill dev process manually.
If the user wants a programmatic test rather than a visual one:
wmill flow preview <path> -d '<args>'wmill script preview <path> -d '<args>'Both print the job result, are safe to run yourself, and don't deploy.
.claude/launch.json entry when no mcp__Claude_Preview__* tool is in your tool list. Nothing will read the file; the server never starts. Spawn wmill dev yourself instead.launch.json entry for every preview target. Each flow/script/app gets its own named entry on its own port — that's how multiple sessions coexist without one preview clobbering another.--path to retarget it. Add a new entry instead.http://localhost:<port>/dev?path=<X> yourself. The proxy's / redirect is what appends the workspace ID and auth token; bypassing it gives a broken page. Always use http://localhost:<port>/.wmill dev in the foreground (you'll hang). Always background.npx claudepluginhub hallow-inc/claude-plugins --plugin hallow-windmillGuides creation, editing, and verification of skills for AI coding agents using test-driven development with subagent scenarios. Use when authoring or debugging skills.