Files
windmill/system_prompts
a4ae82fd69 feat: optionally run trigger messages the filters cannot read (#12226)
* fix: route trigger messages the filters cannot parse to the error handler

A Kafka or websocket trigger with filters silently skipped a message that
was not UTF-8 or not JSON, and Kafka committed its offset, so the message
was lost without a trace. Such a message now goes to the trigger's error
handler (script targets) or the workspace error handler, with the raw
payload and its topic/partition/offset.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix: take the unfilterable-message handler as a RunnableRef after merging main

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix: keep none_of semantics for non-object JSON, honour workspace handler mutes, throttle the no-handler alert

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs: state the caller contract of push_error_handler_with_parent

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* chore: point ee-repo-ref at the kafka companion branch

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix: hold unparseable-message handlers of a suspended trigger, throttle them on websocket

A suspended trigger now holds the handler run like its other runs, tagged
with the trigger so resuming releases it. Websocket text keepalives would
start a handler run per frame, so websocket caps it at one per trigger per
minute; Kafka keeps one per message. A parentless handler run carries no
token prefix.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix: release a held error handler run in place when resuming an edited trigger

Resuming re-pushes runs held before the trigger's last edit against its
target. A held error handler run would then run the target with the
handler's args, so it is released in place.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* feat: add run_on_filter_error to kafka and websocket triggers

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix: treat a truncated array as unreadable, not as a filter mismatch

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* chore: update ee-repo-ref to 695eddf214f6a0e6cf1249ee2c20e716788f0766

This commit updates the EE repository reference after PR #954 was merged in windmill-ee-private.

Previous ee-repo-ref: c8a26463f72ed76423b14e6a1aaf6376e58f2c4c

New ee-repo-ref: 695eddf214f6a0e6cf1249ee2c20e716788f0766

Automated by sync-ee-ref workflow.

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: windmill-internal-app[bot] <windmill-internal-app[bot]@users.noreply.github.com>
Co-authored-by: Ruben Fiszel <ruben@windmill.dev>
2026-11-05 23:33:47 +01:00
..

System Prompts

The single source of the AI guidance Windmill ships: what an agent needs to know about Windmill itself to write flows, scripts, apps, pipelines, resources, triggers and schedules. Two consumers are built from it:

  • the chat (the frontend AI chat: flow, script, app and global modes), through the $system_prompts alias to auto-generated/;
  • the CLI (wmill init / wmill refresh prompts), as the skills embedded in cli/src/guidance/skills.gen.ts, next to the AGENTS.wmill.md template in cli/src/guidance/core.ts.

The workspace MCP server (backend/windmill-api/src/ai_session_tools/) is a third reader, one step removed: it serves the global chat's own get_instructions texts and system prompt, rendered for an external client by npm run gen:mcp-session in frontend/. Rerun that after generate.py.

Guidance written in one consumer only is guidance the other never gets. Write it here.

Structure

system_prompts/
├── base/              # Hand-written guidance, one file per topic (flow-base.md, raw-app.md, …)
│                      # plus CLI-only intros (flow-cli.md, script-cli.md, raw-app-cli.md, …)
├── languages/         # Hand-written per-language guidance (bun.md, python3.md, …)
├── generate.py        # Builds everything under auto-generated/ and cli/src/guidance/skills.gen.ts
├── utils.py           # Shared helpers, including the fence renderer
└── auto-generated/    # Generated — never edit
    ├── prompts.ts     # One export per base/ and languages/ file (chat render), SDK docs, schema
    ├── index.ts       # Chat helpers (getFlowPrompt, getScriptPrompt, …)
    ├── skills/        # One SKILL.md per CLI skill (cli render)
    ├── sdks/          # SDK reference extracted from the TypeScript and Python clients
    └── cli/           # CLI command reference extracted from cli/src/commands/

How a topic is assembled

TOPICS in generate.py lists, for each topic, the parts both consumers concatenate in order: a file under base/ or languages/, or a token filled per consumer ({lang}, {sdk}, {wac_sdk}, {openflow_schema}, {cli_commands}). The same entry produces the topic's chat helper in index.ts and its CLI skill, so a part added there reaches both. A part tagged ('chat', …) or ('cli', …) goes to that consumer only, and cli_intro heads the CLI skill with a CLI-only workflow file (flow-cli.md, script-cli.md, raw-app-cli.md).

Topic Chat helper CLI skill Shared parts
script getScriptPrompt(lang) write-script-<lang> script-base.md, the language file, its SDK
flow getFlowPrompt() write-flow flow-base.md, the OpenFlow schema
raw app getRawAppPrompt(lang) raw-app raw-app.md (chat adds the SDK)
resources getResourcePrompt() resources resources.md
workflow-as-code getWorkflowAsCodePrompt(lang) write-workflow-as-code workflow-as-code.md, the WAC SDK
pipeline getPipelinePrompt() write-pipeline pipeline-base.md
data tables getDatatablePrompt() datatables datatable.md
workspace settings getWorkspaceSettingsPrompt() workspace-settings workspace-settings.md
triggers, schedules, preview, CLI commands — same names CLI only

The app chat embeds RAW_APP_BASE directly (chat/app/core.ts).

Consumer fences

A sentence that only one consumer should see stays in the shared file, fenced:

A tool name outside that character set fails every run of the flow.
<!-- chat-only -->
The flow write tools refuse such a name.
<!-- /chat-only -->
<!-- cli-only -->
`wmill lint <flow folder>` reports it before anything runs.
<!-- /cli-only -->

render_for (utils.py) renders every file once per consumer: prompts.ts gets the chat render, the skills get the cli render, and the fence lines reach neither. Fences sit on their own lines and cannot nest; an unbalanced or misspelled fence fails generation (an HTML comment opening with cli or chat, or ending in only, is read as a fence attempt).

Use a fence for a sentence or a section. When most of a topic differs per consumer, a CLI-only file used as cli_intro reads better than a file that is mostly fences.

What goes where

  • Here: anything true of Windmill regardless of who is asking — module shapes, data flow rules, what the editor accepts, how data tables, secrets or app access work.
  • In the chat's TypeScript prompt builders (frontend/src/lib/components/copilot/chat/*/core.ts): only tool plumbing (which tool to call, its arguments) and values known at run time (the user's name, this app's data-table policy, session capabilities).
  • In cli/src/guidance/core.ts (AGENTS.wmill.md): project-level CLI workflow — which skill to use, deploying, debugging jobs.

A file in TOPICS names no chat tool, not even inside a chat-only fence: it reaches every chat mode (flow mode's system prompt, global mode's get_instructions), each with its own tool names, and global/sessionToolset.test.ts fails a prompt that names a tool its session lacks. Describe the action instead ("the flow write tools refuse such a name") and name the tool in TypeScript. The one exception is flow-chat-special-modules.md, which only flow mode reads.

Regenerating

After editing anything here, or when SDK methods, the OpenFlow schema or CLI commands change:

python system_prompts/generate.py

CI (.github/workflows/check-system-prompts.yml) runs system_prompts/check-freshness.sh, which fails when the committed output is stale.

To also refresh the standalone skills in a Claude plugin checkout:

python system_prompts/generate.py --plugin-dir ~/windmill-claude-plugin

--plugin-dir accepts:

  • the windmill-claude-plugin repo root
  • a plugin root such as plugins/windmill
  • a direct skills/ directory

To regenerate the public docs repo (consumed by context7):

python system_prompts/generate.py --context7-dir ~/windmill-cli-docs

--context7-dir writes a fully-rendered snapshot (AGENTS.md, cli-commands.md, skills/<name>/SKILL.md, README.md, manifest.json with the Windmill version) with all template placeholders resolved — suitable for ingestion by docs aggregators. In CI this runs from .github/workflows/publish-cli-docs.yml on every release tag. The generator refuses to wipe the target directory unless it's empty or has a context7 marker (context7.json, manifest.json, or a windmill-cli-docs git remote), so a typo can't delete unrelated files.