Skip to content

AGENTS.md

Latest commit

 

History

History
177 lines (114 loc) · 14.2 KB

AGENTS.md

File metadata and controls

177 lines (114 loc) · 14.2 KB
Raw

Windmill CLI Agent Instructions

Managed by wmill. This file is regenerated on wmill init and wmill refresh prompts — edit AGENTS.md (user-owned) for project-specific instructions instead.

You are a helpful assistant that can help with Windmill scripts, flows, apps, and resources management.

Important Notes

  • Every new entity MUST be created using the skills listed below.
  • Every modification of an entity MUST be done using the skills listed below.
  • User MUST be asked where to create the entity. It can be in its user folder, under u/{user_name} folder, or in a new folder, /f/{folder_name}/. folder_name and user_name must be provided by the user.

Script Writing Guide

You MUST use the write-script-<language> skill to write or modify scripts in the language specified by the user. Use bun by default. For Workflow-as-Code scripts, use the write-workflow-as-code skill.

Flow Writing Guide

You MUST use the write-flow skill to create or modify flows. When a new flow needs to be created, YOU run wmill flow new <path> yourself (with --summary and optional --description) to scaffold the folder and flow.yaml, then edit flow.yaml to fill in modules and schema. Do NOT scaffold the folder + yaml by hand and do NOT tell the user to run wmill flow new. If path or summary are missing from the user's request, ask via AskUserQuestion (one call, all missing fields) — never invent them. See the write-flow skill for the procedure.

Raw App Development

You MUST use the raw-app skill to create or modify raw apps. When a new app needs to be created, YOU run wmill app new yourself with --summary, --path, and --framework flags (and any other relevant flags). Do NOT ask the user to run it. If you don't have the values for those flags, ask the user via AskUserQuestion (one call, all missing fields) — never invent them. See the raw-app skill for the full procedure.

Triggers

You MUST use the triggers skill to configure HTTP routes, WebSocket, Kafka, NATS, SQS, MQTT, GCP, Azure, Email, or Postgres CDC triggers.

Schedules

You MUST use the schedules skill to configure cron schedules.

Resources

You MUST use the resources skill to manage resource types and credentials.

Visual Preview

You MUST use the preview skill any time the user wants to see/open/visualize/preview a flow, script, or app in the dev page — and after writing one, when offering visual verification. The skill picks between an MCP-embedded proxy (one named launch.json entry per target) and direct mode (URL handed to the user) based on what tools you have.

CLI Reference

You MUST use the cli-commands skill to use the CLI.

Running and previewing local changes

Local previews exist for every entity type and don't deploy:

  • wmill script preview <path> -d '<args>' — run a local script.
  • wmill flow preview <flow_path> -d '<args>' — run a local flow.yaml.
  • wmill app dev — live-reload dev server for raw apps.

Argument shapes and per-language details live in the write-script-<lang>, write-flow, and raw-app skills.

Keeping metadata in sync

After editing a script, flow inline script, or app runnable, its generated metadata can go stale. wmill-lock.yaml stores a content hash per item, so a change that adds or removes an import or changes a script's arguments invalidates that hash and leaves the .lock (resolved dependencies) and .script.yaml (the input schema that drives the auto-generated args UI) out of date. wmill generate-metadata regenerates them and refreshes the hashes. Leaving them stale produces spurious diffs in git-sync and CI.

This only writes local files — it is not a deploy — but it re-resolves dependencies, so it can bump unpinned versions (the same as deploying from the UI; expected, not a bug). So by default offer it and run it once the user agrees, rather than running it silently after every edit. YOU run the command (never tell the user to run it); the choice is only whether to confirm first.

After running it, diff the regenerated lockfiles (e.g. git diff the .lock / .script.lock files): if any dependency versions changed, tell the user what bumped (e.g. requests 2.31.0 → 2.32.0) so they can catch an unwanted change before deploying. Do this even under Metadata: auto — it is information, not a confirmation gate. Pin a version in code to keep it fixed.

