powershell

name	powershell
description	Enterprise PowerShell coding standards. Use when writing, reviewing, or generating any PowerShell code, creating PS1 scripts or functions, debugging PowerShell, or asked to help with PowerShell. Enforces best practices for structure, error handling, security, performance, and output patterns.

This skill enforces enterprise-grade PowerShell standards when writing, reviewing, or generating any PowerShell code. Apply all rules below automatically — do not wait to be asked.

Triggers

• "write a PowerShell script"
• "create a function in PowerShell"
• "review this PowerShell"
• "generate a PS1 file"
• "help me with PowerShell code"

---

Resource Files

Load these when needed for detailed patterns, examples, and gotchas:

File	When to load
resources/common-patterns.md	Need a code pattern (script skeleton, error handling, collections, splatting, regex, pipeline functions, string building, hashtable lookups, safe property accessor helper, module structure, ShouldProcess+Force, etc.)
resources/compatibility-and-clm.md	Need PS5.1 vs PS7+ compatibility details, String.Split() changes, $IsWindows portability, or writing code that may run under AppLocker/WDAC (CLM)
resources/traps-and-gotchas.md	Debugging unexpected behaviour around nulls, booleans, comparison operators, pipeline output pollution, $PSBoundParameters, VerbosePreference in modules, PS class limitations, or defensive null-safe patterns (property access guards, ContainsKey null guards, hashtable key/value guards, null loop entries, Add-Member verification, array double-wrapping)
resources/get-help-and-get-member.md	Using an unfamiliar cmdlet or object — discover parameters, properties, and online docs before writing code
resources/performance-patterns.md	Writing performance-sensitive code — benchmarked patterns for collections, strings, filtering, object creation, hashtable lookups, large file processing, function call overhead
resources/api-and-web.md	Calling REST APIs — authentication, pagination, rate limiting/retry, JSON depth, credential management, PSReadLine history protection
resources/security-hardening.md	Security controls — CLM enforcement (WDAC vs AppLocker), PowerShell logging (Module/Script Block/Transcription), Protected Event Logging, JEA, code signing, script injection prevention

---

Quick Reference

Area	Rule
Structure	#Requires → help → param() → Functions → Main → Cleanup
Strict Mode	Set-StrictMode -Version Latest always
Indent	4 spaces, ≤120 chars per line
Encoding	UTF-8 without BOM; always specify -Encoding utf8NoBOM explicitly
Naming	PascalCase functions/params, camelCase locals
Functions	Always [CmdletBinding()]; Verb-Noun singular nouns
State-changing	SupportsShouldProcess + $PSCmdlet.ShouldProcess()
Output	Emit [PSCustomObject]; never Write-Host for data
Errors	try/catch with -ErrorAction Stop; never empty catch
Arrays	Capture foreach output directly — never += in loops
WMI	Get-CimInstance not Get-WmiObject
Events	Get-WinEvent not Get-EventLog
Secrets	PSCredential/SecureString/SecretManagement vault — no plaintext
Native cmds	Check $LASTEXITCODE after native executables; use try/catch for cmdlets
Aliases	No aliases in scripts — always full cmdlet names
Paths	Join-Path $PSScriptRoot 'file.csv' — never assume working directory
CLM	Check $ExecutionContext.SessionState.LanguageMode; avoid .NET::new(), Add-Type if CLM is possible

---

Critical Rules

These are non-negotiable. Apply them to every script and function.

1. Set-StrictMode -Version Latest at the top of every script (not inside functions).
2. [CmdletBinding()] on every advanced function, no exceptions.
3. -ErrorAction Stop on every cmdlet call inside a try block, or set $ErrorActionPreference = 'Stop' for the scope. Non-terminating errors do NOT trigger catch without this.
4. Never empty catch blocks. Always log at minimum Write-Warning or Write-Error.
5. Save $_ immediately at the start of a catch block: $err = $_
6. No += in loops. Capture foreach output directly, or use [System.Collections.Generic.List[PSObject]]::new() + .Add() in FullLanguage mode only.
7. No Invoke-Expression on untrusted or constructed input — ever.
8. No plaintext credentials in code, parameters, or log output.
9. No aliases in scripts (%, ?, gci, ft, etc.).
10. No Format-* mid-pipeline — emit objects; let the caller format.
11. SupportsShouldProcess on any function that modifies state (files, registry, AD, etc.).
12. No begin/process/end at script top level — only inside pipeline-aware functions.
13. No positional parameters in scripts — always use named parameters (e.g., Get-Item -Path $p not Get-Item $p).
14. Always specify -Encoding on file I/O cmdlets — default encoding differs between PS5.1 and PS7+.

