| 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.
