Agent Skills: PowerShell Expert Skill

PowerShell Expert Skill

Overview

This skill covers PowerShell 7+ (Core) for cross-platform automation, system administration, and DevOps scripting. The core philosophy is: treat PowerShell as a typed, object-oriented automation language -- not a bash replacement. Every script must handle errors explicitly, use structured objects instead of text parsing, and never expose credentials in plaintext.

When to Use

• When writing PowerShell automation scripts for Windows or cross-platform
• When auditing existing PowerShell scripts for security and reliability
• When setting up CI/CD pipelines with PowerShell-based tooling
• When managing Windows infrastructure with DSC or JEA
• When building PowerShell modules with proper structure and testing
• When migrating from Windows PowerShell 5.1 to PowerShell 7+

Iron Laws

1. ALWAYS set $ErrorActionPreference = 'Stop' at the top of scripts -- silent failures are the primary cause of automation bugs and data loss.
2. NEVER hardcode credentials or secrets in scripts -- use Microsoft.PowerShell.SecretManagement module to pull secrets from vaults.
3. ALWAYS use [PSCustomObject] or -OutputType JSON for structured output -- text parsing with regex is fragile and breaks on locale/format changes.
4. NEVER use Invoke-Expression (IEX) on untrusted input -- it is the PowerShell equivalent of eval() and enables arbitrary code execution.
5. ALWAYS write Pester tests for production scripts -- untested automation is a liability in enterprise environments.

Anti-Patterns

| Anti-Pattern | Why It Fails | Correct Approach | | ------------------------------------------------------------------ | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | | Parsing command output with regex instead of using objects | Breaks on locale changes, format updates, and different OS versions | Use cmdlet object output directly or convert to PSCustomObject | | Using Invoke-Expression to build dynamic commands | Enables code injection; any user input can execute arbitrary PowerShell | Use splatting (@params) for dynamic parameters; use Start-Process for external commands | | Catching all exceptions with empty catch blocks | Silently swallows errors; automation appears to succeed when it failed | Use typed catch blocks; log and re-throw unexpected exceptions | | Using Windows PowerShell 5.1 syntax without checking compatibility | Scripts fail on Linux/macOS where PS 7 is the only option | Use $PSVersionTable.PSVersion checks; prefer PS 7 cross-platform cmdlets | | Storing credentials in script variables or config files | Plaintext secrets in source control; credential theft risk | Use Get-Secret from SecretManagement module; inject via environment variables in CI |

Workflow

Step 1: Script Structure

#Requires -Version 7.0
#Requires -Modules @{ ModuleName='Microsoft.PowerShell.SecretManagement'; ModuleVersion='1.1.0' }

$ErrorActionPreference = 'Stop'
Set-StrictMode -Version Latest

function Invoke-DataBackup {
    [CmdletBinding()]
    param(
        [Parameter(Mandatory)]
        [ValidateNotNullOrEmpty()]
        [string]$TargetPath,

        [Parameter()]
        [switch]$Compress
    )

    begin {
        Write-Verbose "Starting backup to $TargetPath"
    }

    process {
        try {
            # Business logic here
        }
        catch [System.IO.IOException] {
            Write-Error "IO error during backup: $_"
            throw
        }
        catch {
            Write-Error "Unexpected error: $_"
            throw
        }
    }

    end {
        Write-Verbose "Backup complete"
    }
}

Step 2: Secure Secret Retrieval

# Register a vault (one-time setup)
Register-SecretVault -Name 'AzureKeyVault' -ModuleName 'Az.KeyVault'

# Retrieve secret at runtime
$apiKey = Get-Secret -Name 'MyApiKey' -Vault 'AzureKeyVault' -AsPlainText

# Use in automation (never log the value)
$headers = @{ 'Authorization' = "Bearer $apiKey" }
Invoke-RestMethod -Uri $endpoint -Headers $headers

Step 3: Object-Oriented Pipeline

# Process structured data through the pipeline
Get-ChildItem -Path $target -Filter *.json |
    ForEach-Object {
        $data = Get-Content -Path $_.FullName | ConvertFrom-Json
        [PSCustomObject]@{
            FileName  = $_.Name
            ItemCount = $data.items.Count
            LastModified = $_.LastWriteTime
        }
    } |
    Sort-Object -Property ItemCount -Descending |
    Export-Csv -Path 'report.csv' -NoTypeInformation

Step 4: Pester Testing

# Invoke-DataBackup.Tests.ps1
Describe 'Invoke-DataBackup' {
    BeforeAll {
        . $PSScriptRoot/Invoke-DataBackup.ps1
    }

    Context 'When target path exists' {
        It 'Should create backup file' {
            $result = Invoke-DataBackup -TargetPath $TestDrive
            $result | Should -Not -BeNullOrEmpty
            Test-Path "$TestDrive/backup.zip" | Should -BeTrue
        }
    }

    Context 'When target path is invalid' {
        It 'Should throw IO exception' {
            { Invoke-DataBackup -TargetPath '/nonexistent/path' } |
                Should -Throw -ExceptionType ([System.IO.IOException])
        }
    }
}

Step 5: Cross-Platform Compatibility

# Use Join-Path for all path operations
$configPath = Join-Path -Path $HOME -ChildPath '.config' -AdditionalChildPath 'myapp', 'settings.json'

# Check platform before using platform-specific features
if ($IsWindows) {
    # Windows-specific: registry, WMI, COM
    $os = Get-CimInstance -ClassName Win32_OperatingSystem
} elseif ($IsLinux -or $IsMacOS) {
    # Unix-specific: /proc, systemctl
    $os = uname -a
}

Complementary Skills

| Skill | Relationship | | ----------------- | ------------------------------------------------------ | | devops | CI/CD pipeline integration with PowerShell scripts | | docker-compose | Containerized PowerShell automation | | terraform-infra | Infrastructure provisioning alongside PS configuration | | tdd | Test-driven development methodology for Pester tests |

Memory Protocol (MANDATORY)

Before starting:

Read .claude/context/memory/learnings.md for prior PowerShell modules, Pester testing patterns, or OS-specific workarounds.

After completing: Record new PowerShell modules, Pester testing patterns, or OS-specific workarounds to .claude/context/memory/learnings.md.

ASSUME INTERRUPTION: Your context may reset. If it's not in memory, it didn't happen.