agentleFS
CristhianzlCristhianzl/pocket-claude/.claude/skills/ensuring-cross-platform/SKILL.md

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.

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
  1. Distinctive:

    If the project's real target is narrower (e.g., Linux only), the user must say so explicitly.

    line 28
  2. Distinctive:

    Before writing any code that touches the filesystem, the shell, the environment, or external processes, answer:

    line 32
  3. Distinctive:

    If any answer is "I don't know" → stop, find out, then continue.

    line 40
  4. Very specific:

    Path APIs, not string concatenation: Use the language's path-join API (pathlib.Path / path.join / filepath.Join).

    line 46
  5. Distinctive:

    Always specify encoding for text I/O: Default to UTF-8. Never rely on locale-dependent defaults — they break on Windows hosts.

    line 47
  6. Very specific:

    No hardcoded shell commands: Use language-native APIs (shutil.rmtree, fs.rm, etc.).

    line 48
  7. Very specific:

    Line endings: read tolerantly, write per-OS: Read with splitlines()-equivalent (handles \n, \r\n, \r).

    line 49
  8. Very specific:

    OS-aware temp / cache / config directories: Use tempfile-equivalents and a platformdirs-equivalent.

    line 50
  9. Distinctive:

    Validate filenames before writing them: when the name comes from user input or an external source.

    line 51
  10. Distinctive:

    Time: UTC at boundaries, local at presentation: Never store local time. Never compare timezones with naive datetimes.

    line 52
  11. Very specific:

    If the project ships Docker, the image MUST build successfully from at least the Linux runner, and a docker run smoke test that exercises …

    line 68
  12. Distinctive:

    If any box fails → fix before delivering.

    line 114
  13. Very specific:

    Before closing the task, ask: *did I encounter a platform constraint, trap, or convention not in this SKILL.md or references/?* If yes, …

    line 118

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

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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:

PlatformArchitecturesNotes
Linuxx86_64, arm64Glibc distros (Ubuntu 22.04+, Debian 12+, RHEL 9+)
macOSx86_64, arm64macOS 13+
Windowsx86_64Windows 10 (22H2) / 11 — native, not WSL
Dockerlinux/amd64, linux/arm64Linux 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:

  1. Which platforms must this run on? (See the table above or the project's override.)
  2. Am I making any POSIX assumption that is not guaranteed on Windows? — path separator, line endings, encoding, fork, signals, file permissions, atomic rename.
  3. Am I calling any external tool I am not declaring as a dependency? — git, make, curl, tar, unzip, anything assumed on PATH.
  4. What is the failure mode on the platform I am NOT testing on right now? — "It probably works" is not an answer.
  5. 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 with shell=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 a platformdirs-equivalent. Never hardcode /tmp, ~/.config, or C:\....
  • 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:

  1. Isolate behind a single abstraction. A Notifier protocol; one factory; lazy imports inside each branch so importing a Linux-only module on Windows does not crash startup.
  2. Detect at runtime, not at import time.
  3. Test each implementation on its target platform in CI.
  4. Document the branch map — every place the implementation differs per OS, why, and the test that covers each branch (see documenting-features skill).
  5. 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.
  • .dockerignore excludes host-OS artifacts (.DS_Store, Thumbs.db, node_modules, etc.).
  • Smoke test runs docker run against 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, .dockerignore baseline, volume mounts.
  • references/platform-specific-code.md — protocol + factory pattern for OS-conditional code.
  • learnings/ — project-specific platform constraints accumulated over time.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.