powershell-windows - Agent Skills

PowerShell Windows Patterns

> Critical patterns and pitfalls for Windows PowerShell.

1. Operator Syntax Rules

CRITICAL: Parentheses Required

❌ Wrong	✅ Correct
`if (Test-Path "a" -or Test-Path "b")`	`if ((Test-Path "a") -or (Test-Path "b"))`
`if (Get-Item $x -and $y -eq 5)`	`if ((Get-Item $x) -and ($y -eq 5))`

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

2. Unicode/Emoji Restriction

CRITICAL: No Unicode in Scripts

Purpose	❌ Don't Use	✅ Use
Success	✅ ✓	[OK] [+]
Error	❌ ✗ 🔴	[!] [X]
Warning	⚠️ 🟡	[*] [WARN]
Info	ℹ️ 🔵	[i] [INFO]
Progress	⏳	[...]

Rule: Use ASCII characters only in PowerShell scripts.

3. Null Check Patterns

Always Check Before Access

❌ Wrong	✅ Correct
`$array.Count -gt 0`	`$array -and $array.Count -gt 0`
`$text.Length`	`if ($text) { $text.Length }`

4. String Interpolation

Complex Expressions

❌ Wrong	✅ Correct
`"Value: $($obj.prop.sub)"`	Store in variable first

Pattern:

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

5. Error Handling

ErrorActionPreference

Value	Use
Stop	Development (fail fast)
Continue	Production scripts
SilentlyContinue	When errors expected

Try/Catch Pattern

Don't return inside try block

Use finally for cleanup

Return after try/catch

6. File Paths

Windows Path Rules

Pattern	Use
Literal path	`C:\Users\User\file.txt`
Variable path	`Join-Path $env:USERPROFILE "file.txt"`
Relative	`Join-Path $ScriptDir "data"`

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

7. Array Operations

Correct Patterns

Operation	Syntax
Empty array	`$array = @()`
Add item	`$array += $item`
ArrayList add	`$list.Add($item)`

8. JSON Operations

CRITICAL: Depth Parameter

❌ Wrong	✅ Correct
`ConvertTo-Json`	`ConvertTo-Json -Depth 10`

Rule: Always specify -Depth for nested objects.

`File Operations`

Operation	Pattern
Read	Get-Content "file.json" -Raw
Write	`$data

`9. Common Errors`

Error Message	Cause	Fix
"parameter 'or'"	Missing parentheses	Wrap cmdlets in ()
"Unexpected token"	Unicode character	Use ASCII only
"Cannot find property"	Null object	Check null first
"Cannot convert"	Type mismatch	Use .ToString()

`10. Script Template`

# Strict mode
Set-StrictMode -Version Latest
$ErrorActionPreference = "Continue"
Paths

$ScriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path
Main

try {
    # Logic here
    Write-Output "[OK] Done"
    exit 0
}
catch {
    Write-Warning "Error: $_"
    exit 1
}

> Remember: PowerShell has unique syntax rules. Parentheses, ASCII-only, and null checks are non-negotiable.