AgentSkillsCN

wsl-shell-reliability

在 Windows 上，为 AI 代理制定以可靠性为先的 Shell 选择策略。应根据执行风险而非个人偏好来选择 WSL 或 PowerShell。

SKILL.md
--- frontmatter
name: wsl-shell-reliability
description: Reliability-first shell selection policy for AI agents on Windows. Choose WSL or PowerShell based on execution risk, not preference.
license: MIT
compatibility: Windows (WSL optional; recommended for POSIX-fragile workflows)
metadata:
  author: simon
  version: "2.0"

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

QuestionIf YesIf No
Windows-native task/tool?Use PowerShell/CMDNext question
POSIX/bash semantics required?Use WSL/bashNext question
Need Linux-first parity?Prefer WSL/bashNext question
High Windows-shell parse risk?Prefer WSL/bashNext question
Both paths low risk?Pick shell with fewer moving partsN/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: