compatibility-check

name	compatibility-check
description	Check cross-platform and cross-version compatibility — Windows/Linux/macOS, Node/Bun, ESM/CJS, path separators, shell commands. Trigger on /compatibility-check, or when writing cross-platform code, debugging platform-specific failures, or checking runtime compatibility.
user-invocable	true
allowed-tools	Read, Grep, Glob, Bash

Compatibility Check

Check code for cross-platform and cross-version compatibility issues. Essential for projects targeting multiple OS, runtimes, or environments.

Checklist

1. File system

• Use path.join() or path.posix / path.win32 instead of hardcoded separators.
• Never hardcode / or \ in paths.
• fs calls — check if the path uses file:// protocol correctly on Windows.

2. Shell commands

• Avoid shell-specific syntax (grep flags, rg availability, sed -i differences).
• Use cross-platform tools or Node.js APIs instead of shell scripts when possible.
• Check for &&, ||, ; chaining that might behave differently.
• Environment variable setting differs (KEY=value vs set KEY=value vs $env:KEY=value).

3. Line endings

• Use .gitattributes to enforce LF/CRLF consistently.
• Never split lines on \n only — use os.EOL or handle both.

4. Runtime compatibility

• Node.js version: check for features requiring 18+, 20+, 22+.
• Bun compatibility: check for Node.js APIs not yet implemented in Bun.
• TypeScript target: does the output match the runtime?
• ESM vs CJS: check imports, __dirname, require() usage.

5. Browser compatibility (if applicable)

• Check for Web API availability (not all Node.js APIs exist in browsers).
• Check for platform-specific APIs (Windows ActiveX, macOS Security framework).

Rules

• Run on the target platform if possible — theory is not enough.
• Document known cross-platform issues in the project README or CONTRIBUTING.
• Prefer platform-agnostic Node.js APIs over OS-specific commands.
• Test path-related code on Windows specifically (most common source of bugs).

Experience Log

This skill learns from experience. Mechanism:

• Read .claude/experience/'"$s"'.md at skill start to benefit from past lessons.
• Write to .claude/experience/'"$s"'.md after use if you learned something new.
• Format: YYYY-MM-DD: <lesson> — one line per entry.
• Evolve: If the same issue repeats 3+ times, update this SKILL.md itself.