PowerShell Master
CRITICAL GUIDELINES
Windows File Path Requirements
MANDATORY: Always Use Backslashes on Windows for File Paths
When using Edit or Write tools on Windows, you MUST use backslashes (\) in file paths, NOT forward slashes (/).
Examples:
- WRONG:
D:/repos/project/file.tsx
- CORRECT:
D:\repos\project\file.tsx
This applies to:
- Edit tool file_path parameter
- Write tool file_path parameter
- All file operations on Windows systems
Documentation Guidelines
NEVER create new documentation files unless explicitly requested by the user.
- Priority: Update existing README.md files rather than creating new documentation
- Repository cleanliness: Keep repository root clean - only README.md unless user requests otherwise
- Style: Documentation should be concise, direct, and professional - avoid AI-generated tone
- User preference: Only create additional .md files when user specifically asks for documentation
Complete PowerShell expertise across all platforms for scripting, automation, CI/CD, and cloud management.
When to Activate
PROACTIVELY activate for ANY PowerShell-related task:
- PowerShell Scripts - Creating, reviewing, optimizing any .ps1 file
- Cmdlets & Modules - Finding, installing, using any PowerShell modules
- Cross-Platform - Windows, Linux, macOS PowerShell tasks
- CI/CD Integration - GitHub Actions, Azure DevOps, Bitbucket Pipelines
- Cloud Automation - Azure (Az), AWS, Microsoft 365 (Microsoft.Graph)
- Module Management - PSGallery search, installation, updates
- Script Debugging - Troubleshooting, performance, security
- Best Practices - Code quality, standards, production-ready scripts
Reference Map
Detailed material lives in references/. Load only what the current task needs.
| Topic |
File |
When to load |
| Cross-platform patterns (paths, platform detection, encoding, shell detection) |
references/cross-platform-patterns.md |
Writing scripts that run on Windows + Linux/macOS, or distinguishing PowerShell vs Git Bash |
| Module management (PSResourceGet, PSGallery, popular modules) |
references/modules-and-gallery.md |
Installing/finding modules, Az 14.5.0, Microsoft.Graph 2.32.0, PnP, AWS Tools, offline installs |
| CI/CD pipelines (GitHub Actions, Azure DevOps, Bitbucket) |
references/cicd-integration.md |
Setting up automated PowerShell builds/tests with multi-platform matrices |
| Syntax & cmdlet reference (variables, operators, flow, functions, pipeline, error handling, Pester, performance, REST) |
references/syntax-reference.md |
Authoring scripts, looking up cmdlets, writing Pester tests, performance tuning |
| Security (JEA, WDAC, Constrained Language Mode, Script Block Logging, credentials, code signing) |
references/security-2025.md |
Production security hardening, credential management, audit logging |
PowerShell Overview
PowerShell Versions & Platforms
PowerShell 7+ (Recommended)
- Cross-platform: Windows, Linux, macOS
- Open source, actively developed
- Better performance than PowerShell 5.1
- UTF-8 by default
- Parallel execution support
- Ternary operators, null-coalescing
Windows PowerShell 5.1 (Legacy)
- Windows-only
- Ships with Windows
- UTF-16LE default encoding
- Required for some Windows-specific modules
Installation Locations:
- Windows:
C:\Program Files\PowerShell\7\ (PS7) or C:\Windows\System32\WindowsPowerShell\v1.0\ (5.1)
- Linux:
/opt/microsoft/powershell/7/ or /usr/bin/pwsh
- macOS:
/usr/local/microsoft/powershell/7/ or /usr/local/bin/pwsh
Core Workflow
- Identify scope — Is this a script, module, automation pipeline, or one-off command? Note target platform(s).
- Check version & modules —
$PSVersionTable.PSVersion, Get-Module -ListAvailable. Confirm PowerShell 7+ unless legacy required.
- Load the relevant reference(s) from the Reference Map above. Avoid loading material you do not need.
- Apply the pre-flight checklist (below) before authoring or running production scripts.
- Validate —
Invoke-ScriptAnalyzer for linting, Invoke-Pester for tests, -WhatIf for destructive cmdlets.
Pre-Flight Checklist for Scripts
Before running any PowerShell script, ensure:
- Platform Detection - Use
$IsWindows, $IsLinux, $IsMacOS (see references/cross-platform-patterns.md)
- Version Check -
#Requires -Version 7.0 if needed
- Module Requirements -
#Requires -Modules specified
- Error Handling -
try/catch blocks in place
- Input Validation - Parameter validation attributes used (see
references/syntax-reference.md)
- No Aliases - Full cmdlet names in scripts
- Path Handling - Use
Join-Path or [IO.Path]::Combine()
- Encoding Specified - UTF-8 for cross-platform
- Credentials Secure - Never hardcoded (see
references/security-2025.md)
- Verbose Logging -
Write-Verbose for debugging
Quick Decision Guide
Use PowerShell 7+ when:
- Cross-platform compatibility needed
- New projects or scripts
- Performance is important
- Modern language features desired
Use Windows PowerShell 5.1 when:
- Windows-specific modules required (WSUS, GroupPolicy legacy)
- Corporate environments with strict version requirements
- Legacy script compatibility needed
Choose Azure CLI when:
- Simple one-liners needed
- JSON output preferred
- Bash scripting integration
Choose PowerShell Az module when:
- Complex automation required
- Object manipulation needed
- PowerShell scripting expertise available
- Reusable scripts and modules needed
Minimal Script Skeleton
#Requires -Version 7.0
<#
.SYNOPSIS
Brief description
.DESCRIPTION
Detailed description
.PARAMETER Name
Parameter description
.EXAMPLE
PS> .\script.ps1 -Name "John"
#>
[CmdletBinding()]
param(
[Parameter(Mandatory=$true)]
[ValidateNotNullOrEmpty()]
[string]$Name
)
$ErrorActionPreference = "Stop"
Set-StrictMode -Version Latest
try {
Write-Verbose "Starting script"
# ... main logic ...
Write-Verbose "Script completed successfully"
}
catch {
Write-Error "Script failed: $_"
exit 1
}
finally {
# Cleanup
}
Expand this skeleton using patterns from references/syntax-reference.md (advanced functions, pipeline, error handling) and references/security-2025.md (input validation, credential handling).
Additional Resources
For shell detection on Windows (PowerShell vs Git Bash), see the powershell-shell-detection skill.
Remember: ALWAYS research latest PowerShell documentation and module versions before implementing solutions. The PowerShell ecosystem evolves rapidly, and best practices are updated frequently.
1---
2name: powershell-master
3description: |
4 Complete PowerShell expertise system across ALL platforms (Windows/Linux/macOS).
5 PROACTIVELY activate for: (1) ANY PowerShell task (scripts/modules/cmdlets), (2) CI/CD automation (GitHub Actions/Azure DevOps/Bitbucket), (3) Cross-platform scripting, (4) Module discovery and management (PSGallery), (5) Azure/AWS/Microsoft 365 automation, (6) Script debugging and optimization, (7) Best practices and security.
6 Provides: PowerShell 7+ features, popular module expertise (Az, Microsoft.Graph, PnP, AWS Tools), PSGallery integration, platform-specific guidance, CI/CD pipeline patterns, cmdlet syntax mastery, and production-ready scripting patterns.
7 Ensures professional-grade, cross-platform PowerShell automation following industry standards.
8metadata:
9 source: https://skillmd.com/skills/josiahsiegel/powershell-master
10---
11
12# PowerShell Master
13
14## CRITICAL GUIDELINES
15
16### Windows File Path Requirements
17
18**MANDATORY: Always Use Backslashes on Windows for File Paths**
19
20When using Edit or Write tools on Windows, you MUST use backslashes (`\`) in file paths, NOT forward slashes (`/`).
21
22Examples:
23- WRONG: `D:/repos/project/file.tsx`
24- CORRECT: `D:\repos\project\file.tsx`
25
26This applies to:
27- Edit tool file_path parameter
28- Write tool file_path parameter
29- All file operations on Windows systems
30
31### Documentation Guidelines
32
33NEVER create new documentation files unless explicitly requested by the user.
34
35- **Priority**: Update existing README.md files rather than creating new documentation
36- **Repository cleanliness**: Keep repository root clean - only README.md unless user requests otherwise
37- **Style**: Documentation should be concise, direct, and professional - avoid AI-generated tone
38- **User preference**: Only create additional .md files when user specifically asks for documentation
39
40---
41
42Complete PowerShell expertise across all platforms for scripting, automation, CI/CD, and cloud management.
43
44---
45
46## When to Activate
47
48PROACTIVELY activate for ANY PowerShell-related task:
49
50- **PowerShell Scripts** - Creating, reviewing, optimizing any .ps1 file
51- **Cmdlets & Modules** - Finding, installing, using any PowerShell modules
52- **Cross-Platform** - Windows, Linux, macOS PowerShell tasks
53- **CI/CD Integration** - GitHub Actions, Azure DevOps, Bitbucket Pipelines
54- **Cloud Automation** - Azure (Az), AWS, Microsoft 365 (Microsoft.Graph)
55- **Module Management** - PSGallery search, installation, updates
56- **Script Debugging** - Troubleshooting, performance, security
57- **Best Practices** - Code quality, standards, production-ready scripts
58
59---
60
61## Reference Map
62
63Detailed material lives in `references/`. Load only what the current task needs.
64
65| Topic | File | When to load |
66|-------|------|--------------|
67| Cross-platform patterns (paths, platform detection, encoding, shell detection) | `references/cross-platform-patterns.md` | Writing scripts that run on Windows + Linux/macOS, or distinguishing PowerShell vs Git Bash |
68| Module management (PSResourceGet, PSGallery, popular modules) | `references/modules-and-gallery.md` | Installing/finding modules, Az 14.5.0, Microsoft.Graph 2.32.0, PnP, AWS Tools, offline installs |
69| CI/CD pipelines (GitHub Actions, Azure DevOps, Bitbucket) | `references/cicd-integration.md` | Setting up automated PowerShell builds/tests with multi-platform matrices |
70| Syntax & cmdlet reference (variables, operators, flow, functions, pipeline, error handling, Pester, performance, REST) | `references/syntax-reference.md` | Authoring scripts, looking up cmdlets, writing Pester tests, performance tuning |
71| Security (JEA, WDAC, Constrained Language Mode, Script Block Logging, credentials, code signing) | `references/security-2025.md` | Production security hardening, credential management, audit logging |
72
73---
74
75## PowerShell Overview
76
77### PowerShell Versions & Platforms
78
79**PowerShell 7+ (Recommended)**
80- Cross-platform: Windows, Linux, macOS
81- Open source, actively developed
82- Better performance than PowerShell 5.1
83- UTF-8 by default
84- Parallel execution support
85- Ternary operators, null-coalescing
86
87**Windows PowerShell 5.1 (Legacy)**
88- Windows-only
89- Ships with Windows
90- UTF-16LE default encoding
91- Required for some Windows-specific modules
92
93**Installation Locations:**
94- **Windows:** `C:\Program Files\PowerShell\7\` (PS7) or `C:\Windows\System32\WindowsPowerShell\v1.0\` (5.1)
95- **Linux:** `/opt/microsoft/powershell/7/` or `/usr/bin/pwsh`
96- **macOS:** `/usr/local/microsoft/powershell/7/` or `/usr/local/bin/pwsh`
97
98---
99
100## Core Workflow
101
1021. **Identify scope** — Is this a script, module, automation pipeline, or one-off command? Note target platform(s).
1032. **Check version & modules** — `$PSVersionTable.PSVersion`, `Get-Module -ListAvailable`. Confirm PowerShell 7+ unless legacy required.
1043. **Load the relevant reference(s)** from the Reference Map above. Avoid loading material you do not need.
1054. **Apply the pre-flight checklist** (below) before authoring or running production scripts.
1065. **Validate** — `Invoke-ScriptAnalyzer` for linting, `Invoke-Pester` for tests, `-WhatIf` for destructive cmdlets.
107
108---
109
110## Pre-Flight Checklist for Scripts
111
112Before running any PowerShell script, ensure:
113
1141. **Platform Detection** - Use `$IsWindows`, `$IsLinux`, `$IsMacOS` (see `references/cross-platform-patterns.md`)
1152. **Version Check** - `#Requires -Version 7.0` if needed
1163. **Module Requirements** - `#Requires -Modules` specified
1174. **Error Handling** - `try/catch` blocks in place
1185. **Input Validation** - Parameter validation attributes used (see `references/syntax-reference.md`)
1196. **No Aliases** - Full cmdlet names in scripts
1207. **Path Handling** - Use `Join-Path` or `[IO.Path]::Combine()`
1218. **Encoding Specified** - UTF-8 for cross-platform
1229. **Credentials Secure** - Never hardcoded (see `references/security-2025.md`)
12310. **Verbose Logging** - `Write-Verbose` for debugging
124
125---
126
127## Quick Decision Guide
128
129**Use PowerShell 7+ when:**
130- Cross-platform compatibility needed
131- New projects or scripts
132- Performance is important
133- Modern language features desired
134
135**Use Windows PowerShell 5.1 when:**
136- Windows-specific modules required (WSUS, GroupPolicy legacy)
137- Corporate environments with strict version requirements
138- Legacy script compatibility needed
139
140**Choose Azure CLI when:**
141- Simple one-liners needed
142- JSON output preferred
143- Bash scripting integration
144
145**Choose PowerShell Az module when:**
146- Complex automation required
147- Object manipulation needed
148- PowerShell scripting expertise available
149- Reusable scripts and modules needed
150
151---
152
153## Minimal Script Skeleton
154
155```powershell
156#Requires -Version 7.0
157
158<#
159.SYNOPSIS
160 Brief description
161.DESCRIPTION
162 Detailed description
163.PARAMETER Name
164 Parameter description
165.EXAMPLE
166 PS> .\script.ps1 -Name "John"
167#>
168
169[CmdletBinding()]
170param(
171 [Parameter(Mandatory=$true)]
172 [ValidateNotNullOrEmpty()]
173 [string]$Name
174)
175
176$ErrorActionPreference = "Stop"
177Set-StrictMode -Version Latest
178
179try {
180 Write-Verbose "Starting script"
181 # ... main logic ...
182 Write-Verbose "Script completed successfully"
183}
184catch {
185 Write-Error "Script failed: $_"
186 exit 1
187}
188finally {
189 # Cleanup
190}
191```
192
193Expand this skeleton using patterns from `references/syntax-reference.md` (advanced functions, pipeline, error handling) and `references/security-2025.md` (input validation, credential handling).
194
195---
196
197## Additional Resources
198
199- PowerShell Docs: https://learn.microsoft.com/powershell
200- PowerShell Gallery: https://www.powershellgallery.com
201- Az Module Docs: https://learn.microsoft.com/powershell/azure
202- Microsoft Graph Docs: https://learn.microsoft.com/graph/powershell
203
204For shell detection on Windows (PowerShell vs Git Bash), see the `powershell-shell-detection` skill.
205
206---
207
208Remember: ALWAYS research latest PowerShell documentation and module versions before implementing solutions. The PowerShell ecosystem evolves rapidly, and best practices are updated frequently.