cross-platform-guardian

Audit and fix cross-platform compatibility issues in dotfiles across macOS, Ubuntu, and Fedora.

193|16|Updated Mar 10, 2023

Search Tags:#automation #testing #Docker #compatibility #dotfiles #cross-platform #Nix

Ready to run

npx skills add https://github.com/wcygan/dotfiles --skill cross-platform-guardian

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: cross-platform-guardian
Source: https://github.com/wcygan/dotfiles/tree/main/.claude/skills/cross-platform-guardian
Command: npx skills add https://github.com/wcygan/dotfiles --skill cross-platform-guardian

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) components.

What problem does it solve?

This Skill ensures cross-platform compatibility for your dotfiles across macOS (Intel/ARM), Ubuntu, and Fedora by detecting hard-coded paths, platform-specific assumptions, and architecture gaps, then auto-fixing where possible and validating with Nix + Docker testing.

Core Features & Use Cases

Audit: Scans for hard-coded paths, missing guards, and platform-specific assumptions.
Auto-Fix: Applies safe fixes to command usage, guards, and config paths.
Test: Validates the Nix flake across all four architectures (x86_64-linux, aarch64-linux, x86_64-darwin, aarch64-darwin).
Update & CI: Keeps flake.lock in sync and checks CI/Docker matrices for full coverage.

Quick Start

Run the compatibility audit and platform tests:

./.claude/skills/cross-platform-guardian/scripts/audit-compatibility.sh
./.claude/skills/cross-platform-guardian/scripts/test-platform-compatibility.sh

Frequently Asked Questions about cross-platform-guardian

High-intent search queries and answers about installing and using this skill.

FAQPage Schema

How do I ensure my dotfiles work across macOS and Linux?▼

Cross-platform dotfiles require detecting hardcoded paths, platform-specific commands, and architecture mismatches, then validating across all target systems. This Skill audits your scripts, auto-fixes common issues, and tests your Nix flake across x86_64-linux, aarch64-linux, x86_64-darwin, and aarch64-darwin architectures using Docker and Nix.

What compatibility issues should I check for in my dotfiles?▼

Common issues include hardcoded paths, unguarded platform-specific commands, incorrect shebangs, non-standard XDG paths, and multi-architecture Nix flake definitions. Run the audit-compatibility.sh script to scan for these problems across macOS (Intel/ARM), Ubuntu, and Fedora.

Can I automate cross-platform testing for my dotfiles?▼

Yes. This Skill provides test-platform-compatibility.sh to validate your Nix flake across all four architectures automatically, and keeps flake.lock in sync. It also verifies CI/Docker matrices for complete platform coverage.

How do I fix hardcoded paths and platform assumptions in my scripts?▼

The auto-fix workflow corrects command usage, adds platform guards where needed, and standardizes XDG paths. After running the audit, apply safe fixes automatically, then re-validate with the platform test script to confirm behavior consistency.

Do I need Docker and Nix to test cross-platform dotfiles?▼

Yes. This Skill uses Nix flakes and Docker to test across all four architectures (x86_64-linux, aarch64-linux, x86_64-darwin, aarch64-darwin). You need both installed to run full validation workflows.

When should I run platform compatibility checks?▼

Run audits and tests when adding new scripts, updating flake.nix or flake.lock, investigating CI failures, or preparing changes for release. Regular checks catch compatibility drift early and prevent platform-specific regressions.