Making a Claude skill work on Windows, macOS and Linux
Instructions travel well; scripts and paths do not. The usual cross-platform breakages in skills, and how to write steps that work whichever OS the buyer is on.
Prose instructions do not care which operating system they run on. Commands and scripts do. Most cross-platform bugs in skills come from a shell command written for one system.
| Breaks on some systems | Works everywhere |
|---|---|
Hard-coded / paths in scripts | The language's path library |
rm -rf, sed -i in instructions | A script in Python or Node that does the same |
| Assuming a tool is installed | A preflight check that names what is missing |
| Line endings in generated files | Explicit newline handling |
State what you support
Put the supported systems in the requirements, and mean it. A skill that is honestly macOS-only is better than one that claims all three and fails on Windows. Our macOS design skill says it targets Mac apps, and its description says so too, as in when not to use a skill.
Then test the claim: run the same checks on each system, which is a small change once you have skills in CI.
Questions
Do Claude skills work on Windows?
The instructions do. Problems come from scripts and commands that assume a Unix shell, specific paths or tools that are not installed by default on Windows.
How do I write paths that work everywhere?
In scripts, build paths with the language's path library instead of hard-coding slashes. In instructions, describe locations relative to the project.
Should I test on all three operating systems?
If your requirements list says a skill supports them, yes. A CI matrix across operating systems is the cheapest way.