SuperAPI AI Directory
Partner中文AI newsFavorites
Skillspowershell-knowledge

powershell-knowledge

Deployment & operations

View repository

Updated 10-28 07:37

About this skill

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
```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 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. These are common starting points — always verify via 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 PowerShellGet-ChildItem, Write-Output, Invoke-Command https://raw.githubusercontent.com/MicrosoftDocs/PowerShell-Docs/main/reference/{version}/{Module}/{Cmdlet}.md
Conceptualabout_Splatting, about_CommonParameters https://raw.githubusercontent.com/MicrosoftDocs/PowerShell-Docs/main/reference/{version}/Microsoft.PowerShell.Core/About/{about_Topic}.md
Windows-onlyGet-ADUser, Get-DnsServerZone, Get-MpComputerStatus https://raw.githubusercontent.com/MicrosoftDocs/windows-powershell-docs/main/docset/winserver2025-ps/{Module}/{Cmdlet}.md
Gallery / packagingInstall-PSResource, Find-PSResource https://raw.githubusercontent.com/MicrosoftDocs/powershell-docs-psget/main/powershell-gallery/powershellget-3.x/Microsoft.PowerShell.PSResourceGet/{Cmdlet}.md
Satellite modulesInvoke-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, 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 APIhttps://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
Naming, parameters, pipeline, error handling, code style references/best-practices.md
Windows Forms, WPF, controls, events, templates references/gui-development.md
Find, install, update, publish modules references/powershellget.md

Included Scripts

Script Purpose
scripts/Search-Gallery.ps1 Formatted PowerShell Gallery search with legacy Find-Module fallback