ensuring-cross-platform
Skill2 starsChanged 3 months agoMITView on GitHub
Apply platform-agnostic engineering rules so code, tests, and Docker builds behave identically on Linux, macOS, and native Windows. Use when writing or reviewing code that touches the filesystem, shell, subprocess, encoding, time, paths, native dependencies, or CI matrix — or when the user mentions Windows, macOS, Linux, "works on my machine", cross-platform, portability, or Docker.
In this repository19 other files it gives its agents.
- .claude/CLAUDE.mdCLAUDE.md
- api-designSkill
- building-frontend-uiSkill
- debugging-agent-runsSkill
- developing-featuresSkill
- developing-features-tddSkill
- documenting-featuresSkill
- evaluating-ai-outputSkill
- exploratory-testingSkill
- fixing-bugsSkill
- playwright-cliSkill
- reviewing-codeSkill
- running-agent-loopsSkill
- security-reviewSkill
- threat-modelingSkill
- validating-in-realitySkill
- writing-prdSkill
- writing-pull-requestsSkill
- writing-testsSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
13 rules. About 0 are common, 7 are distinctive, and 6 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈7
Distinctive · estimate
This author's own choices. Worth a look.
6
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 28
If the project's real target is narrower (e.g., Linux only), the user must say so explicitly.
- Distinctive: line 32
Before writing any code that touches the filesystem, the shell, the environment, or external processes, answer:
- Distinctive: line 40
If any answer is "I don't know" → stop, find out, then continue.
- Very specific: line 46
Path APIs, not string concatenation: Use the language's path-join API (pathlib.Path / path.join / filepath.Join).
- Distinctive: line 47
Always specify encoding for text I/O: Default to UTF-8. Never rely on locale-dependent defaults — they break on Windows hosts.
- Very specific: line 48
No hardcoded shell commands: Use language-native APIs (shutil.rmtree, fs.rm, etc.).
- Very specific: line 49
Line endings: read tolerantly, write per-OS: Read with splitlines()-equivalent (handles \n, \r\n, \r).
- Very specific: line 50
OS-aware temp / cache / config directories: Use tempfile-equivalents and a platformdirs-equivalent.
- Distinctive: line 51
Validate filenames before writing them: when the name comes from user input or an external source.
- Distinctive: line 52
Time: UTC at boundaries, local at presentation: Never store local time. Never compare timezones with naive datetimes.
- Very specific: line 68
If the project ships Docker, the image MUST build successfully from at least the Linux runner, and a docker run smoke test that exercises …
- Distinctive: line 114
If any box fails → fix before delivering.
- Very specific: line 118
Before closing the task, ask: *did I encounter a platform constraint, trap, or convention not in this SKILL.md or references/?* If yes, …
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Ensuring Cross-Platform Behavior
A feature is not "done" because it works on the developer's machine. It is done when it produces identical, correct behavior on every supported platform — verified by tests that run on every supported platform.
This skill is the single source of truth for platform agnosticism. Other skills (developing-features, developing-features-tdd, fixing-bugs, writing-tests, reviewing-code, documenting-features) reference this one and apply its principles to their respective phases.
Read first (always)
List learnings/ and read every file relevant to the current task. Project-specific platform constraints, supported-OS lists, or known traps live there and override the defaults below. If a learning conflicts with this file, the learning wins — mention it to the user.
Default supported platforms
Until the project says otherwise, assume the defensive case:
| Platform | Architectures | Notes |
| Linux | x86_64, arm64 | Glibc distros (Ubuntu 22.04+, Debian 12+, RHEL 9+) |
| macOS | x86_64, arm64 | macOS 13+ |
| Windows | x86_64 | Windows 10 (22H2) / 11 — native, not WSL |
| Docker | linux/amd64, linux/arm64 | Linux containers; host OS may be any of the above |
If the project's real target is narrower (e.g., Linux only), the user must say so explicitly. WSL is not a substitute for native Windows support unless the user documents that exception.
Pre-implementation platform check
Before writing any code that touches the filesystem, the shell, the environment, or external processes, answer:
- Which platforms must this run on? (See the table above or the project's override.)
- Am I making any POSIX assumption that is not guaranteed on Windows? — path separator, line endings, encoding, fork, signals, file permissions, atomic rename.
- Am I calling any external tool I am not declaring as a dependency? —
git,make,curl,tar,unzip, anything assumed onPATH. - What is the failure mode on the platform I am NOT testing on right now? — "It probably works" is not an answer.
- Is this code in a hot path that varies per OS? — filesystem watching, process spawning, GUI, GPU. If yes, design the abstraction first (see
references/platform-specific-code.md).
If any answer is "I don't know" → stop, find out, then continue.
Mandatory patterns
These are language-agnostic principles. For concrete code in Python, TypeScript, Java, Go, C#, etc., see references/patterns.md.
- Path APIs, not string concatenation. Use the language's path-join API (
pathlib.Path/path.join/filepath.Join). Never concatenate paths with/or\. - Always specify encoding for text I/O. Default to UTF-8. Never rely on locale-dependent defaults — they break on Windows hosts.
- No hardcoded shell commands. Use language-native APIs (
shutil.rmtree,fs.rm, etc.). When you must invoke a subprocess, pass arguments as a list, never withshell=True. For tools assumed on PATH, check existence first and declare the dependency. - Line endings: read tolerantly, write per-OS. Read with
splitlines()-equivalent (handles\n,\r\n,\r). Write in text mode and let the runtime translate, except for files where the line ending must be exact (protocols, binary formats) — write in binary mode then. - OS-aware temp / cache / config directories. Use
tempfile-equivalents and aplatformdirs-equivalent. Never hardcode/tmp,~/.config, orC:\.... - Validate filenames before writing them when the name comes from user input or an external source. Reject Windows reserved names (
CON,PRN,AUX,NUL,COM1-9,LPT1-9), forbidden chars (< > : " / \ | ? *+ control chars), trailing space/dot, and./... - Time: UTC at boundaries, local at presentation. Never store local time. Never compare timezones with naive datetimes.
- Native dependencies must have prebuilt artifacts for every target architecture (manylinux + macosx + win_amd64 wheels, prebuilt Node binaries, etc.). Anything calling
LoadLibrary("foo.dll")/dlopen("libfoo.so")is platform-specific by definition — wrap and isolate.
The full anti-pattern reference table (POSIX-only mistakes and their portable fixes) is in references/anti-patterns.md.
CI matrix is mandatory
Tests that only run on Linux prove nothing about Windows or macOS. A green build on one OS is necessary but never sufficient.
The CI configuration MUST run the test suite on every supported OS in the matrix, with fail-fast: false so that a Windows failure does not hide a parallel Linux pass that confirms the bug is OS-specific.
A PR is NOT mergeable when:
- Any matrix cell is failing.
- A matrix cell was removed to "make CI green".
- The matrix was bypassed via merge override "just this once".
If the project ships Docker, the image MUST build successfully from at least the Linux runner, and a docker run smoke test that exercises one critical path MUST be part of the matrix. See references/docker.md for image hygiene and .dockerignore baseline.
Platform-specific code, when justified
Some functionality is genuinely OS-specific (filesystem watchers, GPU, system notifications, hardware sensors). When that happens:
- Isolate behind a single abstraction. A
Notifierprotocol; one factory; lazy imports inside each branch so importing a Linux-only module on Windows does not crash startup. - Detect at runtime, not at import time.
- Test each implementation on its target platform in CI.
- Document the branch map — every place the implementation differs per OS, why, and the test that covers each branch (see
documenting-featuresskill). - Loud, early failure for unsupported platforms. Raise
NotImplementedError(or equivalent) with a clear message naming the platform and the feature. Silent fallback to a no-op is forbidden.
Concrete shape and example code in references/platform-specific-code.md.
Validation checklist (before delivery)
Apply this in addition to the checklists in developing-features, writing-tests, etc. Every box must be ticked.
Code
- All paths constructed with a path API — no string concatenation, no hardcoded
/or\. - All file I/O specifies encoding explicitly (UTF-8 unless documented otherwise).
- No hardcoded shell commands; subprocess calls use list args, no shell expansion.
- No hardcoded
/tmp,~/.config,C:\…— uses temp / platformdirs equivalents. - No reliance on POSIX utilities (
ls,grep,cat,rm) called from code. - Time stored in UTC at boundaries; local time only at presentation.
- Filename validation rejects Windows-reserved names and forbidden chars when input is external.
- Native dependencies have prebuilt artifacts for every target architecture (verified on the registry).
Tests
- Tests pass on every supported platform (CI matrix), not just the developer's machine.
- Tests do not assume case-sensitive filesystems.
- Tests do not assume specific line endings.
- Tests do not depend on
/tmp,/etc, or other POSIX-specific locations. - Platform-specific code has tests that run on each target platform.
Docker (when applicable)
- Image builds reproducibly from Linux, macOS, AND Windows hosts.
.dockerignoreexcludes host-OS artifacts (.DS_Store,Thumbs.db,node_modules, etc.).- Smoke test runs
docker runagainst one critical path in CI. - No bind mounts in production compose; named volumes only.
Documentation
- Supported OS versions are listed in README.
- Known platform-specific limitations are documented.
- Platform-specific code branches are documented (which OS, why, where).
If any box fails → fix before delivering. There is no "I'll add Windows support next sprint" — by then the design has calcified around POSIX assumptions and the cost is 10x.
Final step: capture a learning
Before closing the task, ask: did I encounter a platform constraint, trap, or convention not in this SKILL.md or references/? If yes, append a learnings/YYYY-MM-DD-slug.md per learnings/README.md. If no, skip — don't write filler.
See also
references/patterns.md— Python/TypeScript/Go/Java/C# code for the mandatory patterns.references/anti-patterns.md— POSIX-only mistakes with the portable fix.references/docker.md— image hygiene,.dockerignorebaseline, volume mounts.references/platform-specific-code.md— protocol + factory pattern for OS-conditional code.learnings/— project-specific platform constraints accumulated over time.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

