tool-description-powershell

name	Tool Description: PowerShell
description	Describes the PowerShell command execution tool with syntax guidance, timeout settings, and instructions to prefer specialized tools over PowerShell for file operations
ccVersion	2.1.139
variables	["RENDER_COMMAND_NOTES_FN","COMMAND_NOTES","MAX_TIMEOUT_MS_FN","DEFAULT_TIMEOUT_MS_FN","MAX_OUTPUT_CHARS_FN","CUSTOM_USAGE_NOTE","GLOB_TOOL_NAME","GREP_TOOL_NAME","READ_TOOL_NAME","EDIT_TOOL_NAME","WRITE_TOOL_NAME","POWERSHELL_TOOL_NAME","CUSTOM_GIT_NOTES"]
allowed-tools	Read Write Edit Bash
license	BSD-3-Clause license
metadata	{"skill-author":"Lord1Egypt"}

Executes a given PowerShell command with optional timeout. Working directory persists between commands; shell state (variables, functions) does not.

IMPORTANT: This tool is for terminal operations via PowerShell: git, npm, docker, and PS cmdlets. DO NOT use it for file operations (reading, writing, editing, searching, finding files) - use the specialized tools for this instead.

${RENDER_COMMAND_NOTES_FN(COMMAND_NOTES)}

Before executing the command, please follow these steps:

1. Directory Verification:

   • If the command will create new directories or files, first use Get-ChildItem (or ls) to verify the parent directory exists and is the correct location

2. Command Execution:

   • Always quote file paths that contain spaces with double quotes
   • Capture the output of the command.

PowerShell Syntax Notes:

• Variables use $ prefix: $myVar = "value"
• Escape character is backtick (`), not backslash
• Use Verb-Noun cmdlet naming: Get-ChildItem, Set-Location, New-Item, Remove-Item
• Common aliases: ls (Get-ChildItem), cd (Set-Location), cat (Get-Content), rm (Remove-Item)
• Pipe operator | works similarly to bash but passes objects, not text
• Use Select-Object, Where-Object, ForEach-Object for filtering and transformation
• String interpolation: "Hello $name" or "Hello $($obj.Property)"
• Registry access uses PSDrive prefixes: HKLM:\SOFTWARE\..., HKCU:\... — NOT raw HKEY_LOCAL_MACHINE\...
• Environment variables: read with $env:NAME, set with $env:NAME = "value" (NOT Set-Variable or bash export)
• Call native exe with spaces in path via call operator: & "C:\Program Files\App\app.exe" arg1 arg2

Unix commands that DO NOT exist in PowerShell — use the equivalent instead:

• head / tail → Get-Content file -TotalCount N / -Tail N; piped: | Select-Object -First N / -Last N
• which → (Get-Command name).Source
• touch → if (-not (Test-Path path)) { New-Item -ItemType File path } (NEVER use New-Item -Force on a file — it truncates existing content)
• wc -l → (Get-Content file | Measure-Object -Line).Lines
• mkdir -p → New-Item -ItemType Directory -Force path (-p is not a PowerShell flag)
• rm -rf → Remove-Item -Recurse -Force path
• ln -s → New-Item -ItemType SymbolicLink -Path link -Target target
• chmod / chown → not applicable on Windows; use icacls only if ACL changes are required
• 2>/dev/null → 2>$null (but stderr is captured for you — usually unnecessary)
• VAR=x cmd → $env:VAR = 'x'; cmd (PowerShell has no inline env-var prefix)
• Bash control flow (if [ -f x ], for x in *, backtick cmd substitution) is a parser error — use if (Test-Path x), foreach ($x in ...), $(cmd)

Exit-code note: -ErrorAction SilentlyContinue suppresses error OUTPUT but the cmdlet failure still causes this tool to report exit 1. To make a cmdlet failure truly non-fatal, promote it to terminating and swallow it: try { Cmdlet ... -ErrorAction Stop } catch {} (without -ErrorAction Stop, non-terminating errors skip the catch and still exit 1).

Interactive and blocking commands (will hang — this tool runs with -NonInteractive):

• NEVER use Read-Host, Get-Credential, Out-GridView, $Host.UI.PromptForChoice, or pause
• Destructive cmdlets (Remove-Item, Stop-Process, Clear-Content, etc.) may prompt for confirmation. Add -Confirm:$false when you intend the action to proceed. Use -Force for read-only/hidden items.
• Never use git rebase -i, git add -i, or other commands that open an interactive editor

Passing multiline strings (commit messages, file content) to native executables:

• Use a single-quoted here-string so PowerShell does not expand $ or backticks inside. The closing '@ MUST be at column 0 (no leading whitespace) on its own line — indenting it is a parse error:

git commit -m @' Commit message here. Second line with $literal dollar signs. '@

• Use @'...'@ (single-quoted, literal) not @"..."@ (double-quoted, interpolated) unless you need variable expansion
• For arguments containing -, @, or other characters PowerShell parses as operators, use the stop-parsing token: git log --% --format=%H

Usage notes:

• The command argument is required.
• You can specify an optional timeout in milliseconds (up to ${MAX_TIMEOUT_MS_FN()}ms / ${MAX_TIMEOUT_MS_FN()/60000} minutes). If not specified, commands will timeout after ${DEFAULT_TIMEOUT_MS_FN()}ms (${DEFAULT_TIMEOUT_MS_FN()/60000} minutes).
• It is very helpful if you write a clear, concise description of what this command does.
• If the output exceeds ${MAX_OUTPUT_CHARS_FN()} characters, output will be truncated before being returned to you. ${CUSTOM_USAGE_NOTE?CUSTOM_USAGE_NOTE+ :""} - Avoid using PowerShell to run commands that have dedicated tools, unless explicitly instructed:
  • File search: Use ${GLOB_TOOL_NAME} (NOT Get-ChildItem -Recurse)
  • Content search: Use ${GREP_TOOL_NAME} (NOT Select-String)
  • Read files: Use ${READ_TOOL_NAME} (NOT Get-Content)
  • Edit files: Use ${EDIT_TOOL_NAME}
  • Write files: Use ${WRITE_TOOL_NAME} (NOT Set-Content/Out-File)
  • Communication: Output text directly (NOT Write-Output/Write-Host)
• When issuing multiple commands:
  • If the commands are independent and can run in parallel, make multiple ${POWERSHELL_TOOL_NAME} tool calls in a single message.
  • If the commands depend on each other and must run sequentially, chain them in a single ${POWERSHELL_TOOL_NAME} call (see edition-specific chaining syntax above).
  • Use ; only when you need to run commands sequentially but don't care if earlier commands fail.
  • DO NOT use newlines to separate commands (newlines are ok in quoted strings and here-strings)
• Do NOT prefix commands with cd or Set-Location -- the working directory is already set to the correct project directory automatically. ${CUSTOM_GIT_NOTES?CUSTOM_GIT_NOTES+ :""} - For git commands:
  • Prefer to create a new commit rather than amending an existing commit.
  • Before running destructive operations (e.g., git reset --hard, git push --force, git checkout --), consider whether there is a safer alternative that achieves the same goal. Only use destructive operations when they are truly the best approach.
  • Never skip hooks (--no-verify) or bypass signing (--no-gpg-sign, -c commit.gpgsign=false) unless the user has explicitly asked for it. If a hook fails, investigate and fix the underlying issue.