PowerShell skills and guardrails for reliable Windows command execution by AI agents.
General-purpose coding agents often run Windows and PowerShell less smoothly than Linux or macOS shells. This project gives agents a small, tested runtime aid: agent-facing skills, safe command shapes, compatibility checks, and helper scripts that reduce common Windows command failures.
Install from npm:
npm install -g @agent-shells/powershell-skills
powershell-skills install all
powershell-skills doctorUpdate explicitly:
powershell-skills updateInstall only one adapter:
powershell-skills install codex
powershell-skills install claude-codeGitHub install is still supported for unreleased branches or tags:
npm install -g github:agent-shells/powershell-skills#v0.5.1- Codex adapter for user-level skill discovery under
~/.codex/skills. - Claude Code adapter for personal skill discovery under
~/.claude/skills. powershell-skillsCLI for install, update, and doctor workflows.- Shared execution contract, pattern catalog, and sanitized failure corpus.
- PowerShell helper scripts for path resolution, command discovery, failure classification, external application execution, and read-only cmdlet execution.
Invoke-AgentPowerShell.ps1for structured, allowlisted, read-only cmdlets.- Windows PowerShell 5.1 and PowerShell 7 verification through GitHub Actions CI.
The adapters are written for agents, not for humans to prefix every command manually.
- Codex discovers
powershell-command-runnerfrom~/.codex/skills. - Claude Code discovers
powershell-command-runnerfrom~/.claude/skills. - Both adapters describe Windows, PowerShell, path handling, encoding, filesystem, timeout, and command-failure tasks as trigger cases.
If a current agent session has not refreshed its skill index, restart the agent or start a new session. Details are in adapter behavior.
The project is tested on:
- Windows PowerShell 5.1 through
powershell.exe. - PowerShell 7 through
pwsh. - Node.js 18+ for the npm CLI wrapper.
The npm layer is distribution and install UX. PowerShell scripts remain the compatibility source of truth. See compatibility and verification.
powershell-skills install codex
powershell-skills install claude-code
powershell-skills install all
powershell-skills doctor
powershell-skills updateUse powershell-skills doctor after install or update to check package files, PowerShell hosts, npm, and installed skill locations.
Run local checks:
npm test
npm pack --dry-run
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\verify-v0.1.ps1
pwsh -NoProfile -ExecutionPolicy Bypass -File .\scripts\verify-v0.1.ps1 -PowerShellExe pwshExpected result:
[OK] npm CLI smoke tests passed
[OK] release verification passed
| Topic | Document |
|---|---|
| Agent adapters and auto-trigger behavior | docs/adapters.md |
| Helper scripts and runners | docs/helpers.md |
| PowerShell 5.1 / 7 compatibility | docs/compatibility.md |
| Architecture and repository layout | docs/architecture.md |
| Security model and contribution boundaries | docs/security-model.md |
| Field-test notes | docs/field-tests/README.md |
- v0.1: Codex skill foundation.
- v0.2: PowerShell 5.1 / 7 compatibility matrix and CI.
- v0.3: Claude Code adapter.
- v0.4: npm distribution, update, doctor, and install UX.
- v0.5: read-only PowerShell cmdlet helper.
- v0.5.1: README and documentation polish.
This project accepts normal reviewed issues and pull requests. It does not include automatic telemetry, automatic failure upload, periodic collection, or upload of user command context.
- Supported adapters are Codex and Claude Code.
- Updates are explicit; there is no background auto-update service.
Invoke-AgentCommand.ps1runs external applications only.Invoke-AgentPowerShell.ps1is read-only and allowlist-based; it is not a general PowerShell script runner.- Destructive command execution is not automated and requires validation outside the runner.
- The failure corpus accepts only maintainer-reviewed, sanitized, minimized cases.