powershell-expert

PowerShell Expert

Develop production-quality PowerShell scripts, tools, and GUIs using Microsoft best practices and the PowerShell ecosystem.

Quick Reference

Script Structure

#Requires -Version 5.1

<#
.SYNOPSIS
    Brief description.
.DESCRIPTION
    Detailed description.
.PARAMETER Name
    Parameter description.
.EXAMPLE
    Example-Usage -Name 'Value'
#>

[CmdletBinding()]
param(
    [Parameter(Mandatory, ValueFromPipeline)]
    [ValidateNotNullOrEmpty()]
    [string[]]$Name,

    [switch]$Force
)

begin {
    # One-time setup
}

process {
    foreach ($item in $Name) {
        # Per-item processing
    }
}

end {
    # Cleanup
}

Function Template

function Verb-Noun {
    [CmdletBinding(SupportsShouldProcess)]
    param(
        [Parameter(Mandatory, Position = 0)]
        [string]$Name,

        [Parameter(ValueFromPipelineByPropertyName)]
        [Alias('CN')]
        [string]$ComputerName = $env:COMPUTERNAME,

        [switch]$PassThru
    )

    process {
        if ($PSCmdlet.ShouldProcess($Name, 'Action')) {
            # Implementation
            if ($PassThru) { Write-Output $result }
        }
    }
}

Workflow

1. Script Development

Follow naming and parameter conventions:

• Verb-Noun format with approved verbs (Get-Verb)
• Strong typing with validation attributes
• Pipeline support via ValueFromPipeline
• -WhatIf/-Confirm for destructive operations

See best-practices.md for complete guidelines.

2. GUI Development

Windows Forms for simple dialogs, WPF/XAML for complex interfaces:

Add-Type -AssemblyName System.Windows.Forms
Add-Type -AssemblyName System.Drawing

$form = New-Object System.Windows.Forms.Form -Property @{
    Text          = 'Title'
    Size          = New-Object System.Drawing.Size(400, 300)
    StartPosition = 'CenterScreen'
}

See gui-development.md for controls, events, and templates.

3. PowerShell Gallery Integration

Search and install modules using PSResourceGet:

# Search gallery
Find-PSResource -Name 'ModuleName' -Repository PSGallery

# Install module
Install-PSResource -Name 'ModuleName' -Scope CurrentUser -TrustRepository

Use scripts/Search-Gallery.ps1 for enhanced search.

See powershellget.md for full cmdlet reference.

Key Patterns

Error Handling

try {
    $result = Get-Content -Path $Path -ErrorAction Stop
}
catch [System.IO.FileNotFoundException] {
    Write-Error "File not found: $Path"
    return
}
catch {
    throw
}

Splatting for Readability

$params = @{
    Path        = $sourcePath
    Destination = $destPath
    Recurse     = $true
    Force       = $true
}
Copy-Item @params

Pipeline Best Practices

# Stream output immediately
foreach ($item in $collection) {
    Process-Item $item | Write-Output
}

# Accept pipeline input
param(
    [Parameter(ValueFromPipeline)]
    [string[]]$InputObject
)
process {
    foreach ($obj in $InputObject) {
        # Process each
    }
}

Module Recommendations

When recommending modules, search the PowerShell Gallery:

Live Verification

You MUST verify information against live sources when accuracy is critical. Do not rely solely on training data for module availability or cmdlet syntax.

Tools to use:

• WebFetch: Retrieve and parse specific documentation URLs (PowerShell Gallery pages, Microsoft Docs)
• WebSearch: Find correct URLs when the exact path is unknown or to verify module existence

When Verification is Required

Step 1: Verify Module on PowerShell Gallery

When recommending or checking a module, use the WebFetch tool to verify it exists:

WebFetch call:

• URL: https://www.powershellgallery.com/packages/{ModuleName}
• Prompt: Extract: module name, latest version, last updated date, total downloads, and whether it shows any deprecation warning or 'unlisted' status

If WebFetch returns 404 or error: The module likely doesn't exist. Use the WebSearch tool to confirm:

• Query: {ModuleName} PowerShell module site:powershellgallery.com

Step 2: Verify Cmdlet Syntax (When Needed)

Microsoft Docs URLs vary by module. Use the WebSearch tool to find the correct documentation page:

WebSearch call:

• Query: {Cmdlet-Name} cmdlet site:learn.microsoft.com/en-us/powershell

Then use WebFetch on the returned URL with prompt:

• Prompt: Extract the complete cmdlet syntax, required vs optional parameters, and PowerShell version requirements

Step 3: Fallback Strategies

If the WebFetch or WebSearch tools are unavailable or return errors:

1. For module verification: Execute Search-Gallery.ps1 from this skill:

   ~/.claude/skills/powershell-expert/scripts/Search-Gallery.ps1 -Name 'ModuleName'
   

2. For cmdlet syntax: Suggest the user run locally:

   Get-Help Cmdlet-Name -Full
   Get-Command Cmdlet-Name -Syntax
   

3. Clearly state uncertainty: If verification fails, tell the user:

   "I wasn't able to verify this against live documentation. Please confirm the module exists by running: Find-PSResource -Name 'ModuleName'"

Verification Examples

Good (verified with live data):

"The ImportExcel module (v7.8.10, updated Oct 2024, 17M+ downloads) provides Export-Excel for creating spreadsheets without Excel installed."

Bad (unverified claim):

"Use the Excel-Tools module to export data." ← May not exist!

Documentation Resources

• PowerShell Docs: https://learn.microsoft.com/en-us/powershell/
• Module Browser: https://learn.microsoft.com/en-us/powershell/module/
• PowerShell Gallery: https://www.powershellgallery.com
• GitHub Docs: https://github.com/MicrosoftDocs/PowerShell-Docs

References

• best-practices.md - Naming, parameters, pipeline, error handling, code style
• gui-development.md - Windows Forms, WPF, controls, events, templates
• powershellget.md - Find, install, update, publish modules