powershell-windows_skill

Overview

This skill documents essential PowerShell Windows patterns focused on operator syntax, error handling, null checks, and common pitfalls. It condenses rules that prevent frequent runtime errors and maintain script portability and reliability. Use it as a checklist when writing or reviewing PowerShell scripts for Windows environments.

How this skill works

The skill highlights critical syntax requirements (notably parentheses around cmdlet calls when using logical operators), enforces ASCII-only script content, and presents safe patterns for null checks, string interpolation, file and JSON operations, and array handling. It explains ErrorActionPreference and a recommended try/catch/finally flow, plus a minimal strict-mode script template for robust scripts. Follow the examples to avoid typical runtime errors and maintain consistent output formatting.

When to use it

• When authoring new PowerShell scripts for Windows to avoid syntax and runtime errors
• When refactoring scripts to be more robust and cross-platform safe (path handling)
• During code review to check for null-safety, operator misuse, and Unicode issues
• When handling JSON serialization/deserialization of nested objects
• When standardizing error handling and exit behavior across scripts

Best practices

• Wrap each cmdlet call in parentheses when using -and, -or, -not to avoid parser errors
• Use ASCII characters only in code and message tokens to prevent unexpected tokens
• Always check objects for null before accessing properties or Count
• Use Join-Path for building paths and $ScriptDir for script-relative files
• Specify -Depth with ConvertTo-Json for nested objects and use -Raw with Get-Content

Example use cases

• A deployment script that must reliably test multiple paths with logical operators
• A logging utility that needs ASCII-only status tokens for downstream parsers
• Reading and writing deeply nested configuration objects as JSON with -Depth
• A module that needs strict null checks before property access to avoid exceptions
• A maintenance script using Try/Catch/Finally with consistent exit codes