---

Anti-Patterns

Anti-Pattern	Replace With
Get-WmiObject	Get-CimInstance
Get-EventLog	Get-WinEvent -FilterHashtable @{...}
$array += $item in loops	Capture foreach output, or [List[PSObject]]::new() + .Add()
Write-Host for data output	Write-Output / emit objects
Format-Table mid-pipeline	Emit objects; format at end
Invoke-Expression $cmd	Parameterised calls / splatting
Plaintext password in param	[PSCredential] + SecretManagement
Empty catch {}	Always log or re-throw
$? after native executables	$LASTEXITCODE (for cmdlets use try/catch)
ConvertTo-Json without -Depth	Always ConvertTo-Json -Depth 10 (default 2 silently truncates)
$global: for cross-function state	$script: scope — contained to the script file
Building HTML without encoding	Regex replace for 5 HTML special chars (CLM-safe); HttpUtility in FullLanguage only
Read-Host for required input	[Parameter(Mandatory)]
Aliases (gci, %, ?)	Full cmdlet names
begin/process/end at script top	Only inside pipeline-aware functions
Positional parameters (Get-Item $p)	Named parameters (Get-Item -Path $p)
Out-Null in hot paths	[void](...) or $null = ... (no pipeline overhead)
Where-Object when source has -Filter	Use -Filter on the source cmdlet
ForEach-Object { $_.Prop } for single property	Select-Object -ExpandProperty Prop
New-Object PSObject -Property @{}	[PSCustomObject]@{} (3x faster, cleaner)
[array]::new() or List[T]::new() in CLM	Capture foreach output directly
Add-Type in potentially CLM environments	Cmdlet-based alternatives
continue inside ForEach-Object	return (acts as continue in pipeline context)
if ($array -eq $null)	if ($null -eq $array) (left-side null check)
if ($results) to test for empty collection	if ($results.Count -gt 0)
-Encoding utf8 without knowing PS version	-Encoding utf8NoBOM (explicit, portable)
"abc" -contains "ab" for substring	"abc".Contains("ab") or "abc" -match "ab"
-like "pattern\d+" (regex in glob)	-match "pattern\d+" for regex patterns
String "False" as a boolean	Explicit -eq 'True' or -eq $true comparison
$list.Add($item) on ArrayList	[void]$list.Add($item) — .Add() returns the index to the pipeline
New-Item/New-Object output leaked	$null = New-Item ... or assign to variable
Write-Output $x (usually)	Just emit $x implicitly; use Write-Output -NoEnumerate only for arrays
Inconsistent output types per code path	Always emit the same type; use error stream for errors
No [OutputType()] on functions	Declare [OutputType([PSCustomObject])] on functions with defined output
Invoke-RestMethod without $ProgressPreference	Set $ProgressPreference = 'SilentlyContinue' at script top for non-interactive use
Parameter named Verbose, Debug, WhatIf, etc.	These are reserved by [CmdletBinding()] — rename to avoid conflicts
Parameter named Error, Input, Host, Args	These shadow automatic variables — use distinct names
$string += "text" in loops	-join operator (790× faster at scale)
Nested Where-Object for cross-collection joins	Hashtable lookup — O(n+m) vs O(n×m)
FunctionsToExport = '*' in manifest	Explicit function list — avoids ~15s import penalty
"str".Split('ab') for multi-char splitting	"str".Split([char[]]'ab') — portable across PS5.1 and PS7+
if ($IsWindows) without edition check	$PSVersionTable.PSEdition -eq 'Desktop' -or $IsWindows
Invoke-RestMethod -Authentication + manual Authorization header	Use only one — -Authentication silently overrides the header
-FollowRelLink without -MaximumFollowRelLink	Always set -MaximumFollowRelLink to prevent infinite loops
Class method with implicit output	Class methods discard all output except return — assign or return explicitly
Import-Module MyModule; [ClassType]::new()	using module MyModule required for class types
hidden property assumed private	hidden properties ARE serialized by ConvertTo-Json
$obj.Prop on object that may lack Prop	if ($obj.PSObject.Properties['Prop']) { $obj.Prop } — safe under Set-StrictMode and avoids PropertyNotFoundException
$hash[$key] without null-guarding the key	if ($key) { $hash[$key] } — null key crashes Dictionary<TKey,TValue>; guard first
$hash.ContainsKey($key) without null guard	$key -and $hash.ContainsKey($key) — null argument throws on Dictionary<> types
Loop body with no null guard on $item	if ($null -eq $item) { continue } at top — API/pipeline collections can contain null entries
Building lookup without guarding key or value	Check if ($id -and $value) before $lookup[$id] = $value — null keys create silent corrupt entries
`$connector	Add-Member ...; $connector._Prop`
return ,$array in function + @(Func) at call site	Double-wrap bug: $items = @(Func) when function returns ,$arr gives a 1-element wrapper; use direct assignment $items = Func

