Write Reliable PowerShell Automation
Build PowerShell commands with object output, explicit error handling, literal paths, and safe preview behavior.
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 linesWrite 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
Related Skills
Chalk Picocolors
Style terminal output with chalk and picocolors for colored, formatted CLI text
Clack Prompts
Build beautiful interactive CLI prompts using @clack/prompts with minimal boilerplate
CLI Distribution
Package and distribute CLI tools via npm/npx, standalone binaries with pkg, and Homebrew taps
CLI Testing
Test CLI applications using subprocess execution, mock filesystems, and snapshot testing
Commander Js
Build structured CLI applications with Commander.js including commands, options, and argument parsing
Ink React CLI
Build rich interactive terminal UIs using Ink, a React renderer for the command line