sickn33/antigravity-awesome-skills/powershell-windows

PowerShell Windows Patterns

Critical patterns and pitfalls for Windows PowerShell.

1. Operator Syntax Rules

CRITICAL: Parentheses Required

Rule: Each cmdlet call MUST be in parentheses when using logical operators.

2. Encoding Compatibility

Prefer portable log markers

PowerShell supports Unicode. ASCII log markers are a portability choice, not a syntax requirement. For non-ASCII scripts read by Windows PowerShell 5.1, use UTF-8 with BOM; PowerShell 7 uses UTF-8 without BOM by default. Check the consuming tool before choosing file encoding.

3. Null Check Patterns

Always Check Before Access

4. String Interpolation

Complex Expressions

"Value: $($obj.prop.sub)" is valid subexpression interpolation. Store a complex expression in a variable when that improves readability.

Pattern:

$value = $obj.prop.sub
Write-Output "Value: $value"

5. Error Handling

ErrorActionPreference

Try/Catch Pattern

• A return inside try is valid; finally still runs
• Use finally for cleanup
• Return after try/catch

6. File Paths

Windows Path Rules

Rule: Use Join-Path for cross-platform safety.

7. Array Operations

Correct Patterns

8. JSON Operations

CRITICAL: Depth Parameter

Rule: Always specify -Depth for nested objects.

File Operations

9. Common Errors

10. Script Template

# Strict mode
Set-StrictMode -Version Latest
$ErrorActionPreference = "Stop"
 
# Paths
$ScriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path
 
# Main
try {
    # Cmdlet logic here; check $LASTEXITCODE after native executables.
    Write-Output "[OK] Done"
    exit 0
}
catch {
    Write-Warning "Error: $_"
    exit 1
}

Remember: Check shell version, encoding, null semantics and native exit codes. try/catch alone does not reliably turn native command failures into exceptions.

References: encoding, quoting.

When to Use

Use when writing or debugging Windows PowerShell or PowerShell 7 scripts, especially command expressions, encoding, paths and error handling.

Limitations

• Use this skill only when the task clearly matches the scope described above.
• Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
• Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.