Powershell Knowledge

---
name: powershell-knowledge
description: >
  Comprehensive PowerShell development knowledge for scripts, modules, GUIs, and Windows automation.
  Use when working with: (1) PowerShell script development and best practices, (2) Function and parameter design,
  (3) Pipeline handling and error management, (4) Windows Forms and WPF GUI creation,
  (5) PowerShell Gallery module management, (6) PSScriptAnalyzer and code quality.
---

# PowerShell Expert

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

## Quick Reference

### Script Structure
```powershell
#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
```powershell
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](references/best-practices.md) for complete guidelines.

### 2. GUI Development
Windows Forms for simple dialogs, WPF/XAML for complex interfaces:

```powershell
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](references/gui-development.md) for controls, events, and templates.

### 3. PowerShell Gallery Integration
Search and install modules using PSResourceGet:

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

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

Use [scripts/Search-Gallery.ps1](scripts/Search-Gallery.ps1) for enhanced search.

See [powershellget.md](references/powershellget.md) for full cmdlet reference.

## Key Patterns

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

### Splatting for Readability
```powershell
$params = @{
    Path        = $sourcePath
    Destination = $destPath
    Recurse     = $true
    Force       = $true
}
Copy-Item @params
```

### Pipeline Best Practices
```powershell
# 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. These are common starting points — **always verify via [Module Verification](#module-verification) before recommending**:

| Category | Popular Modules |
|----------|----------------|
| **Azure** | `Az`, `Az.Compute`, `Az.Storage` |
| **Testing** | `Pester`, `PSScriptAnalyzer` |
| **Console** | `PSReadLine`, `Terminal-Icons` |
| **Secrets** | `Microsoft.PowerShell.SecretManagement` |
| **Web** | `Pode` (web server), `PoshRSJob` (async) |
| **GUI** | `WPFBot3000`, `PSGUI` |

## Documentation Lookup

Verify cmdlet syntax and module availability against live sources rather than recalled
detail. Every `learn.microsoft.com` PowerShell page is generated from markdown in a
public MicrosoftDocs repository — **fetch the markdown, not the rendered page**. The
source is far smaller, carries no navigation chrome or JavaScript, and preserves syntax
blocks and parameter tables verbatim.

### Raw Markdown Sources (WebFetch)

Use the **WebFetch** tool against `raw.githubusercontent.com`. Construct the URL
directly from the templates below — do not search for it first.

| Command kind | URL template |
|--------------|--------------|
| **Core PowerShell**<br>`Get-ChildItem`, `Write-Output`, `Invoke-Command` | `https://raw.githubusercontent.com/MicrosoftDocs/PowerShell-Docs/main/reference/{version}/{Module}/{Cmdlet}.md` |
| **Conceptual**<br>`about_Splatting`, `about_CommonParameters` | `https://raw.githubusercontent.com/MicrosoftDocs/PowerShell-Docs/main/reference/{version}/Microsoft.PowerShell.Core/About/{about_Topic}.md` |
| **Windows-only**<br>`Get-ADUser`, `Get-DnsServerZone`, `Get-MpComputerStatus` | `https://raw.githubusercontent.com/MicrosoftDocs/windows-powershell-docs/main/docset/winserver2025-ps/{Module}/{Cmdlet}.md` |
| **Gallery / packaging**<br>`Install-PSResource`, `Find-PSResource` | `https://raw.githubusercontent.com/MicrosoftDocs/powershell-docs-psget/main/powershell-gallery/powershellget-3.x/Microsoft.PowerShell.PSResourceGet/{Cmdlet}.md` |
| **Satellite modules**<br>`Invoke-ScriptAnalyzer`, `Get-Secret` | `https://raw.githubusercontent.com/MicrosoftDocs/PowerShell-Docs-Modules/main/reference/ps-modules/{Module}/{Cmdlet}.md` |

`{version}` is one of `5.1`, `7.4`, `7.5`, `7.6`, `7.7`. Pin it from context —
`#Requires`, `pwsh`, ISE, or a stated platform. **With no signal, fetch both `7.5` and
`5.1` and state any parameter difference**, since the wrong edition yields syntax that
looks authentic but fails on the user's shell.

