PowerShell Command Guard

A compact Codex skill for reliable Windows PowerShell execution.
一个减少 PowerShell 路径、转义、进程和退出码错误的轻量 Codex Skill。

PowerShell Command Guard gives Codex a small set of high-value rules for executing PowerShell commands on Windows. It focuses on failures that are easy to introduce and expensive to debug: paths containing spaces, nested quoting, native exit codes, detached GUI processes, unsafe wildcard operations, and Unity batch-mode launches.

PowerShell Command Guard 为 Codex 提供一组精简、可复用的 PowerShell 执行规则。它不会替代 PowerShell 知识，而是约束最容易出错的部分，并要求用真实的退出码、进程状态、日志或产物验证结果。

Why PowerShell Command Guard?

• Correct handling of Windows paths and quoted executable names.
• Clear separation between PowerShell cmdlet failures and native process exit codes.
• Safer computed-path and recursive file operations.
• Reliable verification for applications that detach after launch.
• Unity-specific guidance loaded only for Unity tasks.
• Progressive disclosure: the core skill stays small to reduce token use.

Repository layout

powershell-command-guard/
├── SKILL.md                         # Compact entry point loaded by Codex
├── agents/openai.yaml              # UI metadata and default invocation
├── references/powershell-patterns.md
├── references/unity.md             # Loaded only for Unity work
├── README.md
└── LICENSE

Installation

Option 1: Clone directly into the Codex skills directory

$skillsRoot = Join-Path $env:USERPROFILE '.codex\skills'
New-Item -ItemType Directory -Path $skillsRoot -Force | Out-Null
git clone 'https://github.com/Hugohong258/powershell-command-guard.git' (Join-Path $skillsRoot 'powershell-command-guard')

Start a new Codex turn after installation so the skill catalog refreshes.

Option 2: Copy an existing checkout

$destination = Join-Path $env:USERPROFILE '.codex\skills\powershell-command-guard'
Copy-Item -LiteralPath 'C:\path\to\powershell-command-guard' -Destination $destination -Recurse

Do not nest the repository as powershell-command-guard/powershell-command-guard; SKILL.md must be directly inside the installed skill folder.

Usage

PowerShell Command Guard supports automatic discovery when a task runs PowerShell on Windows. You can also invoke it explicitly:

Use $powershell-command-guard to run the Unity verification command and diagnose any failure.

用 $powershell-command-guard 安全地移动这些文件，并验证目标路径和执行结果。

Core behavior

Risk	Command Guard guidance
Executable path contains spaces	Use & 'C:\Program Files\…\tool.exe'
Arguments contain spaces	Pass a PowerShell argument array
Literal path contains [ or *	Use -LiteralPath
Cmdlet failure is non-terminating	Use -ErrorAction Stop when required
Native command fails	Check the returned exit code immediately
GUI launcher returns early	Verify the real process, log, or artifact
Recursive deletion or move	Resolve and validate the absolute target first
Unity batch mode	Check duplicate editors and inspect the Unity log

Design principles

1. Compact by default. Only broadly useful rules live in SKILL.md.
2. Progressive disclosure. Detailed patterns and Unity guidance are read only when relevant.
3. Verify, don't assume. A launched process is not necessarily a completed task.
4. Correct the cause. An identical failed command is never repeated blindly.
5. Preserve scope. The skill improves command execution without expanding the user's requested operation.

Validation

Before publishing a change:

python <path-to-skill-creator>\scripts\quick_validate.py .

The official validator requires Python and PyYAML. If it is unavailable, verify at minimum:

• valid YAML frontmatter with name and description;
• folder name and name both equal powershell-command-guard;
• no scaffold placeholders such as TODO;
• every referenced file exists;
• agents/openai.yaml contains a prompt that explicitly names $powershell-command-guard.

Scope and limitations

PowerShell Command Guard reduces common command-construction and verification mistakes; it cannot repair a broken external tool, grant permissions, supply missing credentials, or guarantee that third-party applications behave correctly. It does not authorize destructive or external actions beyond the user's request.

Contributing

Keep additions narrow and evidence-driven. Prefer correcting a demonstrated failure pattern over accumulating general PowerShell advice. Move substantial tool-specific rules into a focused reference so the default skill remains token-efficient.

License

Released under the MIT License.