Agent Skills › itsfatduck/optimizerDuck › powershell-windows

powershell-windows

GitHub

提供Windows PowerShell开发的最佳实践与常见陷阱指南，涵盖运算符语法、Unicode限制、空值检查、字符串插值、错误处理及JSON操作等核心模式。

.agents/skills/powershell-windows/SKILL.md itsfatduck/optimizerDuck

Trigger Scenarios

编写或调试PowerShell脚本解决PowerShell语法错误或运行时异常优化Windows环境下的自动化脚本

Install

npx skills add itsfatduck/optimizerDuck --skill powershell-windows -g -y

More Options

Non-standard path

npx skills add https://github.com/itsfatduck/optimizerDuck/tree/master/.agents/skills/powershell-windows -g -y

Use without installing

npx skills use itsfatduck/optimizerDuck@powershell-windows

指定 Agent (Claude Code)

npx skills add itsfatduck/optimizerDuck --skill powershell-windows -a claude-code -g -y

安装 repo 全部 skill

npx skills add itsfatduck/optimizerDuck --all -g -y

预览 repo 内 skill

npx skills add itsfatduck/optimizerDuck --list

SKILL.md

Frontmatter

{
    "name": "powershell-windows",
    "risk": "unknown",
    "source": "community",
    "date_added": "2026-02-27",
    "description": "PowerShell Windows patterns. Critical pitfalls, operator syntax, error handling."
}

PowerShell Windows Patterns

Critical patterns and pitfalls for Windows PowerShell.

1. Operator Syntax Rules

CRITICAL: Parentheses Required

❌ Wrong	✅ Correct
`if (Test-Path "a" -or Test-Path "b")`	`if ((Test-Path "a") -or (Test-Path "b"))`
`if (Get-Item $x -and $y -eq 5)`	`if ((Get-Item $x) -and ($y -eq 5))`

Rule: Each cmdlet call MUST be in parentheses when using logical operators.

2. Unicode/Emoji Restriction

CRITICAL: No Unicode in Scripts

Purpose	❌ Don't Use	✅ Use
Success	✅ ✓	[OK] [+]
Error	❌ ✗ 🔴	[!] [X]
Warning	⚠️ 🟡	[*] [WARN]
Info	ℹ️ 🔵	[i] [INFO]
Progress	⏳	[...]

Rule: Use ASCII characters only in PowerShell scripts.

3. Null Check Patterns

Always Check Before Access

❌ Wrong	✅ Correct
`$array.Count -gt 0`	`$array -and $array.Count -gt 0`
`$text.Length`	`if ($text) { $text.Length }`

4. String Interpolation

Complex Expressions

❌ Wrong	✅ Correct
`"Value: $($obj.prop.sub)"`	Store in variable first

Pattern:

$value = $obj.prop.sub
Write-Output "Value: $value"

5. Error Handling

ErrorActionPreference

Value	Use
Stop	Development (fail fast)
Continue	Production scripts
SilentlyContinue	When errors expected

Try/Catch Pattern

Don't return inside try block
Use finally for cleanup
Return after try/catch

6. File Paths

Windows Path Rules

Pattern	Use
Literal path	`C:\Users\User\file.txt`
Variable path	`Join-Path $env:USERPROFILE "file.txt"`
Relative	`Join-Path $ScriptDir "data"`

Rule: Use Join-Path for cross-platform safety.

7. Array Operations

Correct Patterns

Operation	Syntax
Empty array	`$array = @()`
Add item	`$array += $item`
ArrayList add	`$list.Add($item)

8. JSON Operations

CRITICAL: Depth Parameter

❌ Wrong	✅ Correct
`ConvertTo-Json`	`ConvertTo-Json -Depth 10`

Rule: Always specify -Depth for nested objects.

File Operations

Operation	Pattern
Read	`Get-Content "file.json" -Raw
Write	`$data

9. Common Errors

Error Message	Cause	Fix
"parameter 'or'"	Missing parentheses	Wrap cmdlets in ()
"Unexpected token"	Unicode character	Use ASCII only
"Cannot find property"	Null object	Check null first
"Cannot convert"	Type mismatch	Use .ToString()

10. Script Template

# Strict mode
Set-StrictMode -Version Latest
$ErrorActionPreference = "Continue"

# Paths
$ScriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path

# Main
try {
    # Logic here
    Write-Output "[OK] Done"
    exit 0
}
catch {
    Write-Warning "Error: $_"
    exit 1
}