Skip to main content
Technology & EngineeringCLI Development30 lines

Write Reliable PowerShell Automation

Build PowerShell commands with object output, explicit error handling, literal paths, and safe preview behavior.

Quick Summary8 lines
Record whether the script must support Windows PowerShell 5.1, PowerShell 7, or both. Specify parameters, required scope, output object shape, and exit behavior. Make the default invocation read-only when users need to review planned changes. Keep data on the success output stream as typed or custom objects. Format results for display at the call site, so a caller can sort and filter properties without parsing text.

## Key Points

- [PowerShell error handling](https://learn.microsoft.com/en-us/PowerShell/module/microsoft.PowerShell.core/about/about_error_handling?view=powershell-5.1)
- [PowerShell ShouldProcess](https://learn.microsoft.com/en-us/powershell/scripting/learn/deep-dives/everything-about-shouldprocess)
skilldb get cli-development-skills/powershell-automationFull skill: 30 lines
Paste into your CLAUDE.md or agent config

Write Reliable PowerShell Automation

Define the command contract

Record whether the script must support Windows PowerShell 5.1, PowerShell 7, or both. Specify parameters, required scope, output object shape, and exit behavior. Make the default invocation read-only when users need to review planned changes. Keep data on the success output stream as typed or custom objects. Format results for display at the call site, so a caller can sort and filter properties without parsing text.

For file work, accept a base directory and explicit child paths. Use -LiteralPath for names interpreted as exact paths. Resolve the base and candidate before any recursive move or delete, and verify containment with path components rather than a naive string prefix. Consider junctions or other links when they can escape the intended directory. Never build a command string from untrusted arguments. Use native cmdlets or pass arguments directly to a fixed executable.

Make failures observable

Use an advanced function when the command needs common parameters or ShouldProcess. For each state change, wrap the exact target and operation in the supported ShouldProcess decision. Test -WhatIf on a fixture and inspect the filesystem afterward. Avoid creating directories, side files, or partial outputs during an operation advertised as a preview. Keep an ordinary read-only mode distinct if the script also needs to collect input.

Some cmdlet failures are non-terminating by default. Use scoped -ErrorAction Stop at operations that must complete for later steps to be safe. Handle expected errors with actionable context, and propagate unexpected ones. Check $LASTEXITCODE for native programs in execution paths where PowerShell does not turn their failure into a terminating error. Capture it before another native command runs. Return a failure to the caller when the script cannot produce its stated result.

Prove repeatability

Start with a fixture directory that includes a filename with spaces and brackets, an unreadable or missing path, and an existing destination. Confirm a clean run emits a predictable object sequence and a second run is safe. Verify that preview leaves file hashes unchanged and that denied or failed actions leave a useful error rather than a success record. If calling a native tool, exercise both successful and nonzero exit statuses.

Record PowerShell version, input root, script command, and the states observed before and after. Keep diagnostics and sensitive input out of default output. Give unattended callers a stable exit and output contract so they can act on a partial failure.

References

Install this skill directly: skilldb add cli-development-skills

Get CLI access →