Wsl Shell Reliability

Reliability-first shell selection policy for AI agents on Windows. Choose WSL or PowerShell based on execution risk, not preference.

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