WSL Shell Reliability

Use this skill to maximize terminal command success on Windows.

This skill does not force WSL. It enforces a reliability-first policy:

• pick the shell with lower failure risk,
• preserve command intent across fallback,
• never switch shells silently.

Trigger conditions

• Any terminal execution task on Windows.
• AI-generated commands that look bash/POSIX-oriented.
• Repeated failures caused by quoting/path/shell mismatch.

One-screen decision table

Question	If Yes	If No
Windows-native task/tool?	Use PowerShell/CMD	Next question
POSIX/bash semantics required?	Use WSL/bash	Next question
Need Linux-first parity?	Prefer WSL/bash	Next question
High Windows-shell parse risk?	Prefer WSL/bash	Next question
Both paths low risk?	Pick shell with fewer moving parts	N/A

Examples:

• Windows-native: winget, reg, netsh, .exe/.msi, service/system ops.
• POSIX-heavy: rm -rf, export, ./script.sh, grep/sed/awk, complex pipes.

Rule priority (conflict resolution)

Apply rules in this priority order when guidance appears to conflict:

1. Windows-native exclusions (must use PowerShell/CMD).
2. Decision table hard signals (POSIX dependence, high parse risk).
3. Fallback policy + intent preservation.
4. Convenience preferences (tool availability, fewer steps).

If still ambiguous, choose the shell with lower execution-failure risk.

Windows-native exclusions (prefer PowerShell/CMD)

• winget, scoop, choco
• PowerShell cmdlets and registry/service/system commands
• .msi/.exe installer flows
• Windows-targeted msbuild/.NET packaging chains

Execution protocol

1. Select shell with the decision table.
2. Generate syntax for that shell (do not mix grammar).
3. Execute command.
4. If failure is shell-related, fallback to the other shell.
5. Preserve intent exactly; only translate syntax.
6. State fallback explicitly.

Shell-aware generation rules

• WSL/bash: POSIX syntax allowed.
• PowerShell: PowerShell-native quoting/escaping.
• CMD: use only when required by task/tool.

Do not run bash syntax directly in PowerShell/CMD.

WSL templates

• wsl.exe -e bash --noprofile --norc -lc "<command>"
• wsl.exe -e bash --noprofile --norc -lc "cd /mnt/<drive>/<path> && <command>"

Quick translation hints (bash -> PowerShell)

• export FOO=bar -> $env:FOO = "bar"
• rm -rf <path> -> Remove-Item -Recurse -Force <path>
• cp -r a b -> Copy-Item a b -Recurse
• mv a b -> Move-Item a b
• cat file -> Get-Content file

Use translations only when fallback requires them.

Guardrails

• Never silently switch shells.
• Never change command semantics when switching shells.
• Never install tools just to enforce one-shell purity.
• Prefer existing toolchain in the selected shell first.

Fallback policy

Fallback to the other shell when:

• WSL is unavailable or unstable,
• the tool cannot be resolved in current shell,
• task is clearly Windows-native,
• command fails due to shell parsing/quoting mismatch.

When falling back, report:

1. what failed,
2. why shell changed,
3. equivalent command intent preserved.

Known limitations

• Some enterprise environments disable WSL installation/execution.
• VPN/proxy/DNS policies may break package/network operations in one shell.
• Cross-filesystem operations can have inconsistent performance.
• Security policies may block execution scripts in PowerShell.

In these cases, prefer explicit fallback and report constraints clearly.

References

Deep technical notes and examples:

• references/REFERENCE.md
• references/SCENARIOS.md