Windows Shell Tool Selection
Skill1 starsChanged 4 months agoMITView on GitHub
Cheat-sheet for when to use a POSIX/Bash tool vs. a PowerShell tool on Windows, and the specific syntax traps between them. Use whenever running shell commands on a Windows machine that has both available, before writing a multi-step or non-trivial command, not after it silently fails.
In this repository25 other files it gives its agents.
- templates/AGENTS.mdAGENTS.md
- braindump-autoSkill
- braindumpSkill
- Capability Claim GroundingSkill
- Derived Figure AuditSkill
- design-review-loopSkill
- Dictation Garble CatcherSkill
- Discord Todo OpsSkill
- Full Account Security AuditSkill
- Large Task Session SplitSkill
- Personal Dashboard StyleSkill
- Pre-Push Secret ScanSkill
- Project Design DocSkill
- Public Repo Leak RetractionSkill
- repo-hygieneSkill
- Repo Index Drift CheckSkill
- Safe Section DeletionSkill
- Session HandoffSkill
- Skill Overlap AuditSkill
- superbraindumpSkill
- ui-change-visual-verifySkill
- Verify, Don't TrustSkill
- Windows Process Restart (Safe)Skill
- Worktree Task-Pack VerificationSkill
- Zombie Process SweepSkill
The file
Files
Windows Shell Tool Selection
On Windows with both a Bash tool (Git-Bash/POSIX) and a PowerShell tool available, picking wrong or mixing syntax from one into the other produces failures that don't always look like failures.
Known traps
PowerShell chaining is not &&/||. Windows PowerShell 5.1 has no pipeline chain operators. A && B is a parse error. Use:
A; if ($?) { B } # B only if A succeeded
A; B # unconditionalPowerShell has no ternary, null-coalescing, or null-conditional operators (?:, ??, ?.) in 5.1. Use explicit if/else and $null -eq checks.
A multi-step PowerShell chain is all-or-nothing at parse time. step1; step2; step3: if step 3 has a syntax error, steps 1 and 2 never ran at all, even though they were valid. A silent-looking failure can actually mean nothing executed. Split suspect chains into separate calls to isolate which part is failing.
Don't redirect 2>&1 on native executables in PowerShell 5.1. It wraps each stderr line in a NativeCommandError and flips $? to false even on a real exit-code-0 success. stderr is already captured. Don't redirect it.
Git-Bash heredocs for multi-line content (commit messages, file writes): never inline multi-line node -e or similar on Windows. A known Git-Bash bug mangles multi-line script fragments passed inline into literal stray files on disk. Use a proper heredoc (<<'EOF' ... EOF) or write to a temp file first.
PowerShell here-strings (@'...'@) must have the closing '@ at column 0: indenting it is a parse error, not a formatting choice.
Encoding: >/Out-File in PowerShell 5.1 default to UTF-8 with BOM; Set-Content/Add-Content default to the system ANSI codepage. If another tool will read the file, pass -Encoding utf8 explicitly rather than relying on the default.
Which tool for which job
| Task | Use |
| git, npm, docker, standard CLI tools | PowerShell (or Bash: either works, PowerShell usually has better native integration) |
| Multi-line heredoc content (commit messages, file bodies) | Bash tool: PowerShell here-strings are stricter about formatting |
Anything doing find/grep/sed-style text processing | Bash tool: the POSIX tools are more direct than PowerShell equivalents |
| Windows-native operations (registry, services, WMI/CIM queries) | PowerShell: no Bash equivalent exists |
Rule of thumb
If a command is non-trivial (more than one clause, any conditional, any heredoc), decide which tool it's going into before writing it, based on which syntax it actually needs. Don't write PowerShell-flavored syntax into a Bash call or vice versa and debug the failure after the fact.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.