home / skills / xfstudio / skills / powershell-windows

powershell-windows skill

safe

This skill analyzes PowerShell Windows patterns to highlight critical syntax, error handling, and ASCII-only scripting practices.

This is most likely a fork of the powershell-windows skill from vudovn

npx playbooks add skill xfstudio/skills --skill powershell-windows

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

3.4 KB

---
name: powershell-windows
description: PowerShell Windows patterns. Critical pitfalls, operator syntax, error handling.
allowed-tools: Read, Write, Edit, Glob, Grep, Bash
---

# 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) | Out-Null` |

---

## 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 | ConvertFrom-Json` |
| Write | `$data | ConvertTo-Json -Depth 10 | Out-File "file.json" -Encoding UTF8` |

---

## 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

```powershell
# 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.

Overview

This skill packages essential PowerShell Windows patterns focused on operator syntax, error handling, null checks, path rules, and JSON handling. It highlights critical pitfalls and prescriptive fixes so scripts are predictable, robust, and cross-platform friendly. Use it to harden scripts, reduce runtime surprises, and adopt consistent conventions.

How this skill works

The skill inspects common PowerShell constructs and enforces concrete rules: wrap cmdlet expressions in parentheses when using logical operators, avoid Unicode/emoji in scripts, check for null before property access, and always specify JSON depth. It also provides patterns for error handling (ErrorActionPreference, try/catch/finally), safe path construction with Join-Path, array management, and file I/O best practices. Example templates and fixes for frequent error messages are included.

When to use it

Writing or reviewing PowerShell scripts for Windows
Building automation that must be robust across environments
Converting quick one-liners into production-safe functions
Working with nested JSON or complex object graphs
Hardening CI/CD scripts and deployment tools

Best practices

Wrap every cmdlet call in parentheses when using -and/-or/-not to avoid operator parsing errors
Use ASCII-only characters in scripts; replace emojis/unicode with simple tokens like [OK], [WARN], [X]
Always null-check objects/collections before accessing properties (e.g., $obj -and $obj.Prop)
Use Join-Path and $ScriptDir for file paths to avoid hardcoded separators
Specify -Depth with ConvertTo-Json for nested objects and use -Raw when reading JSON files
Set ErrorActionPreference appropriately; use Try/Catch/Finally and avoid returning inside try blocks

Example use cases

Validate and refactor an existing script to fix 'parameter "or"' and 'Unexpected token' errors
Create a reliable JSON read/write routine for nested configuration objects
Standardize path handling in scripts used across tools and CI agents
Implement fail-fast development behavior with ErrorActionPreference = 'Stop' and production-safe 'Continue'
Build a template script that includes strict mode, path resolution, and structured error handling

FAQ

Why must cmdlet calls be in parentheses with logical operators?

PowerShell parses -and/-or between expressions, not between cmdlet calls. Parentheses force evaluation of each cmdlet result and prevent unexpected "parameter 'or'" or parsing errors.

Can I ever use Unicode or emojis in scripts?

Avoid them in script source and identifiers. Unicode can cause unexpected token errors in the parser and break tooling. Use plain ASCII tokens like [OK], [WARN], [X] for readability.