From e952298f84d04cbb11f0c44c32435f0b711bf3bf Mon Sep 17 00:00:00 2001
From: Ruben Fiszel <ruben@windmill.dev>
Date: Sat, 3 Oct 2026 09:33:18 +0200
Subject: [PATCH] feat: replace the AI input filling toggle with an additional
 prompt (#11501)

* feat: replace the AI input filling toggle with an additional prompt for AI

* feat: pass the additional prompt for AI to MCP clients and shared AI guidance

* feat: shrink the run page AI card to a button and a collapsed prompt

* fix: offer writers a way to add a prompt for AI from the run page
---
 backend/windmill-mcp/src/common/types.rs      | 22 +++++-
 backend/windmill-mcp/src/server/tools.rs      | 30 +++++++
 cli/src/guidance/skills.gen.ts                | 24 ++++++
 .../components/copilot/AIFormAssistant.svelte | 79 ++++++++++++-------
 .../components/copilot/AIFormSettings.svelte  | 47 +++--------
 .../components/copilot/chat/global/core.ts    |  2 +-
 .../lib/components/details/FlowDetail.svelte  | 10 +--
 .../components/details/ScriptDetail.svelte    | 10 +--
 .../flows/content/FlowSettings.svelte         |  4 +-
 system_prompts/auto-generated/flow.md         |  4 +
 system_prompts/auto-generated/prompts.ts      |  5 ++
 system_prompts/auto-generated/script.md       |  1 +
 .../auto-generated/skills/write-flow/SKILL.md |  4 +
 .../skills/write-script-ansible/SKILL.md      |  1 +
 .../skills/write-script-bash/SKILL.md         |  1 +
 .../skills/write-script-bigquery/SKILL.md     |  1 +
 .../skills/write-script-bun/SKILL.md          |  1 +
 .../skills/write-script-bunnative/SKILL.md    |  1 +
 .../skills/write-script-csharp/SKILL.md       |  1 +
 .../skills/write-script-deno/SKILL.md         |  1 +
 .../skills/write-script-duckdb/SKILL.md       |  1 +
 .../skills/write-script-go/SKILL.md           |  1 +
 .../skills/write-script-graphql/SKILL.md      |  1 +
 .../skills/write-script-java/SKILL.md         |  1 +
 .../skills/write-script-mssql/SKILL.md        |  1 +
 .../skills/write-script-mysql/SKILL.md        |  1 +
 .../skills/write-script-php/SKILL.md          |  1 +
 .../skills/write-script-postgresql/SKILL.md   |  1 +
 .../skills/write-script-powershell/SKILL.md   |  1 +
 .../skills/write-script-python3/SKILL.md      |  1 +
 .../skills/write-script-rlang/SKILL.md        |  1 +
 .../skills/write-script-rust/SKILL.md         |  1 +
 .../skills/write-script-snowflake/SKILL.md    |  1 +
 system_prompts/base/flow-base.md              |  4 +
 system_prompts/base/script-base.md            |  1 +
 35 files changed, 192 insertions(+), 75 deletions(-)

diff --git a/backend/windmill-mcp/src/common/types.rs b/backend/windmill-mcp/src/common/types.rs
index 8ec6175bdb..92513b7a29 100644
--- a/backend/windmill-mcp/src/common/types.rs
+++ b/backend/windmill-mcp/src/common/types.rs
@@ -67,6 +67,11 @@ pub struct SchemaType {
     pub properties: HashMap<String, Value>,
     #[serde(default)]
     pub required: Vec<String>,
+    /// The author's guidance for choosing the inputs. A `Value` so that a schema carrying
+    /// anything but a string here still parses, and never serialized: it belongs in the
+    /// tool description, not in the input schema a client validates arguments against.
+    #[serde(default, skip_serializing)]
+    pub prompt_for_ai: Option<Value>,
 }
 
 fn default_schema_type() -> String {
@@ -75,7 +80,22 @@ fn default_schema_type() -> String {
 
 impl Default for SchemaType {
     fn default() -> Self {
-        Self { r#type: "object".to_string(), properties: HashMap::new(), required: vec![] }
+        Self {
+            r#type: "object".to_string(),
+            properties: HashMap::new(),
+            required: vec![],
+            prompt_for_ai: None,
+        }
+    }
+}
+
+impl SchemaType {
+    pub fn prompt_for_ai(&self) -> Option<&str> {
+        self.prompt_for_ai
+            .as_ref()
+            .and_then(Value::as_str)
+            .map(str::trim)
+            .filter(|prompt| !prompt.is_empty())
     }
 }
 
diff --git a/backend/windmill-mcp/src/server/tools.rs b/backend/windmill-mcp/src/server/tools.rs
index 4fcbe086cd..98ea105db4 100644
--- a/backend/windmill-mcp/src/server/tools.rs
+++ b/backend/windmill-mcp/src/server/tools.rs
@@ -208,6 +208,11 @@ pub fn create_tool_from_item<T: ToolableItem, B: McpBackend>(
     );
 
     let schema = item.get_schema();
+    if let Some(prompt) = schema.prompt_for_ai() {
+        description.push_str(&format!(
+            " Its author gave these instructions for choosing the arguments: {prompt}"
+        ));
+    }
     let schema_obj =
         backend.transform_schema_for_resources(&schema, resources_cache, resources_types);
 
@@ -283,6 +288,31 @@ mod tests {
         .clone()
     }
 
+    #[test]
+    fn prompt_for_ai_is_read_but_kept_out_of_the_input_schema() {
+        let schema: SchemaType = serde_json::from_value(json!({
+            "type": "object",
+            "properties": { "query": { "type": "string" } },
+            "prompt_for_ai": "  Prefer short queries.  ",
+        }))
+        .unwrap();
+
+        assert_eq!(schema.prompt_for_ai(), Some("Prefer short queries."));
+        assert!(serde_json::to_value(&schema)
+            .unwrap()
+            .get("prompt_for_ai")
+            .is_none());
+
+        // A non-string value must not cost the tool its inputs.
+        let odd: SchemaType = serde_json::from_value(json!({
+            "properties": { "query": { "type": "string" } },
+            "prompt_for_ai": 3,
+        }))
+        .unwrap();
+        assert_eq!(odd.prompt_for_ai(), None);
+        assert!(odd.properties.contains_key("query"));
+    }
+
     #[test]
     fn hint_lists_optional_params_and_never_a_required_one() {
         let hint = omission_hint(&script_schema(), "script")
diff --git a/cli/src/guidance/skills.gen.ts b/cli/src/guidance/skills.gen.ts
index b770e3aab8..d087448dad 100644
--- a/cli/src/guidance/skills.gen.ts
+++ b/cli/src/guidance/skills.gen.ts
@@ -98,6 +98,7 @@ Use \`wmill resource-type list --schema\` to discover available resource types.
 - Libraries are installed automatically - do not show installation instructions
 - In a language with an entrypoint function (TypeScript, Python, Go, Rust, PHP, R, …), name it \`main\` (\`Main\` in C#) and do not call it; in TypeScript it must be async. SQL, GraphQL, Bash, PowerShell and Ansible scripts have no \`main\`: their language section shows how they take arguments
 - Where the language has a Windmill client (\`wmill\`), use it to interact with the platform
+- A script's input schema may carry a top-level \`prompt_for_ai\` string: its author's instructions to an AI choosing the inputs. Follow it when you pick arguments to run that script, and keep it when you rewrite the schema
 
 ## Return Values
 
@@ -261,6 +262,7 @@ Use \`wmill resource-type list --schema\` to discover available resource types.
 - Libraries are installed automatically - do not show installation instructions
 - In a language with an entrypoint function (TypeScript, Python, Go, Rust, PHP, R, …), name it \`main\` (\`Main\` in C#) and do not call it; in TypeScript it must be async. SQL, GraphQL, Bash, PowerShell and Ansible scripts have no \`main\`: their language section shows how they take arguments
 - Where the language has a Windmill client (\`wmill\`), use it to interact with the platform
+- A script's input schema may carry a top-level \`prompt_for_ai\` string: its author's instructions to an AI choosing the inputs. Follow it when you pick arguments to run that script, and keep it when you rewrite the schema
 
 ## Return Values
 
@@ -384,6 +386,7 @@ Use \`wmill resource-type list --schema\` to discover available resource types.
 - Libraries are installed automatically - do not show installation instructions
 - In a language with an entrypoint function (TypeScript, Python, Go, Rust, PHP, R, …), name it \`main\` (\`Main\` in C#) and do not call it; in TypeScript it must be async. SQL, GraphQL, Bash, PowerShell and Ansible scripts have no \`main\`: their language section shows how they take arguments
 - Where the language has a Windmill client (\`wmill\`), use it to interact with the platform
+- A script's input schema may carry a top-level \`prompt_for_ai\` string: its author's instructions to an AI choosing the inputs. Follow it when you pick arguments to run that script, and keep it when you rewrite the schema
 
 ## Return Values
 
@@ -500,6 +503,7 @@ Use \`wmill resource-type list --schema\` to discover available resource types.
 - Libraries are installed automatically - do not show installation instructions
 - In a language with an entrypoint function (TypeScript, Python, Go, Rust, PHP, R, …), name it \`main\` (\`Main\` in C#) and do not call it; in TypeScript it must be async. SQL, GraphQL, Bash, PowerShell and Ansible scripts have no \`main\`: their language section shows how they take arguments
 - Where the language has a Windmill client (\`wmill\`), use it to interact with the platform
+- A script's input schema may carry a top-level \`prompt_for_ai\` string: its author's instructions to an AI choosing the inputs. Follow it when you pick arguments to run that script, and keep it when you rewrite the schema
 
 ## Return Values
 
@@ -1320,6 +1324,7 @@ Use \`wmill resource-type list --schema\` to discover available resource types.
 - Libraries are installed automatically - do not show installation instructions
 - In a language with an entrypoint function (TypeScript, Python, Go, Rust, PHP, R, …), name it \`main\` (\`Main\` in C#) and do not call it; in TypeScript it must be async. SQL, GraphQL, Bash, PowerShell and Ansible scripts have no \`main\`: their language section shows how they take arguments
 - Where the language has a Windmill client (\`wmill\`), use it to interact with the platform
+- A script's input schema may carry a top-level \`prompt_for_ai\` string: its author's instructions to an AI choosing the inputs. Follow it when you pick arguments to run that script, and keep it when you rewrite the schema
 
 ## Return Values
 
@@ -2152,6 +2157,7 @@ Use \`wmill resource-type list --schema\` to discover available resource types.
 - Libraries are installed automatically - do not show installation instructions
 - In a language with an entrypoint function (TypeScript, Python, Go, Rust, PHP, R, …), name it \`main\` (\`Main\` in C#) and do not call it; in TypeScript it must be async. SQL, GraphQL, Bash, PowerShell and Ansible scripts have no \`main\`: their language section shows how they take arguments
 - Where the language has a Windmill client (\`wmill\`), use it to interact with the platform
+- A script's input schema may carry a top-level \`prompt_for_ai\` string: its author's instructions to an AI choosing the inputs. Follow it when you pick arguments to run that script, and keep it when you rewrite the schema
 
 ## Return Values
 
@@ -2267,6 +2273,7 @@ Use \`wmill resource-type list --schema\` to discover available resource types.
 - Libraries are installed automatically - do not show installation instructions
 - In a language with an entrypoint function (TypeScript, Python, Go, Rust, PHP, R, …), name it \`main\` (\`Main\` in C#) and do not call it; in TypeScript it must be async. SQL, GraphQL, Bash, PowerShell and Ansible scripts have no \`main\`: their language section shows how they take arguments
 - Where the language has a Windmill client (\`wmill\`), use it to interact with the platform
+- A script's input schema may carry a top-level \`prompt_for_ai\` string: its author's instructions to an AI choosing the inputs. Follow it when you pick arguments to run that script, and keep it when you rewrite the schema
 
 ## Return Values
 
@@ -3089,6 +3096,7 @@ Use \`wmill resource-type list --schema\` to discover available resource types.
 - Libraries are installed automatically - do not show installation instructions
 - In a language with an entrypoint function (TypeScript, Python, Go, Rust, PHP, R, …), name it \`main\` (\`Main\` in C#) and do not call it; in TypeScript it must be async. SQL, GraphQL, Bash, PowerShell and Ansible scripts have no \`main\`: their language section shows how they take arguments
 - Where the language has a Windmill client (\`wmill\`), use it to interact with the platform
+- A script's input schema may carry a top-level \`prompt_for_ai\` string: its author's instructions to an AI choosing the inputs. Follow it when you pick arguments to run that script, and keep it when you rewrite the schema
 
 ## Return Values
 
@@ -3238,6 +3246,7 @@ Use \`wmill resource-type list --schema\` to discover available resource types.
 - Libraries are installed automatically - do not show installation instructions
 - In a language with an entrypoint function (TypeScript, Python, Go, Rust, PHP, R, …), name it \`main\` (\`Main\` in C#) and do not call it; in TypeScript it must be async. SQL, GraphQL, Bash, PowerShell and Ansible scripts have no \`main\`: their language section shows how they take arguments
 - Where the language has a Windmill client (\`wmill\`), use it to interact with the platform
+- A script's input schema may carry a top-level \`prompt_for_ai\` string: its author's instructions to an AI choosing the inputs. Follow it when you pick arguments to run that script, and keep it when you rewrite the schema
 
 ## Return Values
 
@@ -3370,6 +3379,7 @@ Use \`wmill resource-type list --schema\` to discover available resource types.
 - Libraries are installed automatically - do not show installation instructions
 - In a language with an entrypoint function (TypeScript, Python, Go, Rust, PHP, R, …), name it \`main\` (\`Main\` in C#) and do not call it; in TypeScript it must be async. SQL, GraphQL, Bash, PowerShell and Ansible scripts have no \`main\`: their language section shows how they take arguments
 - Where the language has a Windmill client (\`wmill\`), use it to interact with the platform
+- A script's input schema may carry a top-level \`prompt_for_ai\` string: its author's instructions to an AI choosing the inputs. Follow it when you pick arguments to run that script, and keep it when you rewrite the schema
 
 ## Return Values
 
@@ -3489,6 +3499,7 @@ Use \`wmill resource-type list --schema\` to discover available resource types.
 - Libraries are installed automatically - do not show installation instructions
 - In a language with an entrypoint function (TypeScript, Python, Go, Rust, PHP, R, …), name it \`main\` (\`Main\` in C#) and do not call it; in TypeScript it must be async. SQL, GraphQL, Bash, PowerShell and Ansible scripts have no \`main\`: their language section shows how they take arguments
 - Where the language has a Windmill client (\`wmill\`), use it to interact with the platform
+- A script's input schema may carry a top-level \`prompt_for_ai\` string: its author's instructions to an AI choosing the inputs. Follow it when you pick arguments to run that script, and keep it when you rewrite the schema
 
 ## Return Values
 
@@ -3601,6 +3612,7 @@ Use \`wmill resource-type list --schema\` to discover available resource types.
 - Libraries are installed automatically - do not show installation instructions
 - In a language with an entrypoint function (TypeScript, Python, Go, Rust, PHP, R, …), name it \`main\` (\`Main\` in C#) and do not call it; in TypeScript it must be async. SQL, GraphQL, Bash, PowerShell and Ansible scripts have no \`main\`: their language section shows how they take arguments
 - Where the language has a Windmill client (\`wmill\`), use it to interact with the platform
+- A script's input schema may carry a top-level \`prompt_for_ai\` string: its author's instructions to an AI choosing the inputs. Follow it when you pick arguments to run that script, and keep it when you rewrite the schema
 
 ## Return Values
 
@@ -3716,6 +3728,7 @@ Use \`wmill resource-type list --schema\` to discover available resource types.
 - Libraries are installed automatically - do not show installation instructions
 - In a language with an entrypoint function (TypeScript, Python, Go, Rust, PHP, R, …), name it \`main\` (\`Main\` in C#) and do not call it; in TypeScript it must be async. SQL, GraphQL, Bash, PowerShell and Ansible scripts have no \`main\`: their language section shows how they take arguments
 - Where the language has a Windmill client (\`wmill\`), use it to interact with the platform
+- A script's input schema may carry a top-level \`prompt_for_ai\` string: its author's instructions to an AI choosing the inputs. Follow it when you pick arguments to run that script, and keep it when you rewrite the schema
 
 ## Return Values
 
@@ -3832,6 +3845,7 @@ Use \`wmill resource-type list --schema\` to discover available resource types.
 - Libraries are installed automatically - do not show installation instructions
 - In a language with an entrypoint function (TypeScript, Python, Go, Rust, PHP, R, …), name it \`main\` (\`Main\` in C#) and do not call it; in TypeScript it must be async. SQL, GraphQL, Bash, PowerShell and Ansible scripts have no \`main\`: their language section shows how they take arguments
 - Where the language has a Windmill client (\`wmill\`), use it to interact with the platform
+- A script's input schema may carry a top-level \`prompt_for_ai\` string: its author's instructions to an AI choosing the inputs. Follow it when you pick arguments to run that script, and keep it when you rewrite the schema
 
 ## Return Values
 
@@ -3963,6 +3977,7 @@ Use \`wmill resource-type list --schema\` to discover available resource types.
 - Libraries are installed automatically - do not show installation instructions
 - In a language with an entrypoint function (TypeScript, Python, Go, Rust, PHP, R, …), name it \`main\` (\`Main\` in C#) and do not call it; in TypeScript it must be async. SQL, GraphQL, Bash, PowerShell and Ansible scripts have no \`main\`: their language section shows how they take arguments
 - Where the language has a Windmill client (\`wmill\`), use it to interact with the platform
+- A script's input schema may carry a top-level \`prompt_for_ai\` string: its author's instructions to an AI choosing the inputs. Follow it when you pick arguments to run that script, and keep it when you rewrite the schema
 
 ## Return Values
 
@@ -4077,6 +4092,7 @@ Use \`wmill resource-type list --schema\` to discover available resource types.
 - Libraries are installed automatically - do not show installation instructions
 - In a language with an entrypoint function (TypeScript, Python, Go, Rust, PHP, R, …), name it \`main\` (\`Main\` in C#) and do not call it; in TypeScript it must be async. SQL, GraphQL, Bash, PowerShell and Ansible scripts have no \`main\`: their language section shows how they take arguments
 - Where the language has a Windmill client (\`wmill\`), use it to interact with the platform
+- A script's input schema may carry a top-level \`prompt_for_ai\` string: its author's instructions to an AI choosing the inputs. Follow it when you pick arguments to run that script, and keep it when you rewrite the schema
 
 ## Return Values
 
@@ -4206,6 +4222,7 @@ Use \`wmill resource-type list --schema\` to discover available resource types.
 - Libraries are installed automatically - do not show installation instructions
 - In a language with an entrypoint function (TypeScript, Python, Go, Rust, PHP, R, …), name it \`main\` (\`Main\` in C#) and do not call it; in TypeScript it must be async. SQL, GraphQL, Bash, PowerShell and Ansible scripts have no \`main\`: their language section shows how they take arguments
 - Where the language has a Windmill client (\`wmill\`), use it to interact with the platform
+- A script's input schema may carry a top-level \`prompt_for_ai\` string: its author's instructions to an AI choosing the inputs. Follow it when you pick arguments to run that script, and keep it when you rewrite the schema
 
 ## Return Values
 
@@ -5210,6 +5227,7 @@ Use \`wmill resource-type list --schema\` to discover available resource types.
 - Libraries are installed automatically - do not show installation instructions
 - In a language with an entrypoint function (TypeScript, Python, Go, Rust, PHP, R, …), name it \`main\` (\`Main\` in C#) and do not call it; in TypeScript it must be async. SQL, GraphQL, Bash, PowerShell and Ansible scripts have no \`main\`: their language section shows how they take arguments
 - Where the language has a Windmill client (\`wmill\`), use it to interact with the platform
+- A script's input schema may carry a top-level \`prompt_for_ai\` string: its author's instructions to an AI choosing the inputs. Follow it when you pick arguments to run that script, and keep it when you rewrite the schema
 
 ## Return Values
 
@@ -5369,6 +5387,7 @@ Use \`wmill resource-type list --schema\` to discover available resource types.
 - Libraries are installed automatically - do not show installation instructions
 - In a language with an entrypoint function (TypeScript, Python, Go, Rust, PHP, R, …), name it \`main\` (\`Main\` in C#) and do not call it; in TypeScript it must be async. SQL, GraphQL, Bash, PowerShell and Ansible scripts have no \`main\`: their language section shows how they take arguments
 - Where the language has a Windmill client (\`wmill\`), use it to interact with the platform
+- A script's input schema may carry a top-level \`prompt_for_ai\` string: its author's instructions to an AI choosing the inputs. Follow it when you pick arguments to run that script, and keep it when you rewrite the schema
 
 ## Return Values
 
@@ -5518,6 +5537,7 @@ Use \`wmill resource-type list --schema\` to discover available resource types.
 - Libraries are installed automatically - do not show installation instructions
 - In a language with an entrypoint function (TypeScript, Python, Go, Rust, PHP, R, …), name it \`main\` (\`Main\` in C#) and do not call it; in TypeScript it must be async. SQL, GraphQL, Bash, PowerShell and Ansible scripts have no \`main\`: their language section shows how they take arguments
 - Where the language has a Windmill client (\`wmill\`), use it to interact with the platform
+- A script's input schema may carry a top-level \`prompt_for_ai\` string: its author's instructions to an AI choosing the inputs. Follow it when you pick arguments to run that script, and keep it when you rewrite the schema
 
 ## Return Values
 
@@ -6072,6 +6092,10 @@ Unless the user asked for new code, look for a workspace script or flow that alr
 The step's \`input_transforms\` must cover the reused item's inputs, so read its input schema first.
 Find candidates in the local tree (a \`.script.yaml\` sits next to each script and holds its input schema, a \`flow.yaml\` in each flow folder) and on the workspace with \`wmill script list\` / \`wmill flow list\`; \`wmill script get <path>\` and \`wmill flow get <path>\` show an item's details.
 
+## Additional Prompt for AI
+
+A flow's input schema may carry a top-level \`prompt_for_ai\` string, as a script's can: its author's instructions to an AI choosing the inputs. Follow it when you pick arguments to run that flow, and keep it when you rewrite the schema.
+
 ## Organizing Flows: Groups and Notes
 
 Groups and notes shape how a flow reads in the editor; neither changes what it does.
diff --git a/frontend/src/lib/components/copilot/AIFormAssistant.svelte b/frontend/src/lib/components/copilot/AIFormAssistant.svelte
index aab3c73a1e..72ab57cab6 100644
--- a/frontend/src/lib/components/copilot/AIFormAssistant.svelte
+++ b/frontend/src/lib/components/copilot/AIFormAssistant.svelte
@@ -1,6 +1,7 @@
 <script lang="ts">
 	import { Button } from '$lib/components/common'
-	import { Pencil, WandSparkles } from 'lucide-svelte'
+	import { ChevronDown, ChevronRight, Pencil, WandSparkles } from 'lucide-svelte'
+	import { slide } from 'svelte/transition'
 	import { aiChatManager } from './chat/AIChatManager.svelte'
 	import OpenInSessionButton from '$lib/components/sessions/OpenInSessionButton.svelte'
 	import { AIBtnClasses } from './chat/AIButtonStyle'
@@ -9,7 +10,8 @@
 	import { logFeatureUsage } from '$lib/utils/featureUsage'
 
 	interface Props {
-		onEditInstructions: () => void
+		/** Unset for a viewer who cannot edit the item: the card then offers no way to the editor. */
+		onEditInstructions: (() => void) | undefined
 		instructions: string
 		runnableType: 'script' | 'flow'
 		path: string | undefined
@@ -19,6 +21,8 @@
 
 	const operatingWorkspace = useOperatingWorkspace()
 
+	let expanded = $state(false)
+
 	// Anonymous counter for this card being acted on, keyed by what it sits above. The two
 	// branches share one counter: they are the same intent, and which of them is on screen
 	// follows the user's session gate rather than a choice made here. `beforeOpen` is the
@@ -53,46 +57,67 @@
 </script>
 
 {#if !$copilotInfo.workspaceDisabled}
-	<div class="my-3 p-3 bg-surface-secondary rounded-md relative flex flex-col gap-3">
+	<div class="my-2 flex flex-col gap-1">
 		<div class="flex flex-row gap-2 justify-between items-center">
-			<!-- Heading stays neutral because the two branches do different things: the
-		     hand-off runs the item, the legacy path fills the form. Each button
-		     names its own action. A plain Button rather than AskAiButton, whose own
-		     session branch would fire here too and open an empty session. -->
-			<h3 class="text-sm font-medium">AI can help with these inputs</h3>
+			{#if instructions}
+				<Button
+					variant="subtle"
+					unifiedSize="sm"
+					startIcon={{ icon: expanded ? ChevronDown : ChevronRight }}
+					onclick={() => (expanded = !expanded)}
+				>
+					Additional prompt for AI
+				</Button>
+			{:else if onEditInstructions}
+				<Button
+					variant="subtle"
+					unifiedSize="sm"
+					startIcon={{ icon: Pencil }}
+					onclick={onEditInstructions}
+				>
+					Add a prompt for AI
+				</Button>
+			{:else}
+				<span></span>
+			{/if}
+			<!-- Each button names its own action because the two branches do different things:
+			     the hand-off runs the item, the legacy path fills the form. A plain Button rather
+			     than AskAiButton, whose own session branch would fire here too and open an empty
+			     session. -->
 			<OpenInSessionButton
 				source={sessionSource}
 				label="Run in AI session"
 				tooltip="Open an AI session that picks inputs and runs this"
-				btnProps={{ iconOnly: false, startIcon: { icon: WandSparkles } }}
+				btnProps={{ iconOnly: false, unifiedSize: 'sm', startIcon: { icon: WandSparkles } }}
 			>
 				{#snippet fallback()}
 					<Button
-						unifiedSize="md"
+						unifiedSize="sm"
 						startIcon={{ icon: WandSparkles }}
 						btnClasses={AIBtnClasses('default')}
-						on:click={fillFormWithAI}
+						onclick={fillFormWithAI}
 					>
 						Fill with AI
 					</Button>
 				{/snippet}
 			</OpenInSessionButton>
 		</div>
-		<div class="flex flex-row gap-2 items-center">
-			<p class="text-sm text-primary">
-				{instructions
-					? 'Instructions: ' + instructions
-					: 'No AI instructions provided. Click edit to add guidance for AI form filling.'}
-			</p>
-			<Button
-				color="light"
-				size="xs2"
-				startIcon={{
-					icon: Pencil
-				}}
-				iconOnly
-				on:click={onEditInstructions}
-			/>
-		</div>
+		{#if instructions && expanded}
+			<div
+				transition:slide={{ duration: 120 }}
+				class="flex flex-row gap-2 items-start justify-between p-2 bg-surface-secondary rounded-md"
+			>
+				<p class="text-xs text-primary whitespace-pre-wrap">{instructions}</p>
+				{#if onEditInstructions}
+					<Button
+						variant="subtle"
+						unifiedSize="xs"
+						startIcon={{ icon: Pencil }}
+						iconOnly
+						onclick={onEditInstructions}
+					/>
+				{/if}
+			</div>
+		{/if}
 	</div>
 {/if}
diff --git a/frontend/src/lib/components/copilot/AIFormSettings.svelte b/frontend/src/lib/components/copilot/AIFormSettings.svelte
index ef627ace4b..2094dda9f5 100644
--- a/frontend/src/lib/components/copilot/AIFormSettings.svelte
+++ b/frontend/src/lib/components/copilot/AIFormSettings.svelte
@@ -1,8 +1,6 @@
 <script lang="ts">
-	import { slide } from 'svelte/transition'
 	import Label from '../Label.svelte'
-	import Toggle from '../Toggle.svelte'
-	import Tooltip from '../Tooltip.svelte'
+	import TextInput from '../text_input/TextInput.svelte'
 	import { copilotInfo } from '$lib/aiStore'
 
 	interface Props {
@@ -10,40 +8,21 @@
 		type?: 'flow' | 'script'
 	}
 
-	let { prompt = $bindable(undefined), type = 'script' }: Props = $props()
+	let { prompt = $bindable(), type = 'script' }: Props = $props()
 </script>
 
 {#if !$copilotInfo.workspaceDisabled}
-	<div>
-		<Toggle
-			textClass="font-medium"
-			size="xs"
-			checked={prompt !== undefined}
-			on:change={() => {
-				if (prompt !== undefined) {
-					prompt = undefined
-				} else {
-					prompt = ''
-				}
+	<Label
+		label="Additional prompt for AI"
+		tooltip="An AI choosing this {type}'s inputs already reads its description and each field's description. Anything written here is given to it as extra guidance: mention specific fields and how they interact."
+	>
+		<TextInput
+			underlyingInputEl="textarea"
+			bind:value={() => prompt ?? '', (v) => (prompt = v === '' ? undefined : String(v))}
+			inputProps={{
+				placeholder: `Instructions for the AI about how to choose this ${type}'s inputs`,
+				rows: 3
 			}}
-			options={{ right: `Enable filling ${type} inputs with AI` }}
 		/>
-		{#if prompt !== undefined}
-			<div transition:slide={{ duration: 120 }} class="mt-6">
-				<Label label="Additional prompt for AI">
-					{#snippet header()}
-						<Tooltip>
-							AI will use script description and each field description to fill the inputs form. In
-							addition, any prompt passed here will be used by AI to guide it. You can mention
-							specific fields and interaction between fields here.
-						</Tooltip>
-					{/snippet}
-					<textarea
-						bind:value={prompt}
-						placeholder="Instructions for the AI about how to fill the form"
-					></textarea>
-				</Label>
-			</div>
-		{/if}
-	</div>
+	</Label>
 {/if}
diff --git a/frontend/src/lib/components/copilot/chat/global/core.ts b/frontend/src/lib/components/copilot/chat/global/core.ts
index 2a39ca1902..603c0abe36 100644
--- a/frontend/src/lib/components/copilot/chat/global/core.ts
+++ b/frontend/src/lib/components/copilot/chat/global/core.ts
@@ -900,7 +900,7 @@ const testRunArgsSchema = z
 	.nullable()
 	.optional()
 	.describe(
-		'Arguments to pass to the runnable. Omit or pass null when no arguments are needed. An argument typed as a resource (format "resource-<type>" in the input schema) takes the bare string "$res:<path>" as its whole value — never an object wrapper like {"$res": "<path>"}, and never a plain path, both of which reach the runnable unresolved. Same for a variable, with "$var:<path>". The prefixed string can also sit in a nested field, e.g. {"gh_auth": {"token": "$var:g/all/gh_token"}}.'
+		'Arguments to pass to the runnable. Omit or pass null when no arguments are needed. An argument typed as a resource (format "resource-<type>" in the input schema) takes the bare string "$res:<path>" as its whole value — never an object wrapper like {"$res": "<path>"}, and never a plain path, both of which reach the runnable unresolved. Same for a variable, with "$var:<path>". The prefixed string can also sit in a nested field, e.g. {"gh_auth": {"token": "$var:g/all/gh_token"}}. When the input schema carries a top-level "prompt_for_ai", it is the author\'s own instructions for choosing these arguments: follow it.'
 	)
 
 const backgroundArgSchema = z
diff --git a/frontend/src/lib/components/details/FlowDetail.svelte b/frontend/src/lib/components/details/FlowDetail.svelte
index 7001075e93..6802b3ddce 100644
--- a/frontend/src/lib/components/details/FlowDetail.svelte
+++ b/frontend/src/lib/components/details/FlowDetail.svelte
@@ -852,12 +852,12 @@
 									</div>
 								{/if}
 
-								{#if flow.schema?.prompt_for_ai !== undefined}
+								{#if Object.keys(flow.schema?.properties ?? {}).length > 0}
 									<AIFormAssistant
-										instructions={flow.schema?.prompt_for_ai as string}
-										onEditInstructions={() => {
-											onNavigate(`/flows/edit/${flow?.path}`)
-										}}
+										instructions={(flow.schema?.prompt_for_ai as string | undefined) ?? ''}
+										onEditInstructions={can_write && canAuthorFlow
+											? () => onNavigate(`/flows/edit/${flow?.path}`)
+											: undefined}
 										runnableType="flow"
 										path={flow?.path}
 									/>
diff --git a/frontend/src/lib/components/details/ScriptDetail.svelte b/frontend/src/lib/components/details/ScriptDetail.svelte
index 432ffbd74a..89708ea0ca 100644
--- a/frontend/src/lib/components/details/ScriptDetail.svelte
+++ b/frontend/src/lib/components/details/ScriptDetail.svelte
@@ -1073,12 +1073,12 @@
 								</div>
 							{/if}
 
-							{#if script?.schema?.prompt_for_ai !== undefined}
+							{#if Object.keys(script?.schema?.properties ?? {}).length > 0}
 								<AIFormAssistant
-									instructions={script.schema?.prompt_for_ai as string}
-									onEditInstructions={() => {
-										onNavigate(`/scripts/edit/${script?.path}?metadata_open=true`)
-									}}
+									instructions={(script?.schema?.prompt_for_ai as string | undefined) ?? ''}
+									onEditInstructions={can_write && !actingUser?.operator
+										? () => onNavigate(`/scripts/edit/${script?.path}?metadata_open=true`)
+										: undefined}
 									runnableType="script"
 									path={script?.path}
 								/>
diff --git a/frontend/src/lib/components/flows/content/FlowSettings.svelte b/frontend/src/lib/components/flows/content/FlowSettings.svelte
index 922e5b2cfd..d607da6ac1 100644
--- a/frontend/src/lib/components/flows/content/FlowSettings.svelte
+++ b/frontend/src/lib/components/flows/content/FlowSettings.svelte
@@ -92,8 +92,8 @@
 
 	let activeAdvancedOptions = $derived([
 		{
-			name: 'Fill flow inputs with AI',
-			active: typeof flowStore.val.schema?.prompt_for_ai == 'string'
+			name: 'Additional prompt for AI',
+			active: !!flowStore.val.schema?.prompt_for_ai
 		},
 		{
 			name: 'High Priority',
diff --git a/system_prompts/auto-generated/flow.md b/system_prompts/auto-generated/flow.md
index c45089c723..246b0dbc0a 100644
--- a/system_prompts/auto-generated/flow.md
+++ b/system_prompts/auto-generated/flow.md
@@ -406,6 +406,10 @@ Unless the user asked for new code, look for a workspace script or flow that alr
 
 The step's `input_transforms` must cover the reused item's inputs, so read its input schema first.
 
+## Additional Prompt for AI
+
+A flow's input schema may carry a top-level `prompt_for_ai` string, as a script's can: its author's instructions to an AI choosing the inputs. Follow it when you pick arguments to run that flow, and keep it when you rewrite the schema.
+
 ## Organizing Flows: Groups and Notes
 
 Groups and notes shape how a flow reads in the editor; neither changes what it does.
diff --git a/system_prompts/auto-generated/prompts.ts b/system_prompts/auto-generated/prompts.ts
index 5c77b89d92..c659bcab12 100644
--- a/system_prompts/auto-generated/prompts.ts
+++ b/system_prompts/auto-generated/prompts.ts
@@ -8,6 +8,7 @@ export const SCRIPT_BASE = `# Windmill Script Writing Guide
 - Libraries are installed automatically - do not show installation instructions
 - In a language with an entrypoint function (TypeScript, Python, Go, Rust, PHP, R, …), name it \`main\` (\`Main\` in C#) and do not call it; in TypeScript it must be async. SQL, GraphQL, Bash, PowerShell and Ansible scripts have no \`main\`: their language section shows how they take arguments
 - Where the language has a Windmill client (\`wmill\`), use it to interact with the platform
+- A script's input schema may carry a top-level \`prompt_for_ai\` string: its author's instructions to an AI choosing the inputs. Follow it when you pick arguments to run that script, and keep it when you rewrite the schema
 
 ## Return Values
 
@@ -432,6 +433,10 @@ Unless the user asked for new code, look for a workspace script or flow that alr
 
 The step's \`input_transforms\` must cover the reused item's inputs, so read its input schema first.
 
+## Additional Prompt for AI
+
+A flow's input schema may carry a top-level \`prompt_for_ai\` string, as a script's can: its author's instructions to an AI choosing the inputs. Follow it when you pick arguments to run that flow, and keep it when you rewrite the schema.
+
 ## Organizing Flows: Groups and Notes
 
 Groups and notes shape how a flow reads in the editor; neither changes what it does.
diff --git a/system_prompts/auto-generated/script.md b/system_prompts/auto-generated/script.md
index 46ae438164..0517cf1897 100644
--- a/system_prompts/auto-generated/script.md
+++ b/system_prompts/auto-generated/script.md
@@ -6,6 +6,7 @@
 - Libraries are installed automatically - do not show installation instructions
 - In a language with an entrypoint function (TypeScript, Python, Go, Rust, PHP, R, …), name it `main` (`Main` in C#) and do not call it; in TypeScript it must be async. SQL, GraphQL, Bash, PowerShell and Ansible scripts have no `main`: their language section shows how they take arguments
 - Where the language has a Windmill client (`wmill`), use it to interact with the platform
+- A script's input schema may carry a top-level `prompt_for_ai` string: its author's instructions to an AI choosing the inputs. Follow it when you pick arguments to run that script, and keep it when you rewrite the schema
 
 ## Return Values
 
diff --git a/system_prompts/auto-generated/skills/write-flow/SKILL.md b/system_prompts/auto-generated/skills/write-flow/SKILL.md
index d259948e56..29f79a2ca5 100644
--- a/system_prompts/auto-generated/skills/write-flow/SKILL.md
+++ b/system_prompts/auto-generated/skills/write-flow/SKILL.md
@@ -494,6 +494,10 @@ Unless the user asked for new code, look for a workspace script or flow that alr
 The step's `input_transforms` must cover the reused item's inputs, so read its input schema first.
 Find candidates in the local tree (a `.script.yaml` sits next to each script and holds its input schema, a `flow.yaml` in each flow folder) and on the workspace with `wmill script list` / `wmill flow list`; `wmill script get <path>` and `wmill flow get <path>` show an item's details.
 
+## Additional Prompt for AI
+
+A flow's input schema may carry a top-level `prompt_for_ai` string, as a script's can: its author's instructions to an AI choosing the inputs. Follow it when you pick arguments to run that flow, and keep it when you rewrite the schema.
+
 ## Organizing Flows: Groups and Notes
 
 Groups and notes shape how a flow reads in the editor; neither changes what it does.
diff --git a/system_prompts/auto-generated/skills/write-script-ansible/SKILL.md b/system_prompts/auto-generated/skills/write-script-ansible/SKILL.md
index e6683248db..9bb87cb4a1 100644
--- a/system_prompts/auto-generated/skills/write-script-ansible/SKILL.md
+++ b/system_prompts/auto-generated/skills/write-script-ansible/SKILL.md
@@ -56,6 +56,7 @@ Use `wmill resource-type list --schema` to discover available resource types.
 - Libraries are installed automatically - do not show installation instructions
 - In a language with an entrypoint function (TypeScript, Python, Go, Rust, PHP, R, …), name it `main` (`Main` in C#) and do not call it; in TypeScript it must be async. SQL, GraphQL, Bash, PowerShell and Ansible scripts have no `main`: their language section shows how they take arguments
 - Where the language has a Windmill client (`wmill`), use it to interact with the platform
+- A script's input schema may carry a top-level `prompt_for_ai` string: its author's instructions to an AI choosing the inputs. Follow it when you pick arguments to run that script, and keep it when you rewrite the schema
 
 ## Return Values
 
diff --git a/system_prompts/auto-generated/skills/write-script-bash/SKILL.md b/system_prompts/auto-generated/skills/write-script-bash/SKILL.md
index 42bbd7bc01..0c4634b775 100644
--- a/system_prompts/auto-generated/skills/write-script-bash/SKILL.md
+++ b/system_prompts/auto-generated/skills/write-script-bash/SKILL.md
@@ -56,6 +56,7 @@ Use `wmill resource-type list --schema` to discover available resource types.
 - Libraries are installed automatically - do not show installation instructions
 - In a language with an entrypoint function (TypeScript, Python, Go, Rust, PHP, R, …), name it `main` (`Main` in C#) and do not call it; in TypeScript it must be async. SQL, GraphQL, Bash, PowerShell and Ansible scripts have no `main`: their language section shows how they take arguments
 - Where the language has a Windmill client (`wmill`), use it to interact with the platform
+- A script's input schema may carry a top-level `prompt_for_ai` string: its author's instructions to an AI choosing the inputs. Follow it when you pick arguments to run that script, and keep it when you rewrite the schema
 
 ## Return Values
 
diff --git a/system_prompts/auto-generated/skills/write-script-bigquery/SKILL.md b/system_prompts/auto-generated/skills/write-script-bigquery/SKILL.md
index dc3e19c0c9..497336b001 100644
--- a/system_prompts/auto-generated/skills/write-script-bigquery/SKILL.md
+++ b/system_prompts/auto-generated/skills/write-script-bigquery/SKILL.md
@@ -56,6 +56,7 @@ Use `wmill resource-type list --schema` to discover available resource types.
 - Libraries are installed automatically - do not show installation instructions
 - In a language with an entrypoint function (TypeScript, Python, Go, Rust, PHP, R, …), name it `main` (`Main` in C#) and do not call it; in TypeScript it must be async. SQL, GraphQL, Bash, PowerShell and Ansible scripts have no `main`: their language section shows how they take arguments
 - Where the language has a Windmill client (`wmill`), use it to interact with the platform
+- A script's input schema may carry a top-level `prompt_for_ai` string: its author's instructions to an AI choosing the inputs. Follow it when you pick arguments to run that script, and keep it when you rewrite the schema
 
 ## Return Values
 
diff --git a/system_prompts/auto-generated/skills/write-script-bun/SKILL.md b/system_prompts/auto-generated/skills/write-script-bun/SKILL.md
index 6d82183b88..4b340c0db1 100644
--- a/system_prompts/auto-generated/skills/write-script-bun/SKILL.md
+++ b/system_prompts/auto-generated/skills/write-script-bun/SKILL.md
@@ -56,6 +56,7 @@ Use `wmill resource-type list --schema` to discover available resource types.
 - Libraries are installed automatically - do not show installation instructions
 - In a language with an entrypoint function (TypeScript, Python, Go, Rust, PHP, R, …), name it `main` (`Main` in C#) and do not call it; in TypeScript it must be async. SQL, GraphQL, Bash, PowerShell and Ansible scripts have no `main`: their language section shows how they take arguments
 - Where the language has a Windmill client (`wmill`), use it to interact with the platform
+- A script's input schema may carry a top-level `prompt_for_ai` string: its author's instructions to an AI choosing the inputs. Follow it when you pick arguments to run that script, and keep it when you rewrite the schema
 
 ## Return Values
 
diff --git a/system_prompts/auto-generated/skills/write-script-bunnative/SKILL.md b/system_prompts/auto-generated/skills/write-script-bunnative/SKILL.md
index fd6b21dc60..03d40ab044 100644
--- a/system_prompts/auto-generated/skills/write-script-bunnative/SKILL.md
+++ b/system_prompts/auto-generated/skills/write-script-bunnative/SKILL.md
@@ -56,6 +56,7 @@ Use `wmill resource-type list --schema` to discover available resource types.
 - Libraries are installed automatically - do not show installation instructions
 - In a language with an entrypoint function (TypeScript, Python, Go, Rust, PHP, R, …), name it `main` (`Main` in C#) and do not call it; in TypeScript it must be async. SQL, GraphQL, Bash, PowerShell and Ansible scripts have no `main`: their language section shows how they take arguments
 - Where the language has a Windmill client (`wmill`), use it to interact with the platform
+- A script's input schema may carry a top-level `prompt_for_ai` string: its author's instructions to an AI choosing the inputs. Follow it when you pick arguments to run that script, and keep it when you rewrite the schema
 
 ## Return Values
 
diff --git a/system_prompts/auto-generated/skills/write-script-csharp/SKILL.md b/system_prompts/auto-generated/skills/write-script-csharp/SKILL.md
index d755483abb..389c683f7c 100644
--- a/system_prompts/auto-generated/skills/write-script-csharp/SKILL.md
+++ b/system_prompts/auto-generated/skills/write-script-csharp/SKILL.md
@@ -56,6 +56,7 @@ Use `wmill resource-type list --schema` to discover available resource types.
 - Libraries are installed automatically - do not show installation instructions
 - In a language with an entrypoint function (TypeScript, Python, Go, Rust, PHP, R, …), name it `main` (`Main` in C#) and do not call it; in TypeScript it must be async. SQL, GraphQL, Bash, PowerShell and Ansible scripts have no `main`: their language section shows how they take arguments
 - Where the language has a Windmill client (`wmill`), use it to interact with the platform
+- A script's input schema may carry a top-level `prompt_for_ai` string: its author's instructions to an AI choosing the inputs. Follow it when you pick arguments to run that script, and keep it when you rewrite the schema
 
 ## Return Values
 
diff --git a/system_prompts/auto-generated/skills/write-script-deno/SKILL.md b/system_prompts/auto-generated/skills/write-script-deno/SKILL.md
index eec2f25dfa..b15655a6da 100644
--- a/system_prompts/auto-generated/skills/write-script-deno/SKILL.md
+++ b/system_prompts/auto-generated/skills/write-script-deno/SKILL.md
@@ -56,6 +56,7 @@ Use `wmill resource-type list --schema` to discover available resource types.
 - Libraries are installed automatically - do not show installation instructions
 - In a language with an entrypoint function (TypeScript, Python, Go, Rust, PHP, R, …), name it `main` (`Main` in C#) and do not call it; in TypeScript it must be async. SQL, GraphQL, Bash, PowerShell and Ansible scripts have no `main`: their language section shows how they take arguments
 - Where the language has a Windmill client (`wmill`), use it to interact with the platform
+- A script's input schema may carry a top-level `prompt_for_ai` string: its author's instructions to an AI choosing the inputs. Follow it when you pick arguments to run that script, and keep it when you rewrite the schema
 
 ## Return Values
 
diff --git a/system_prompts/auto-generated/skills/write-script-duckdb/SKILL.md b/system_prompts/auto-generated/skills/write-script-duckdb/SKILL.md
index b2b841d0eb..2ffcf4607c 100644
--- a/system_prompts/auto-generated/skills/write-script-duckdb/SKILL.md
+++ b/system_prompts/auto-generated/skills/write-script-duckdb/SKILL.md
@@ -56,6 +56,7 @@ Use `wmill resource-type list --schema` to discover available resource types.
 - Libraries are installed automatically - do not show installation instructions
 - In a language with an entrypoint function (TypeScript, Python, Go, Rust, PHP, R, …), name it `main` (`Main` in C#) and do not call it; in TypeScript it must be async. SQL, GraphQL, Bash, PowerShell and Ansible scripts have no `main`: their language section shows how they take arguments
 - Where the language has a Windmill client (`wmill`), use it to interact with the platform
+- A script's input schema may carry a top-level `prompt_for_ai` string: its author's instructions to an AI choosing the inputs. Follow it when you pick arguments to run that script, and keep it when you rewrite the schema
 
 ## Return Values
 
diff --git a/system_prompts/auto-generated/skills/write-script-go/SKILL.md b/system_prompts/auto-generated/skills/write-script-go/SKILL.md
index 31a60a7548..1707fcda4c 100644
--- a/system_prompts/auto-generated/skills/write-script-go/SKILL.md
+++ b/system_prompts/auto-generated/skills/write-script-go/SKILL.md
@@ -56,6 +56,7 @@ Use `wmill resource-type list --schema` to discover available resource types.
 - Libraries are installed automatically - do not show installation instructions
 - In a language with an entrypoint function (TypeScript, Python, Go, Rust, PHP, R, …), name it `main` (`Main` in C#) and do not call it; in TypeScript it must be async. SQL, GraphQL, Bash, PowerShell and Ansible scripts have no `main`: their language section shows how they take arguments
 - Where the language has a Windmill client (`wmill`), use it to interact with the platform
+- A script's input schema may carry a top-level `prompt_for_ai` string: its author's instructions to an AI choosing the inputs. Follow it when you pick arguments to run that script, and keep it when you rewrite the schema
 
 ## Return Values
 
diff --git a/system_prompts/auto-generated/skills/write-script-graphql/SKILL.md b/system_prompts/auto-generated/skills/write-script-graphql/SKILL.md
index 9924e72f7f..c928dea3bc 100644
--- a/system_prompts/auto-generated/skills/write-script-graphql/SKILL.md
+++ b/system_prompts/auto-generated/skills/write-script-graphql/SKILL.md
@@ -56,6 +56,7 @@ Use `wmill resource-type list --schema` to discover available resource types.
 - Libraries are installed automatically - do not show installation instructions
 - In a language with an entrypoint function (TypeScript, Python, Go, Rust, PHP, R, …), name it `main` (`Main` in C#) and do not call it; in TypeScript it must be async. SQL, GraphQL, Bash, PowerShell and Ansible scripts have no `main`: their language section shows how they take arguments
 - Where the language has a Windmill client (`wmill`), use it to interact with the platform
+- A script's input schema may carry a top-level `prompt_for_ai` string: its author's instructions to an AI choosing the inputs. Follow it when you pick arguments to run that script, and keep it when you rewrite the schema
 
 ## Return Values
 
diff --git a/system_prompts/auto-generated/skills/write-script-java/SKILL.md b/system_prompts/auto-generated/skills/write-script-java/SKILL.md
index a28d7763cb..a768a5faa5 100644
--- a/system_prompts/auto-generated/skills/write-script-java/SKILL.md
+++ b/system_prompts/auto-generated/skills/write-script-java/SKILL.md
@@ -56,6 +56,7 @@ Use `wmill resource-type list --schema` to discover available resource types.
 - Libraries are installed automatically - do not show installation instructions
 - In a language with an entrypoint function (TypeScript, Python, Go, Rust, PHP, R, …), name it `main` (`Main` in C#) and do not call it; in TypeScript it must be async. SQL, GraphQL, Bash, PowerShell and Ansible scripts have no `main`: their language section shows how they take arguments
 - Where the language has a Windmill client (`wmill`), use it to interact with the platform
+- A script's input schema may carry a top-level `prompt_for_ai` string: its author's instructions to an AI choosing the inputs. Follow it when you pick arguments to run that script, and keep it when you rewrite the schema
 
 ## Return Values
 
diff --git a/system_prompts/auto-generated/skills/write-script-mssql/SKILL.md b/system_prompts/auto-generated/skills/write-script-mssql/SKILL.md
index 75f3827440..9215f06906 100644
--- a/system_prompts/auto-generated/skills/write-script-mssql/SKILL.md
+++ b/system_prompts/auto-generated/skills/write-script-mssql/SKILL.md
@@ -56,6 +56,7 @@ Use `wmill resource-type list --schema` to discover available resource types.
 - Libraries are installed automatically - do not show installation instructions
 - In a language with an entrypoint function (TypeScript, Python, Go, Rust, PHP, R, …), name it `main` (`Main` in C#) and do not call it; in TypeScript it must be async. SQL, GraphQL, Bash, PowerShell and Ansible scripts have no `main`: their language section shows how they take arguments
 - Where the language has a Windmill client (`wmill`), use it to interact with the platform
+- A script's input schema may carry a top-level `prompt_for_ai` string: its author's instructions to an AI choosing the inputs. Follow it when you pick arguments to run that script, and keep it when you rewrite the schema
 
 ## Return Values
 
diff --git a/system_prompts/auto-generated/skills/write-script-mysql/SKILL.md b/system_prompts/auto-generated/skills/write-script-mysql/SKILL.md
index c2f034c4f6..d682cce351 100644
--- a/system_prompts/auto-generated/skills/write-script-mysql/SKILL.md
+++ b/system_prompts/auto-generated/skills/write-script-mysql/SKILL.md
@@ -56,6 +56,7 @@ Use `wmill resource-type list --schema` to discover available resource types.
 - Libraries are installed automatically - do not show installation instructions
 - In a language with an entrypoint function (TypeScript, Python, Go, Rust, PHP, R, …), name it `main` (`Main` in C#) and do not call it; in TypeScript it must be async. SQL, GraphQL, Bash, PowerShell and Ansible scripts have no `main`: their language section shows how they take arguments
 - Where the language has a Windmill client (`wmill`), use it to interact with the platform
+- A script's input schema may carry a top-level `prompt_for_ai` string: its author's instructions to an AI choosing the inputs. Follow it when you pick arguments to run that script, and keep it when you rewrite the schema
 
 ## Return Values
 
diff --git a/system_prompts/auto-generated/skills/write-script-php/SKILL.md b/system_prompts/auto-generated/skills/write-script-php/SKILL.md
index 1052944b8e..16c68834dc 100644
--- a/system_prompts/auto-generated/skills/write-script-php/SKILL.md
+++ b/system_prompts/auto-generated/skills/write-script-php/SKILL.md
@@ -56,6 +56,7 @@ Use `wmill resource-type list --schema` to discover available resource types.
 - Libraries are installed automatically - do not show installation instructions
 - In a language with an entrypoint function (TypeScript, Python, Go, Rust, PHP, R, …), name it `main` (`Main` in C#) and do not call it; in TypeScript it must be async. SQL, GraphQL, Bash, PowerShell and Ansible scripts have no `main`: their language section shows how they take arguments
 - Where the language has a Windmill client (`wmill`), use it to interact with the platform
+- A script's input schema may carry a top-level `prompt_for_ai` string: its author's instructions to an AI choosing the inputs. Follow it when you pick arguments to run that script, and keep it when you rewrite the schema
 
 ## Return Values
 
diff --git a/system_prompts/auto-generated/skills/write-script-postgresql/SKILL.md b/system_prompts/auto-generated/skills/write-script-postgresql/SKILL.md
index 8937c078f4..b0e14a6b12 100644
--- a/system_prompts/auto-generated/skills/write-script-postgresql/SKILL.md
+++ b/system_prompts/auto-generated/skills/write-script-postgresql/SKILL.md
@@ -56,6 +56,7 @@ Use `wmill resource-type list --schema` to discover available resource types.
 - Libraries are installed automatically - do not show installation instructions
 - In a language with an entrypoint function (TypeScript, Python, Go, Rust, PHP, R, …), name it `main` (`Main` in C#) and do not call it; in TypeScript it must be async. SQL, GraphQL, Bash, PowerShell and Ansible scripts have no `main`: their language section shows how they take arguments
 - Where the language has a Windmill client (`wmill`), use it to interact with the platform
+- A script's input schema may carry a top-level `prompt_for_ai` string: its author's instructions to an AI choosing the inputs. Follow it when you pick arguments to run that script, and keep it when you rewrite the schema
 
 ## Return Values
 
diff --git a/system_prompts/auto-generated/skills/write-script-powershell/SKILL.md b/system_prompts/auto-generated/skills/write-script-powershell/SKILL.md
index c3e2bd7500..540776c68a 100644
--- a/system_prompts/auto-generated/skills/write-script-powershell/SKILL.md
+++ b/system_prompts/auto-generated/skills/write-script-powershell/SKILL.md
@@ -56,6 +56,7 @@ Use `wmill resource-type list --schema` to discover available resource types.
 - Libraries are installed automatically - do not show installation instructions
 - In a language with an entrypoint function (TypeScript, Python, Go, Rust, PHP, R, …), name it `main` (`Main` in C#) and do not call it; in TypeScript it must be async. SQL, GraphQL, Bash, PowerShell and Ansible scripts have no `main`: their language section shows how they take arguments
 - Where the language has a Windmill client (`wmill`), use it to interact with the platform
+- A script's input schema may carry a top-level `prompt_for_ai` string: its author's instructions to an AI choosing the inputs. Follow it when you pick arguments to run that script, and keep it when you rewrite the schema
 
 ## Return Values
 
diff --git a/system_prompts/auto-generated/skills/write-script-python3/SKILL.md b/system_prompts/auto-generated/skills/write-script-python3/SKILL.md
index b030ff4316..b9c2793f47 100644
--- a/system_prompts/auto-generated/skills/write-script-python3/SKILL.md
+++ b/system_prompts/auto-generated/skills/write-script-python3/SKILL.md
@@ -56,6 +56,7 @@ Use `wmill resource-type list --schema` to discover available resource types.
 - Libraries are installed automatically - do not show installation instructions
 - In a language with an entrypoint function (TypeScript, Python, Go, Rust, PHP, R, …), name it `main` (`Main` in C#) and do not call it; in TypeScript it must be async. SQL, GraphQL, Bash, PowerShell and Ansible scripts have no `main`: their language section shows how they take arguments
 - Where the language has a Windmill client (`wmill`), use it to interact with the platform
+- A script's input schema may carry a top-level `prompt_for_ai` string: its author's instructions to an AI choosing the inputs. Follow it when you pick arguments to run that script, and keep it when you rewrite the schema
 
 ## Return Values
 
diff --git a/system_prompts/auto-generated/skills/write-script-rlang/SKILL.md b/system_prompts/auto-generated/skills/write-script-rlang/SKILL.md
index 626b602749..061e1dcc45 100644
--- a/system_prompts/auto-generated/skills/write-script-rlang/SKILL.md
+++ b/system_prompts/auto-generated/skills/write-script-rlang/SKILL.md
@@ -56,6 +56,7 @@ Use `wmill resource-type list --schema` to discover available resource types.
 - Libraries are installed automatically - do not show installation instructions
 - In a language with an entrypoint function (TypeScript, Python, Go, Rust, PHP, R, …), name it `main` (`Main` in C#) and do not call it; in TypeScript it must be async. SQL, GraphQL, Bash, PowerShell and Ansible scripts have no `main`: their language section shows how they take arguments
 - Where the language has a Windmill client (`wmill`), use it to interact with the platform
+- A script's input schema may carry a top-level `prompt_for_ai` string: its author's instructions to an AI choosing the inputs. Follow it when you pick arguments to run that script, and keep it when you rewrite the schema
 
 ## Return Values
 
diff --git a/system_prompts/auto-generated/skills/write-script-rust/SKILL.md b/system_prompts/auto-generated/skills/write-script-rust/SKILL.md
index 0f4a95bbe2..d9b599dffa 100644
--- a/system_prompts/auto-generated/skills/write-script-rust/SKILL.md
+++ b/system_prompts/auto-generated/skills/write-script-rust/SKILL.md
@@ -56,6 +56,7 @@ Use `wmill resource-type list --schema` to discover available resource types.
 - Libraries are installed automatically - do not show installation instructions
 - In a language with an entrypoint function (TypeScript, Python, Go, Rust, PHP, R, …), name it `main` (`Main` in C#) and do not call it; in TypeScript it must be async. SQL, GraphQL, Bash, PowerShell and Ansible scripts have no `main`: their language section shows how they take arguments
 - Where the language has a Windmill client (`wmill`), use it to interact with the platform
+- A script's input schema may carry a top-level `prompt_for_ai` string: its author's instructions to an AI choosing the inputs. Follow it when you pick arguments to run that script, and keep it when you rewrite the schema
 
 ## Return Values
 
diff --git a/system_prompts/auto-generated/skills/write-script-snowflake/SKILL.md b/system_prompts/auto-generated/skills/write-script-snowflake/SKILL.md
index 99af11e419..8c438e7038 100644
--- a/system_prompts/auto-generated/skills/write-script-snowflake/SKILL.md
+++ b/system_prompts/auto-generated/skills/write-script-snowflake/SKILL.md
@@ -56,6 +56,7 @@ Use `wmill resource-type list --schema` to discover available resource types.
 - Libraries are installed automatically - do not show installation instructions
 - In a language with an entrypoint function (TypeScript, Python, Go, Rust, PHP, R, …), name it `main` (`Main` in C#) and do not call it; in TypeScript it must be async. SQL, GraphQL, Bash, PowerShell and Ansible scripts have no `main`: their language section shows how they take arguments
 - Where the language has a Windmill client (`wmill`), use it to interact with the platform
+- A script's input schema may carry a top-level `prompt_for_ai` string: its author's instructions to an AI choosing the inputs. Follow it when you pick arguments to run that script, and keep it when you rewrite the schema
 
 ## Return Values
 
diff --git a/system_prompts/base/flow-base.md b/system_prompts/base/flow-base.md
index b0a8998604..5c5c93411d 100644
--- a/system_prompts/base/flow-base.md
+++ b/system_prompts/base/flow-base.md
@@ -414,6 +414,10 @@ The step's `input_transforms` must cover the reused item's inputs, so read its i
 Find candidates in the local tree (a `.script.yaml` sits next to each script and holds its input schema, a `flow.yaml` in each flow folder) and on the workspace with `wmill script list` / `wmill flow list`; `wmill script get <path>` and `wmill flow get <path>` show an item's details.
 <!-- /cli-only -->
 
+## Additional Prompt for AI
+
+A flow's input schema may carry a top-level `prompt_for_ai` string, as a script's can: its author's instructions to an AI choosing the inputs. Follow it when you pick arguments to run that flow, and keep it when you rewrite the schema.
+
 ## Organizing Flows: Groups and Notes
 
 Groups and notes shape how a flow reads in the editor; neither changes what it does.
diff --git a/system_prompts/base/script-base.md b/system_prompts/base/script-base.md
index 2641d7cd0a..9bd878ea9b 100644
--- a/system_prompts/base/script-base.md
+++ b/system_prompts/base/script-base.md
@@ -6,6 +6,7 @@
 - Libraries are installed automatically - do not show installation instructions
 - In a language with an entrypoint function (TypeScript, Python, Go, Rust, PHP, R, …), name it `main` (`Main` in C#) and do not call it; in TypeScript it must be async. SQL, GraphQL, Bash, PowerShell and Ansible scripts have no `main`: their language section shows how they take arguments
 - Where the language has a Windmill client (`wmill`), use it to interact with the platform
+- A script's input schema may carry a top-level `prompt_for_ai` string: its author's instructions to an AI choosing the inputs. Follow it when you pick arguments to run that script, and keep it when you rewrite the schema
 
 ## Return Values