**WebFetch prompt**: `Extract the complete syntax blocks, the full parameter table with
types and defaults, and the examples.`

Three rules govern URL construction:

1. **Case matters.** Raw paths are case-sensitive where `learn.microsoft.com` is not.
   `.../activedirectory/Get-ADUser.md` returns 404; `.../ActiveDirectory/Get-ADUser.md`
   returns 200. Preserve the module's own casing.
2. **Never point at a folder.** Raw serves blobs only — any URL ending in `/` returns
   404. There is no directory-listing endpoint.
3. **Convert page URLs.** Rewrite `github.com/{owner}/{repo}/blob/{branch}/{path}` to
   `raw.githubusercontent.com/{owner}/{repo}/{branch}/{path}`.

Routing a cmdlet to the right repository, module, and version folder is covered in
**[doc-sources.md](references/doc-sources.md)**, along with complete module inventories
and a 404 troubleshooting table. Consult it whenever the correct path is not obvious.

### Fallback Chain

Escalate only on failure, one step at a time:

| Step | Tool | Use when |
|------|------|----------|
| 1 | **WebFetch** raw markdown | Default — always attempt first |
| 2 | **WebFetch** contents API<br>`https://api.github.com/repos/{owner}/{repo}/contents/{path}` | A folder name is unknown. Returns plain JSON that parses cleanly; 60 requests/hour unauthenticated |
| 3 | **WebFetch** `learn.microsoft.com` | No raw source exists (third-party modules, Learn-only articles) |
| 4 | **WebSearch** | Path cannot be derived. Query: `{Cmdlet-Name} site:learn.microsoft.com/en-us/powershell` — then convert the result back to a raw URL and return to step 1 |
| 5 | Local execution | Tools unavailable. Ask the user to run `Get-Help {Cmdlet} -Full` or `Get-Command {Cmdlet} -Syntax` |

If every step fails, state the uncertainty explicitly rather than guessing:

> "I wasn't able to verify this against live documentation. Please confirm by running:
> `Get-Command Cmdlet-Name -Syntax`"

### Module Verification

Gallery packages have no markdown source. **WebFetch** the listing page directly:

- **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`

A 404 means the module likely does not exist — confirm with **WebSearch** for
`{ModuleName} PowerShell module site:powershellgallery.com`. If both tools are
unavailable, execute
`${CLAUDE_PLUGIN_ROOT}/skills/powershell-knowledge/scripts/Search-Gallery.ps1 -Name 'ModuleName'`.

| Scenario | Requirement |
|----------|-------------|
| User asks whether module X exists | **MUST** verify on the Gallery |
| Recommending a specific module | **MUST** verify it exists and is not deprecated |
| Stating a module version requirement | **MUST** check the Gallery for the current version |
| Providing exact cmdlet syntax | **SHOULD** verify against raw markdown |
| General best practices | Static references suffice |

**Good** (verified against live data):
> "ImportExcel (v7.8.10, updated Oct 2024, 17M+ downloads) provides `Export-Excel` for
> creating spreadsheets without Excel installed."

**Bad** (unverified):
> "Use the Excel-Tools module to export data." ← may not exist

### Rendered Documentation

Browse these manually; prefer the raw sources above when fetching.

| Resource | URL |
|----------|-----|
| PowerShell documentation | https://learn.microsoft.com/en-us/powershell/ |
| Module browser | https://learn.microsoft.com/en-us/powershell/module/ |
| PowerShell Gallery | https://www.powershellgallery.com |

## Reference Files

| Topic | File |
|-------|------|
| Documentation routing, raw URL maps, 404 troubleshooting | [references/doc-sources.md](references/doc-sources.md) |
| Naming, parameters, pipeline, error handling, code style | [references/best-practices.md](references/best-practices.md) |
| Windows Forms, WPF, controls, events, templates | [references/gui-development.md](references/gui-development.md) |
| Find, install, update, publish modules | [references/powershellget.md](references/powershellget.md) |

## Included Scripts

| Script | Purpose |
|--------|---------|
| [scripts/Search-Gallery.ps1](scripts/Search-Gallery.ps1) | Formatted PowerShell Gallery search with legacy `Find-Module` fallback |