Powershell

---
name: powershell
description: "PowerShell 7.4/7.6 LTS cross-platform scripting and automation: object-oriented pipelines, advanced functions with CmdletBinding, error handling (try/catch, ErrorActionPreference), module management (PSGallery, PSGet), remoting (WinRM, SSH), parallel execution (ForEach-Object -Parallel, ThreadJobs, Runspaces), and structured data processing (JSON, CSV, XML). Covers Windows and Linux/macOS administration, REST API interaction, and .NET interop. WHEN: \"PowerShell\", \"pwsh\", \"cmdlet\", \"pipeline\", \".ps1\", \"PSObject\", \"PSCustomObject\", \"Invoke-RestMethod\", \"Invoke-WebRequest\", \"CIM\", \"WMI\", \"Get-ChildItem\", \"ForEach-Object\", \"Where-Object\", \"Select-Object\", \"ConvertTo-Json\", \"Import-Csv\", \"Export-Csv\", \"Start-Job\", \"Start-ThreadJob\", \"PSReadLine\", \"module\", \"PSGallery\", \"splatting\", \"ValidateSet\", \"ErrorActionPreference\", \"$ErrorActionPreference\", \"PowerShell 7\"."
license: MIT
---

# PowerShell Technology Expert

This skill covers PowerShell 7.4/7.6 LTS cross-platform scripting and automation. It has deep coverage of:

- Object-oriented pipeline architecture (everything is a .NET object)
- Advanced functions with CmdletBinding, parameter validation, ShouldProcess
- Error handling: try/catch/finally, ErrorActionPreference, ErrorRecord anatomy
- String interpolation, here-strings, regex (-match, Select-String, [regex])
- Collections: arrays, ArrayList, Generic.List, hashtables, ordered, splatting
- Module management: PSGallery, PSGet, creating .psm1/.psd1 modules
- Remoting: WinRM, SSH-based remoting, Invoke-Command, Enter-PSSession
- Parallel execution: ForEach-Object -Parallel, Start-ThreadJob, Runspaces
- Data processing: CSV (Import/Export-Csv), JSON (ConvertTo/From-Json), XML
- REST API interaction: Invoke-RestMethod, Invoke-WebRequest, auth patterns
- Cross-platform support: $IsWindows, $IsLinux, $IsMacOS, platform-specific code
- Output formatting: Format-Table, Format-List, PSStyle, ANSI colors, Write-* streams

## How to Approach Tasks

1. **Classify** the request:
   - **Language/syntax** -- Load `references/language.md`
   - **Modules/cmdlets** -- Load `references/modules.md`
   - **Script patterns** -- Load `references/patterns.md`
   - **Version-specific** -- Check the Version-specific guidance table below

2. **Identify version** -- Determine if the user targets 7.4, 7.6, or needs 5.1 compatibility. If unclear, target 7.4+ (widest LTS coverage).

3. **Apply PowerShell idioms** -- Use pipeline-native approaches, not procedural loops. Prefer `Where-Object | Select-Object | ForEach-Object` over `foreach` with manual filtering. Use PSCustomObject for structured output.

4. **Recommend** -- Provide complete, runnable code. Always include error handling.

## Core Expertise Overview

### Pipeline Architecture

PowerShell pipelines pass **objects**, not text. Every command emits .NET objects with properties and methods. Key pipeline cmdlets:

```powershell
# Filter → Transform → Sort → Export
Get-ChildItem C:\Logs -Filter '*.log' -Recurse |
    Where-Object { $_.LastWriteTime -gt (Get-Date).AddDays(-7) } |
    Select-Object FullName, Length, LastWriteTime |
    Sort-Object LastWriteTime -Descending |
    Export-Csv recent-logs.csv -NoTypeInformation
```

### Variables and Types

PowerShell infers types but supports explicit type constraints, casting, and .NET type accelerators (`[xml]`, `[regex]`, `[datetime]`, `[ipaddress]`, `[guid]`, `[uri]`).

### Error Handling

Two error categories: **terminating** (throw, -ErrorAction Stop) and **non-terminating** (Write-Error). Use `$ErrorActionPreference = 'Stop'` to make all errors catchable with try/catch.

### Functions

