write-script-powershell_skill

Overview

This skill teaches how to write PowerShell scripts that integrate with the Windmill/wmill platform and how to prepare them for deployment. It covers parameter declaration, typing, structured return values, and the CLI steps to generate metadata and push scripts. The guidance focuses on predictable inputs/outputs so scripts run reliably as webhooks, tasks, or UI-driven actions.

How this skill works

Scripts declare inputs with a param(...) block on the first line so the runtime can pass arguments in reliably. You can annotate parameter types (string, int, bool, array) and set defaults, which improves validation and UX in automation platforms. Return structured objects by outputting a hashtable or object at the end of the script; Windmill captures that output as the script result. After authoring, use the CLI to generate metadata and deploy so the platform can expose the script as a resource.

When to use it

• When building PowerShell tasks to run as server-side steps or webhooks.
• When you need typed parameters for validation and clearer platform UIs.
• When returning structured data to downstream workflows or APIs.
• When packaging scripts for automated deployment and versioning with the Windmill CLI.
• When exposing scripts as reusable resources for low-code UIs or workflows.

Best practices

• Always put param(...) on the first line to ensure argument parsing works correctly.
• Prefer explicit parameter types and sensible defaults to prevent runtime errors and improve auto-generated forms.
• Return a single structured object (hashtable) containing status and data to standardize downstream handling.
• Use Get-Date -Format "o" or ISO 8601 for timestamps to keep outputs interoperable.
• Run wmill script generate-metadata before pushing to create .script.yaml and lock files for reproducible deployments.

Example use cases

• Create a script that accepts a username and count, processes data, and returns a result object for use in a workflow.
• Write a PowerShell webhook that validates incoming payloads using typed parameters and returns detailed status and errors.
• Pack scripts that query a database or external API and return normalized data structures for dashboards or UIs.
• Automate operational tasks (users, backups, config) as versioned scripts that can be pushed and invoked by other services.