version: "1.0.0"

name: powershell description: > Author, validate, and invoke PowerShell safely before execution. Use when AI generates or changes PowerShell scripts or commands. USE FOR: generate powershell, validate powershell syntax, parse ps1, safely pass arguments to powershell script, powershell quoting, special characters in powershell arguments, AST parse, PSScriptAnalyzer.

PowerShell Authoring and Validation

Validate generated PowerShell quietly and keep input separate from code.

Core Workflow

1. Write multi-step logic to a .ps1 file.
2. Resolve installed skill root through skill discovery. Never guess or hardcode it.
3. Run & (Join-Path $skillRoot 'scripts\Test-PowerShellScript.ps1') -Path $scriptPath -PassThru after every .ps1 or .psm1 edit.
4. Fix parser errors and PSScriptAnalyzer Error findings before continuing.
5. Treat analyzer warnings as advisory. Preserve them for final report without interrupting implementation.
6. If user asks to fix analyzer findings, add -Strict and resolve warnings before continuing.
7. Invoke scripts with named parameters, splatting, or argument arrays. Never rebuild invocation as source text.
8. Run smallest read-only, dependency-mocked, or -WhatIf behavior check available.

WSL Detection

When running from a Linux shell, detect WSL before choosing a Windows PowerShell executable:

grep -qi microsoft /proc/sys/kernel/osrelease 2>/dev/null || grep -qi microsoft /proc/version

If detection succeeds, read ./references/wsl-powershell.md before invoking powershell.exe or pwsh.exe.

Keep successful intermediate checks quiet. Report immediately only for unresolved failures or required user decisions. At completion, report parser status, analyzer status, and useful analyzer warnings.

Mandatory Validator

For all parser and PSScriptAnalyzer validation, only run bundled scripts/Test-PowerShellScript.ps1. Do not replace or mock its validation.

$validatorPath = Join-Path $skillRoot 'scripts/Test-PowerShellScript.ps1'
$validation = @(& $validatorPath -Path $scriptPath -PassThru)

Parser errors and analyzer Error findings fail validation. Analyzer warnings do not fail by default. Missing or failed PSScriptAnalyzer is recorded in results and fails only with -RequireScriptAnalyzer. Use -Strict for strict CI or when user requests analyzer findings be fixed. With -PassThru, inspect each result's Passed property; validation failures are returned instead of thrown. Do not read validator source unless documented usage and output cannot explain failure.

Result Contract

With -PassThru, validator returns one result per input path with these fields:

• Path: Resolved file path, or original input when path validation fails.
• Passed: Overall validation result.
• ValidationError: Path resolution or extension error; otherwise $null.
• ParseErrors: Raw PowerShell parser error objects. Count with @($result.ParseErrors).Count; read location from Extent.
• ScriptAnalyzerStatus: Available, Unavailable, Failed, or NotRun.
• AnalyzerFindings: Raw PSScriptAnalyzer diagnostic objects. Count with @($result.AnalyzerFindings).Count.
• AnalyzerError: Analyzer import or invocation error; otherwise $null.

Progressive References

• Read ./references/safe-invocation.md when handling unpredictable input,

transient command text, child PowerShell processes, native executables, or parameter-binding failures.

• Read ./references/wsl-powershell.md when WSL detection succeeds or

Windows-host PowerShell execution is needed.

• Read ./references/authoring-rules.md when creating reusable scripts,

advanced functions, pipeline commands, or mutating operations.

• Read ./references/psscriptanalyzer.md only when installing, configuring, or

troubleshooting PSScriptAnalyzer.

Limits

Parser success proves grammar only. It does not prove command availability, parameter binding, native argument validity, authentication, remote-service behavior, or business logic.