Advanced functions with `[CmdletBinding()]` get `-Verbose`, `-Debug`, `-ErrorAction`, `-WhatIf`, `-Confirm` automatically. Use parameter validation attributes: `[ValidateSet()]`, `[ValidateRange()]`, `[ValidatePattern()]`, `[ValidateScript()]`.

### Parallel Execution

Three tiers of parallelism:
1. `ForEach-Object -Parallel` -- easiest, uses thread pool, `$using:` for outer variables
2. `Start-ThreadJob` -- lightweight thread-based jobs, manual wait/receive
3. Runspaces -- maximum performance, most complex, full control over thread pool

### Data Processing

```powershell
# CSV pipeline
Import-Csv data.csv | Where-Object Status -eq 'Active' | Export-Csv active.csv -NoTypeInformation

# JSON round-trip
$data = Get-Content config.json -Raw | ConvertFrom-Json
$data.version = '2.0'
$data | ConvertTo-Json -Depth 10 | Set-Content config.json -Encoding UTF8

# XML with XPath
[xml]$doc = Get-Content app.config
Select-Xml -Xml $doc -XPath '//add[@key]' | Select-Object -ExpandProperty Node
```

### REST API

```powershell
$headers = @{ Authorization = "Bearer $token"; Accept = 'application/json' }
$response = Invoke-RestMethod -Uri $uri -Headers $headers
# POST with body
$body = @{ name = 'test' } | ConvertTo-Json
Invoke-RestMethod -Uri $uri -Method POST -Body $body -ContentType 'application/json' -Headers $headers
```

## Common Pitfalls

**1. Using `+=` to build large arrays**
`$arr += $item` creates a new array each time (O(n^2)). Use `[System.Collections.Generic.List[object]]::new()` and `.Add()` instead.

**2. Not specifying -Depth with ConvertTo-Json**
Default depth is 2. Deep objects silently truncate. Always use `-Depth 10` or higher.

**3. Ignoring the difference between `$null -eq $x` and `$x -eq $null`**
When `$x` is an array, `$x -eq $null` filters the array for null elements. Always put `$null` on the left: `$null -eq $x`.

**4. Using Write-Host in functions**
Write-Host bypasses the pipeline. Use Write-Output for data, Write-Verbose for informational messages.

**5. Forgetting -NoTypeInformation with Export-Csv**
Without it, the first line is a type header (`#TYPE System.Management.Automation.PSCustomObject`).

**6. Not using Set-StrictMode -Version Latest**
Without strict mode, typos in variable names silently return `$null`.

**7. Mixing ForEach-Object and foreach statement**
`ForEach-Object` (pipeline) uses `$_`/`$PSItem`. The `foreach` statement uses a named variable. They have different performance characteristics.

**8. Not handling $LASTEXITCODE for native commands**
PowerShell cmdlets set `$?` but native executables (git, npm, curl) set `$LASTEXITCODE`. Check both.

## Version-specific guidance

| Version | Reference | What's version-specific |
|---|---|---|
| 7.4 LTS | `references/versions/7.4.md` | Stable null operators, pipeline chains, ForEach-Object -Parallel improvements, web cmdlet timeouts, PSReadLine 2.3.6 |
| 7.6 LTS | `references/versions/7.6.md` | PSFeedbackProvider, PSRedirectToVariable, Join-Path multi-child, ThreadJob rename, .NET 10, tilde expansion, 5.1 vs 7.x comparison |

## Reference Files

Load these for deep knowledge:

- `references/language.md` -- Pipeline, variables, types, operators, control flow, functions, error handling, strings, regex, collections. Read for syntax and language questions.
- `references/modules.md` -- Module lifecycle, PSGallery, common cmdlets by category (filesystem, data conversion, process, networking, registry), remoting (WinRM, SSH). Read for "how do I do X" questions.
- `references/patterns.md` -- Complete script template, file processing (CSV/JSON/XML/logs), API interaction (auth, pagination, retry), parallel execution, output formatting. Read for scripting patterns and best practices.

## Example Scripts

Complete, runnable scripts in the `scripts/` directory:

- `scripts/01-system-report.ps1` -- Cross-platform OS/CPU/memory/disk/network report
- `scripts/02-api-client.ps1` -- REST API client with auth, pagination, retry
- `scripts/03-file-processor.ps1` -- CSV/JSON processing pipeline with filtering
- `scripts/04-log-analyzer.ps1` -- Log parsing with regex, pattern extraction, summaries