v0.5.1 - README and documentation polish

Documentation-only patch.

• Shortened the root README into a clearer GitHub and npm landing page.
• Split detailed adapter behavior, helper script notes, compatibility guidance, architecture, and security boundaries into focused docs under docs/.
• Published npm package @agent-shells/powershell-skills@0.5.1.
• No runtime behavior changed from v0.5.

Verification:

• npm test
• npm pack --dry-run
• Windows PowerShell 5.1 release verification
• PowerShell 7 release verification
• GitHub Actions CI run 28607772523 passed

v0.5

v0.5 - Read-Only PowerShell Helper

Release date: 2026-07-02

Summary

V0.5 adds a constrained PowerShell cmdlet helper for agents that need structured output from read-only PowerShell operations. It does not change the Application-only boundary of Invoke-AgentCommand.ps1.

The package is published on npm as @agent-shells/powershell-skills.

Added

• core/scripts/Invoke-AgentPowerShell.ps1.
• Structured JSON spec support:

{
  "cmdlet": "Test-Path",
  "parameters": {
    "LiteralPath": "C:\\path with space\\file.txt"
  },
  "cwd": "C:\\workspace",
  "timeout_seconds": 15,
  "risk": "normal"
}

• Allowlisted read-only cmdlets:
  • Test-Path
  • Resolve-Path
  • Get-Item
  • Get-ChildItem
  • Get-Content
  • Get-Command
  • Get-Location
  • Get-Process
  • Get-Service
  • Select-String

Safety Boundaries

• Rejects aliases such as gci.
• Rejects functions and non-cmdlet commands.
• Rejects cmdlets outside the read-only allowlist.
• Rejects parameters outside each cmdlet's parameter allowlist.
• Rejects destructive risk.
• Uses timeout handling for bounded execution.
• Produces JSON with status, stdout, stderr, output, timeout, duration, and classification fields.
• Handles Windows npm .cmd dispatch in the CLI so doctor and update can run without shell deprecation warnings.

Verification

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 pwsh

Install

npm install -g @agent-shells/powershell-skills
powershell-skills install all
powershell-skills doctor

Boundaries

• This is not an unrestricted PowerShell runner.
• It does not execute free-form script text.
• It does not execute destructive commands.
• It does not bypass agent, OS, workspace, or user permission rules.

v0.4

v0.4 - npm Distribution and Install UX

Release date: 2026-07-02

Summary

V0.4 adds an npm distribution layer without rewriting the PowerShell core. The new powershell-skills CLI wraps the existing installers, adds doctor diagnostics, and provides an explicit update path.

Added

• package.json for @agent-shells/powershell-skills.
• bin/powershell-skills.js CLI.
• powershell-skills install codex.
• powershell-skills install claude-code.
• powershell-skills install all.
• powershell-skills doctor.
• powershell-skills update.
• --json output for install and doctor automation.
• --dry-run for update inspection.
• tests/npm-cli-smoke.js for CLI verification.

Installation

Install from GitHub through npm:

npm install -g github:agent-shells/powershell-skills#v0.4
powershell-skills install all
powershell-skills doctor

After npm registry publishing is available:

npm install -g @agent-shells/powershell-skills
powershell-skills install all
powershell-skills doctor

Verification

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 pwsh

Boundaries

• npm is a distribution and UX layer only.
• Existing PowerShell scripts remain the source of truth.
• Updates are explicit and user-triggered.
• No telemetry or failure upload was added.
• Destructive commands still require external validation and are not auto-executed.

v0.3 - Claude Code Adapter

v0.3 Release Notes

Release date: 2026-07-02

V0.3 adds Claude Code compatibility and validates that the skill can be used in a real Claude Code session on Windows.

Highlights

• Added Claude Code adapter at adapters/claude-code/powershell-command-runner/.
• Added global Claude Code installer:

powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\install-claude-global.ps1

• Installs to:

%USERPROFILE%\.claude\skills\powershell-command-runner

• Bundles core/ inside the installed skill.
• Rewrites core references to ${CLAUDE_SKILL_DIR}/core.
• Keeps the same privacy boundary: no telemetry, no failure upload, no scheduled collection.

Local Claude Code Validation

Tested with Claude Code 2.1.158 in normal non-bare mode:

• Explicit /powershell-command-runner invocation loaded the skill.
• A Windows path task without a slash command loaded the skill automatically.
• Claude Code used Test-Path -LiteralPath against a path containing both a space and Chinese characters.
• The command returned True.

Known limit:

• --bare mode returned Unknown command: /powershell-command-runner during local testing. Do not use --bare as the standard skill acceptance path.

Verification

powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\verify-v0.1.ps1 -PowerShellExe powershell.exe
pwsh -NoProfile -ExecutionPolicy Bypass -File .\scripts\verify-v0.1.ps1 -PowerShellExe pwsh

v0.2 - PowerShell Compatibility Matrix

v0.2 Release Notes

Release date: 2026-07-02

V0.2 adds the compatibility floor required for a Windows agent-runtime aid: the core scripts must run under both Windows PowerShell 5.1 and PowerShell 7.

Highlights

• Added GitHub Actions CI on windows-latest.
• Added matrix jobs:
  • Windows PowerShell 5.1 through powershell.exe
  • PowerShell 7 through pwsh
• Added -PowerShellExe to smoke and release verification scripts.
• Reworked helper invocations so nested helper calls use the current PowerShell host.
• Fixed JSON shape handling across 5.1 and 7.
• Adjusted timeout smoke tests to avoid environment-specific false failures while still catching process-tree wait regressions.

Why It Matters

The goal is not to make PowerShell 5.1 and 7 identical. The goal is to give agents a reliable base that detects and avoids known runtime differences before command execution fails.

Verification

powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\verify-v0.1.ps1 -PowerShellExe powershell.exe
pwsh -NoProfile -ExecutionPolicy Bypass -File .\scripts\verify-v0.1.ps1 -PowerShellExe pwsh

v0.1 - Codex Skill Foundation

v0.1 Release Notes

Release date: 2026-07-02

V0.1 establishes the Codex-first foundation for improving Windows and PowerShell command reliability.

Highlights

• Codex skill adapter with implicit invocation metadata.
• Shared core/ contract for command-risk routing.
• Pattern catalog for shell selection, path handling, quoting, encoding, tool discovery, parser traps, file operation safety, timeout handling, and repeated failures.
• JSON-oriented helper scripts:
  • Test-AgentCommand.ps1
  • Resolve-AgentPath.ps1
  • Classify-AgentFailure.ps1
  • Invoke-AgentCommand.ps1
• Seed failure corpus with sanitized minimal cases.
• Repo-local Codex install for development.
• Global Codex install for normal user-level use.
• Smoke tests and release verification.

Limits

• Codex was the only implemented adapter in v0.1.
• PowerShell 7 compatibility was a target but not yet covered by CI.
• No npm package or auto-update channel existed.
• No telemetry, failure upload, scheduled collection, or raw command-context collection existed.

Verification

powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\verify-v0.1.ps1