powershell-engineering-skill

PowerShell Engineering Skill

An Agent Skill for PowerShell development, with task-specific guidance and two executable helpers: an environment reporter and a project validator. It covers writing, reviewing, debugging, testing, and securing PowerShell code.

The skill is designed for Codex and uses the portable SKILL.md Agent Skills format. It recommends PowerShell 7 for new work and treats Windows PowerShell 5.1 as a separate compatibility target when required. References are split by topic so an agent can load only what a task needs.

The guidance is not a PowerShell runtime, module, or autonomous coding system. Generated code still needs review and validation in its target environment.

Coverage

• Commands, scripts, advanced functions, modules, manifests, and classes
• PowerShell 7, Windows PowerShell 5.1, and cross-platform compatibility
• Native executable argument passing, quoting, paths, encoding, JSON, REST, CSV, XML, and environment variables
• Error semantics, output streams, structured logging, and exit codes
• Pester, PSScriptAnalyzer, AST parsing, CI matrices, and release gates
• PSResourceGet, PowerShellGet compatibility, module packaging, and Gallery publishing
• Secrets, least privilege, execution policy, code signing, remoting, JEA, and destructive-operation safeguards
• Performance, jobs, thread jobs, parallel pipelines, runspaces, and remoting
• Windows services, registry, scheduled tasks, CIM, event logs, COM, WPF, and Windows Forms

Install

Use the Codex skill installer:

python "$HOME\.codex\skills\.system\skill-installer\scripts\install-skill-from-github.py" `
  --repo yechya/powershell-engineering-skill `
  --path skills/powershell-engineering

Or use the cross-agent skills CLI:

npx skills add yechya/powershell-engineering-skill --skill powershell-engineering

The skill becomes available to a new Codex task after installation.

Example Prompts

Use $powershell-engineering to review this module for PowerShell 7 and 5.1 compatibility.
Use $powershell-engineering to turn this Bash deployment script into safe PowerShell 7.
Use $powershell-engineering to add Pester tests and PSScriptAnalyzer CI to this project.
Use $powershell-engineering to debug native executable quoting on Windows.
Use $powershell-engineering to design a publishable PowerShell Gallery module.

Included Tools

From the repository root:

# Inspect the current environment as JSON
./skills/powershell-engineering/scripts/Get-PowerShellEnvironment.ps1 -OutputFormat Json

# Parse a target project without requiring an analyzer installation
$result = ./skills/powershell-engineering/scripts/Test-PowerShellProject.ps1 `
  -Path /path/to/project -SkipPSScriptAnalyzer
if (-not $result.Succeeded) { throw 'PowerShell syntax validation failed.' }

Replace /path/to/project with the actual project path. For analyzer and test integration, install PSScriptAnalyzer and Pester separately, omit -SkipPSScriptAnalyzer, and add -RunPester when tests are present.

Validation and Limits

Run the repository check from a clean checkout:

pwsh -NoLogo -NoProfile -File ./tests/Test-Skill.ps1

tests/Test-Skill.ps1 checks skill structure, relative Markdown links, PowerShell syntax, environment output, and valid/invalid parser fixtures. It exercises Pester integration when Pester is installed. The CI workflow runs that check and analyzes the bundled scripts under PowerShell 7 on Windows, Linux, and macOS.

• The bundled scripts declare #Requires -Version 5.1, but CI does not include a Windows PowerShell 5.1 job. The CI badge is not evidence of full 5.1 coverage.
• Parsing does not prove runtime behavior, permissions, or third-party API compatibility. Run generated code in the environment it will actually use.
• Inspect the validator's PSScriptAnalyzer.Status and Pester.Status fields. Succeeded alone does not mean every optional check ran: an absent analyzer is reported as Unavailable, and a requested test run can report NoTests.
• Environment reports include local paths; review them before sharing publicly.

Sources and Design

This repository was informed by a survey of existing community skills, including:

• powershell-7-modern
• powershell-expert
• powershell-master
• powershell-windows
• idiomatic-powershell
• powershell-core
• shell-use
• psake LLM tools
• PowerShell AI Skills and MCP

Primary documentation sources are listed in source-map.md, and the runnable checks above show the validation scope. The guidance avoids recurring bad rules in community material: PowerShell is not ASCII-only, production errors should not be ignored by default, and pipelines are not always faster than language loops. Host-specific tool instructions are kept out of the portable skill.

License

MIT