os-awareness

OS Awareness

Rule 1: Detect Before You Act

Before running any command, reading any file, or writing any path, explicitly know what OS you're on. Do not assume.

If you don't know, run one of these at the very start of the session:

• Windows: [System.Environment]::OSVersion.VersionString
• macOS / Linux: uname -a

Rule 2: Remember the OS for the Entire Session

Once detected, keep it in context. Do not re-detect unless you're in a new session or a subagent that wasn't told.

Key differences to track:

Aspect	Windows (PowerShell)	Linux / macOS (bash)
Path separator	\	/
Environment variable	$env:VAR	$VAR or ${VAR}
Home dir	$env:USERPROFILE	$HOME
Temp dir	$env:TEMP	/tmp
Line ending	CRLF	LF
Case sensitivity	Case-insensitive paths	Case-sensitive (Linux)
Executable extension	.exe, .ps1	no extension
Shell syntax	&&, `
Quoting	double for interpolation, single for literal	same
File tools	backtick escape, double-quote paths with spaces	single-quote paths

Rule 3: OS-Specific Gotchas

Windows-Specific

• Always quote paths with spaces: "C:\Program Files\..." — pwsh will split on spaces without quotes
• Use New-Item, Remove-Item, Get-ChildItem instead of mkdir, rm, ls for scripted operations
• Prefer Test-Path over [ -f ] or [ -d ]
• Git: LF/CRLF warnings are cosmetic — don't worry about them
• Node/Python: use npx.cmd / python not npx / python3
• Never use sudo, apt, brew, chmod, chown, systemctl, or kill -9

Linux-Specific

• Always prefer single quotes for paths to avoid shell expansion
• ~ expands to home directory
• Use /tmp for temp work
• Never use C:\ paths, $env:, or Get-ChildItem
• No .exe extension needed
• Be careful with case-sensitive filenames

macOS-Specific

• Same as Linux but note brew may be available
• $TMPDIR instead of /tmp (usually)
• Case-insensitive filesystem by default (like Windows)

Rule 4: Subagents Must Be Told

When spawning a subagent via task, include the OS info in the prompt so the subagent doesn't have to re-detect.

Example: "The host OS is Windows 11 (pwsh). Use PowerShell syntax and Windows paths."

Cross-references

• anti-global-install — OS detection prevents wrong install paths on Windows.

• portable-self-contained — Portable environment setup depends on OS-aware paths.

• toolchain-fallback — Toolchain paths and fallback strategies differ per OS; OS-aware detection is required.

• anti-global-install — OS detection determines correct install paths vs global defaults.

• skill-loader — Apply the capped selection policy when deciding which platform-aware skills should also be active for cross-platform tasks.

Bundled OS detection script

A bundled script at scripts/detect-os.ps1 (PowerShell) returns the host OS environment:

.\scripts\detect-os.ps1                    # human-readable report
.\scripts\detect-os.ps1 -Json              # JSON for programmatic use

Returns: platform (Windows/macOS/Linux), shell, path separator, case sensitivity, line ending convention, and syntax notes for each OS.

To use as a project-local tool:

cp <skill-path>/os-awareness/scripts/detect-os.ps1 .ai_scripts/
.ai_scripts\detect-os.ps1 -Json