home / skills / windmill-labs / windmill / write-script-powershell

write-script-powershell skill

safe

/system_prompts/auto-generated/skills/write-script-powershell

This skill helps you write PowerShell scripts by illustrating parameter declarations, typing, and structured return values for clear, reusable automation.

npx playbooks add skill windmill-labs/windmill --skill write-script-powershell

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

1.1 KB

---
name: write-script-powershell
description: MUST use when writing PowerShell scripts.
---

## CLI Commands

Place scripts in a folder. After writing, run:
- `wmill script generate-metadata` - Generate .script.yaml and .lock files
- `wmill sync push` - Deploy to Windmill

Use `wmill resource-type list --schema` to discover available resource types.

# PowerShell

## Structure

Arguments are obtained by calling the `param` function on the first line:

```powershell
param($Name, $Count = 0, [int]$Age)

# Your code here
Write-Output "Processing $Name, count: $Count, age: $Age"

# Return object
@{
    name = $Name
    count = $Count
    age = $Age
}
```

## Parameter Types

You can specify types for parameters:

```powershell
param(
    [string]$Name,
    [int]$Count = 0,
    [bool]$Enabled = $true,
    [array]$Items
)

@{
    name = $Name
    count = $Count
    enabled = $Enabled
    items = $Items
}
```

## Return Values

Return values by outputting them at the end of the script:

```powershell
param($Input)

$result = @{
    processed = $true
    data = $Input
    timestamp = Get-Date -Format "o"
}

$result
```

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.

FAQ

How do I declare optional parameters?

Set a default value in the param block, e.g. [int]$Count = 0. Parameters with defaults are optional.

How should I return data from the script?

Output a hashtable or PSCustomObject at the end of the script. The platform captures the final output as the result.

What CLI steps are required to deploy a script?

Run wmill script generate-metadata to create metadata and lock files, then wmill sync push to deploy the script.