---

Review Checklist

Before finalising any generated PowerShell, verify:

• Set-StrictMode -Version Latest present at script top
• [CmdletBinding()] on every advanced function
• -ErrorAction Stop on all cmdlet calls in try blocks (or $ErrorActionPreference = 'Stop' set)
• No empty catch blocks; $err = $_ saved at catch start
• No += inside loops for collection building
• No aliases used anywhere
• No Write-Host used for data (only acceptable for interactive UI messaging)
• No Invoke-Expression on dynamic/user-supplied input
• No plaintext secrets in code or output
• SupportsShouldProcess on all state-modifying functions
• finally block for any resource cleanup
• Output is objects ([PSCustomObject]), not pre-formatted strings
• Get-CimInstance used instead of Get-WmiObject
• $LASTEXITCODE checked after every native executable call
• $PSScriptRoot used for all paths relative to the script file
• Parameter variables not mutated; copied to local variables first
• Lines ≤120 characters; 4-space indentation throughout
• No positional parameter usage — all parameters named explicitly
• -Encoding utf8NoBOM specified on all file I/O operations
• $null is on the LEFT side of all null comparisons
• Empty collection checked with .Count -eq 0, not bare if ($collection)
• @($results) used when .Count is needed on cmdlet output
• return (not continue) used to skip items in ForEach-Object
• CLM-unsafe patterns (.NET::new(), Add-Type) avoided if script may run under AppLocker/WDAC
• PS7-only syntax (??, ? :, -Parallel) annotated or avoided if PS5.1 support required
• -Filter used on source cmdlets rather than downstream Where-Object where possible
• -like used for glob patterns, -match used for regex — not mixed
• -contains/-in used for collection membership, not string substring checks
• [void]$list.Add(...) used when calling ArrayList.Add() (it returns the index)
• Intermediate cmdlets (New-Item, New-Object, etc.) inside functions have their output suppressed or assigned
• No parameter names clash with common parameters (Verbose, Debug, WhatIf, Confirm, ErrorAction, etc.)
• No parameter names shadow automatic variables (Error, Input, Host, Args, This)
• [OutputType()] declared on functions that emit a defined object type
• $ProgressPreference = 'SilentlyContinue' set in non-interactive scripts that call Invoke-WebRequest/Invoke-RestMethod
• Write-Host not used for data — only for interactive UI messages
• String building in loops uses -join, not += (790× slower at scale)
• Cross-collection joins use hashtable lookup, not nested Where-Object (O(n+m) vs O(n×m))
• Module manifest uses explicit FunctionsToExport list, not '*' (~15s penalty at import)
• String.Split() with multi-char argument uses [char[]] cast for portable behaviour
• $IsWindows portability uses $PSVersionTable.PSEdition -eq 'Desktop' -or $IsWindows
• External/API object property access is guarded: if ($obj.PSObject.Properties['Prop']) before $obj.Prop (strict-mode-safe)
• Hashtable keys are null-guarded before indexing: if ($key) { $hash[$key] } not bare $hash[$key]
• ContainsKey() calls are null-guarded: $key -and $hash.ContainsKey($key)
• Loop bodies guard against null items at the top: if ($null -eq $item) { continue }
• Lookup hashtable population guards both key and value before inserting: if ($id -and $value) { $lookup[$id] = $value }
• Add-Member note properties are verified before access: if ($obj.PSObject.Properties['_Name']) { $obj._Name }
• Functions using return ,$array convention are called with direct assignment ($x = Func), NOT $x = @(Func) (double-wrap bug)