PowerShell Reliable Execution

Execute PowerShell commands reliably on Windows. Avoid &&, handle parameter parsing, recover from interruptions, and ensure cross-session continuity.

Security Scan

This is an instruction-only skill that provides PowerShell best-practice patterns and verification checks; it requests no credentials, installs nothing, and its actions are consistent with its stated purpose.

Purpose & Capability

The name and description (reliable PowerShell execution, error handling, checkpointing) match the SKILL.md content. The skill does not request unrelated credentials, binaries, or installs, and all examples focus on local PowerShell patterns that are appropriate for the stated goal.

Instruction Scope

All runtime instructions remain within the domain of authoring/running PowerShell scripts: safe command chaining, parameter handling, path handling, checkpointing, retry logic, and local file scanning for secrets. The guidance instructs scanning scripts and writing checkpoint files in the working directory — which is reasonable for this purpose but means users should review what files will be scanned or written before running on sensitive directories.

Install Mechanism

No install spec or code files that would be downloaded or executed are present; this is instruction-only content, which minimizes supply-chain/infrastructure risk.

Credentials

The skill declares no required environment variables or credentials. It references common environment variables (e.g., $env:USERPROFILE, an example $env:MY_API_KEY) only as examples; this is proportionate to the guidance. Users should note the skill shows patterns for using environment variables and SecureString but does not require any secrets itself.

Persistence & Privilege

The skill does not request persistent installation, elevated privileges, or always-on inclusion. It recommends storing checkpoint files in the working directory only and does not modify other skills or global agent settings.

Assessment

This skill is coherent and appears to do what it says: teach and verify reliable PowerShell execution patterns. Before using: (1) review any scripts you run that were produced or modified based on these patterns, especially checkpoint files — they live in the working directory and could accidentally include sensitive state if misused; (2) never run unreviewed code from unknown sources with elevated privileges; (3) treat the secret-detection heuristics as helpful but imperfect (they can miss secrets or generate false positives) — perform an independent review for hardcoded credentials; (4) test long-running or background-job patterns in a safe environment to ensure they behave as expected.

Execute commands reliably on Windows PowerShell. Avoid common pitfalls like && chaining, parameter swallowing, and session interruptions.

Problem Statement

Windows PowerShell differs from bash in critical ways:

Issue	Bash	PowerShell	Solution
Command chaining	cmd1 && cmd2	cmd1 -ErrorAction Stop; if ($?) { cmd2 }	Use semicolons + error handling
Parameter parsing	-arg value	-Argument value (case-insensitive)	Use full parameter names
Path separators	/	\ (or / in some cmdlets)	Use Join-Path
Output redirection	> >>	> >> (encoding issues)	Use Out-File -Encoding UTF8
Environment vars	$VAR	$env:VAR	Use $env: prefix

Core Patterns

1. Safe Command Chaining

Wrong:

mkdir test && cd test && echo done

Right:

$ErrorActionPreference = 'Stop'
try {
    New-Item -ItemType Directory -Path test -Force
    Set-Location test
    Write-Host 'done'
} catch {
    Write-Error "Failed: $_"
    exit 1
}

2. Parameter Safety

Wrong:

git commit -m "message"

Right:

git commit -Message "message"
# Or use splatting:
$params = @{ Message = "message" }
git commit @params

3. Path Handling

Wrong:

$path = "C:/Users/name/file.txt"

Right:

$path = Join-Path $env:USERPROFILE "file.txt"
# Or use literal paths:
$path = 'C:\Users\name\file.txt'

4. Output Encoding

Wrong:

echo "text" > file.txt

Right:

"text" | Out-File -FilePath file.txt -Encoding UTF8

5. Session Continuity

For long-running commands:

# Start background job
$job = Start-Job -ScriptBlock {
    param($arg)
    # Long operation
} -ArgumentList $arg

# Wait with timeout
Wait-Job $job -Timeout 300

# Get results
if ($job.State -eq 'Completed') {
    Receive-Job $job
} else {
    Stop-Job $job
    Write-Warning "Job timed out"
}

Error Recovery

Retry Pattern

function Invoke-Retry {
    param(
        [scriptblock]$Command,
        [int]$MaxAttempts = 3,
        [int]$DelaySeconds = 2
    )
    
    $attempt = 0
    while ($attempt -lt $MaxAttempts) {
        try {
            $attempt++
            return & $Command
        } catch {
            if ($attempt -eq $MaxAttempts) { throw }
            Start-Sleep -Seconds $DelaySeconds
        }
    }
}

# Usage
Invoke-Retry -Command { Invoke-WebRequest -Uri $url } -MaxAttempts 3

Interruption Recovery

# Checkpoint pattern
$checkpointFile = ".checkpoint.json"

if (Test-Path $checkpointFile) {
    $state = Get-Content $checkpointFile | ConvertFrom-Json
    Write-Host "Resuming from step $($state.step)"
} else {
    $state = @{ step = 0 }
}

switch ($state.step) {
    0 { 
        # Step 1
        $state.step = 1
        $state | ConvertTo-Json | Out-File $checkpointFile
    }
    1 {
        # Step 2
        Remove-Item $checkpointFile
    }
}

Privacy Security

All execution is local:

• NO command logging to external services
• NO credential capture in scripts
• NO automatic upload of execution results
• Sensitive data handled via [SecureString]
• Checkpoint files stored in working directory only

Sensitive Data Filter: Before writing any checkpoint or log:

• Exclude Password, Token, Secret, ApiKey
• Use [SecureString] for credentials
• Never echo sensitive variables

Executable Completion Criteria

A PowerShell command execution is reliable if and only if:

Criteria	Verification
No && chaining	Select-String '&&' script.ps1 returns nothing
Error handling present	`Select-String 'try
Paths use Join-Path	`Select-String 'Join-Path
Output encoding specified	Select-String 'Out-File.*Encoding' script.ps1 matches
Checkpoint for long ops	Checkpoint file pattern present for ops > 60s
No hardcoded secrets	`Select-String 'password

Quick Reference

Common Cmdlet Mappings

Task	Bash	PowerShell
List files	ls -la	Get-ChildItem -Force
Change dir	cd /path	Set-Location C:\path
Create dir	mkdir x	New-Item -ItemType Directory x
Copy file	cp a b	Copy-Item a b
Move file	mv a b	Move-Item a b
Delete	rm x	Remove-Item x
View file	cat x	Get-Content x
Edit file	vim x	notepad x
Find text	grep x	Select-String x
Pipe	|	| (same)
Redirect	>	> (use Out-File)

Splatting Template

$params = @{
    Path = $filePath
    Encoding = 'UTF8'
    Force = $true
}
Set-Content @params

References

• references/privacy-checklist.md - Privacy security checklist
• Microsoft Docs: PowerShell Best Practices

---

Execute reliably. Recover gracefully.