With no path argument it regenerates only the items whose metadata is actually stale (content hash drifted), workspace-wide — not everything. The set can be larger than the file you edited for two reasons: imports propagate (editing a script that others import marks every importer stale too, so their locks regenerate against the new code — by design, since a lock must reflect the imported code), and any pre-existing drift is swept in. If it touches items you didn't expect, run wmill generate-metadata --dry-run first — it lists each stale item with a reason (content changed or depends on <path>) and changes nothing, so you can see why each is in scope. To narrow it, pass a folder or file path (wmill generate-metadata f/foo); add --strict-folder-boundaries to touch only items literally inside that folder (it warns about stale importers outside the folder that it skipped — they resurface as stale on the next unscoped run).

Save the preference so you don't ask every session. If the user wants metadata regenerated automatically after edits (or always confirmed first), record it in the project-specific instructions section of AGENTS.md (user-owned — never overwritten by wmill refresh prompts), e.g. a line like Metadata: auto (run wmill generate-metadata after edits) or Metadata: ask first. Read that line first on later sessions and follow it.

If the on-disk .lock and .script.yaml are already correct and only wmill-lock.yaml needs its hashes refreshed (hash drift, or bootstrapping missing entries), use wmill generate-metadata rehash — it re-records hashes from disk with no backend round-trip and no dependency changes.

Deploying

There are two ways local changes reach the workspace. Pick based on how the repo is wired, not habit.

Detecting the setup

Before deploying, check whether this repo has a GitHub Actions (or other CI) workflow that runs wmill sync push on push. That workflow is the signal that pushing a branch will deploy:

  • Look for .github/workflows/*.yml (or other CI configs) that invoke wmill sync push, wmill deployment commands, or similar.

If such a workflow exists → use git push (Option A). Otherwise → use wmill sync push directly (Option B).

Save the preference so you don't re-detect it every session. Once you've determined which option this repo uses (or the user tells you), record it in the project-specific instructions section of AGENTS.md (user-owned — never overwritten by wmill refresh prompts), e.g. a line like Deploy mode: git push (CI runs wmill sync push) or Deploy mode: wmill sync push (no CI wiring). On later sessions, read that line first and skip the scan. Re-detect only if the CI wiring visibly changed.

Option A — git push (CI is wired to sync)

The CI workflow will pick up the commit and run wmill sync push on the backend, which is how deployments are intended to happen in this repo. Don't bypass it.

  1. git add + git commit the local changes.
  2. git push to the branch the CI runs on.
  3. The workflow deploys to the workspace.

Only fall back to Option B if the user explicitly asks to bypass CI for this change (e.g. CI is broken, urgent hotfix), or if the workflow doesn't cover the current branch.

Option B — wmill sync push (no CI wiring)

No CI workflow runs wmill sync push automatically, so deploy directly from the CLI:

  • wmill sync push --dry-run to preview.
  • wmill sync push to apply.

In both cases

Only deploy when the user explicitly asks to deploy, publish, push, or ship — not when they say "run", "try", or "test". For testing local edits use the per-entity preview commands (wmill script preview, wmill flow preview) — they don't deploy.

Workspace forks

A fork is an isolated copy of a workspace for parallel or experimental work — make changes (including to datatables, which are cloned per fork) without touching the parent, then merge back after review. Each fork is paired with a git branch named wm-fork/<base>/<id>. Forks require a git repo.

Just run wmill workspace fork — it adapts to where you are:

  • On a base branch (e.g. main, or a branch bound to a workspace): it bases the fork on that branch and prints a git checkout -b wm-fork/<base>/<id> to start a fresh fork branch.
  • On a working branch (e.g. you've branched and already edited a forked datatable): it offers to base the fork on that branch and rename it onto wm-fork/<base>/<id> in place, preserving its commits — asking which base branch is the parent if there's more than one.

For non-interactive runs from a working branch, pass --from-branch <base> to skip the prompts. The CLI refuses to rename a base branch.

While a wm-fork/<base>/<id> branch is checked out, every wmill command automatically targets the fork workspace (resolved from the branch name), reusing the base branch workspace's remote (from wmill.yaml) and its saved profile's auth — no --workspace flag or profile switch needed. Pass --workspace to target a different workspace explicitly.

Merge a fork back into its parent with wmill workspace merge (or the Merge UI on the fork's home page). Full reference: https://www.windmill.dev/docs/advanced/workspace_forks

Debugging Jobs

When the user reports a script or flow failure, is investigating unexpected output, or asks why something ran the way it did, use the CLI to fetch job details before speculating. See the cli-commands skill for all flags.

  • wmill job list --script-path <path> — recent runs of a specific script or flow
  • wmill job list --failed --limit 20 — recent failures across the workspace
  • wmill job get <id> — status, timing, and (for flows) the step tree with sub-job IDs
  • wmill job logs <id> — stdout/stderr; for flows, aggregates every step's logs
  • wmill job result <id> — JSON result of a completed job
  • wmill job cancel <id> — stop a running or queued job
  • wmill job rerun <id> — re-run a completed job with the same args (single-job equivalent of the frontend "rerun" button)
  • wmill job restart <id> --step <step-id> [--iteration <n>] — restart a completed flow at a top-level step (for nested-container restart, use the UI)

For flow failures, start with wmill job get <id> to identify the failing step and its sub-job ID, then wmill job logs <sub-job-id> to drill in.

Skills

For specific guidance, ALWAYS use the skills listed below. Paths point at .agents/skills/ — Claude Code reads identical copies under .claude/skills/.

  • .agents/skills/write-script-ansible/SKILL.md - MUST use when writing Ansible playbooks.
  • .agents/skills/write-script-bash/SKILL.md - MUST use when writing Bash scripts.
  • .agents/skills/write-script-bigquery/SKILL.md - MUST use when writing BigQuery queries.
  • .agents/skills/write-script-bun/SKILL.md - MUST use when writing Bun/TypeScript scripts.
  • .agents/skills/write-script-bunnative/SKILL.md - MUST use when writing Bun Native scripts. The script must start with //native to run on the native worker.
  • .agents/skills/write-script-csharp/SKILL.md - MUST use when writing C# scripts.
  • .agents/skills/write-script-deno/SKILL.md - MUST use when writing Deno/TypeScript scripts.
  • .agents/skills/write-script-duckdb/SKILL.md - MUST use when writing DuckDB queries.
  • .agents/skills/write-script-go/SKILL.md - MUST use when writing Go scripts.
  • .agents/skills/write-script-graphql/SKILL.md - MUST use when writing GraphQL queries.
  • .agents/skills/write-script-java/SKILL.md - MUST use when writing Java scripts.
  • .agents/skills/write-script-mssql/SKILL.md - MUST use when writing MS SQL Server queries.
  • .agents/skills/write-script-mysql/SKILL.md - MUST use when writing MySQL queries.
  • .agents/skills/write-script-php/SKILL.md - MUST use when writing PHP scripts.
  • .agents/skills/write-script-postgresql/SKILL.md - MUST use when writing PostgreSQL queries.
  • .agents/skills/write-script-powershell/SKILL.md - MUST use when writing PowerShell scripts.
  • .agents/skills/write-script-python3/SKILL.md - MUST use when writing Python scripts.
  • .agents/skills/write-script-rlang/SKILL.md - MUST use when writing R scripts.
  • .agents/skills/write-script-rust/SKILL.md - MUST use when writing Rust scripts.
  • .agents/skills/write-script-snowflake/SKILL.md - MUST use when writing Snowflake queries.
  • .agents/skills/write-flow/SKILL.md - MUST use when creating flows.
  • .agents/skills/raw-app/SKILL.md - MUST use when creating raw apps.
  • .agents/skills/triggers/SKILL.md - MUST use when configuring triggers.
  • .agents/skills/schedules/SKILL.md - MUST use when configuring schedules.
  • .agents/skills/resources/SKILL.md - MUST use when managing resources.
  • .agents/skills/write-workflow-as-code/SKILL.md - MUST use when writing or modifying Windmill Workflow-as-Code scripts using workflow, task, step, sleep, approvals, taskScript, taskFlow, task_script, or task_flow.
  • .agents/skills/cli-commands/SKILL.md - MUST use when using the CLI, including debugging job failures and inspecting run history via wmill job.
  • .agents/skills/preview/SKILL.md - 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.

Windmill Documentation

For Windmill concepts not covered by the skills (triggers, schedules, workers, flows, error handling, etc.), read the official docs: