Moving AI Coding Agent Rules and Skills Across macOS, Linux, and Windows

Why Does Moving AI Coding Agent Skills Across macOS, Linux, and Windows Break?

Moving AI coding agent skills across macOS, Linux, and Windows breaks because each operating system imposes fundamentally conflicting assumptions regarding text line endings, path separators, file permissions, and symbolic link dereferencing. When developers copy instruction files across OS boundaries, these low-level filesystem discrepancies cause YAML frontmatter parsing failures, broken script executions, and silent rule misfires in tools like Anthropic Claude Code, Cursor, and OpenAI Codex.

Engineers who author AI agent skills on a MacBook Pro often assume their instructions will execute identically when checked out on an Ubuntu CI server, a remote Linux devbox, or a Windows 11 workstation. In practice, four structural failure modes emerge immediately upon crossing operating system boundaries:

• Carriage Return Line Feed (CRLF) Corruption: Windows text editors and Git checkouts insert a two-byte carriage return and line feed sequence (0x0D 0x0A or \r\n) instead of the POSIX standard single-byte line feed (0x0A or \n). When an AI agent runtime parses a SKILL.md or .cursor/rules/*.mdc file containing CRLF endings, strict YAML parsers fail to parse frontmatter boundaries, while embedded bash scripts fail with the infamous /usr/bin/env: 'bash\r': No such file or directory error.
• Path Separator and Directory Variable Divergence: POSIX runtimes utilize forward slashes (/) and reference $HOME, whereas native Windows environments rely on backslashes (\) and environment variables like %USERPROFILE% and %APPDATA%. Hardcoded paths inside skill templates fail instantly when invoked on another OS.
• Symbolic Link Dereferencing Failures: On macOS and Linux, developers frequently symlink a central skill directory into local project repositories using ln -s. On Windows, creating symbolic links requires elevated administrative privileges or Windows Developer Mode. Without these, Git checks out symbolic links as static 40-byte text files containing raw relative paths, leaving AI agents unable to traverse to the actual skill instructions.
• POSIX Executable Permission Stripping: Multi-file skills often bundle executable scripts (such as test runners, linters, or deployment validators) marked with chmod +x (octal 755). Windows filesystems (NTFS) do not preserve POSIX file mode bits. When files are checked out or shared across Windows and Linux Subsystem (WSL), the executable bit is frequently stripped to 644, triggering EACCES: permission denied errors during agent tool calls.

Cross-platform portability requires treating AI agent skills as compiled, environment-agnostic assets rather than fragile local shell scripts. Without automated normalization, engineers lose hours debugging agent hallucination and execution timeouts that stem entirely from underlying filesystem formatting errors.

Where Do Coding Agents Store Skills on macOS, Linux, and Windows?

Coding assistants store their personal and repository-scoped skills in distinct filesystem locations that vary significantly across macOS, Linux distributions, native Windows, and Windows Subsystem for Linux (WSL 2). Understanding these exact configuration paths is essential to mapping and synchronizing agent instructions without creating redundant or conflicting directories.

While macOS and Linux adhere closely to the XDG Base Directory Specification or user home defaults, native Windows distributes configuration files across %USERPROFILE% and %APPDATA%, while WSL 2 introduces an additional translation layer under /mnt/c/.

According to the official Anthropic Claude Code documentation, global skills reside in ~/.claude/skills/ while project-specific skills must be placed in .claude/skills/ within the current repository root. When running on native Windows via PowerShell, Claude Code resolves the user home directory to C:\Users\<username>\.claude\skills\. However, if the developer executes Claude Code inside a WSL 2 terminal, the runtime accesses /home/<user>/.claude/skills/ on the virtualized Linux filesystem.

This duality creates immediate drift: editing a skill in Cursor on Windows does not automatically update Claude Code executing inside WSL unless an explicit bridge or centralized synchronization tool is active.

How Do Line Endings and Git Configuration Break Cross-Platform AI Rules?

Line endings break cross-platform AI agent rules because Windows environments default to two-byte CRLF line terminators (\r\n), whereas AI agent runtimes and YAML frontmatter parsers expect single-byte LF line terminators (\n). When Git or local editors introduce invisible carriage returns into Markdown instructions, the agent model receives corrupted prompt tokens and tool execution commands fail.

The impact of line ending corruption manifests in three distinct technical failure points:

1. YAML Frontmatter Delimiter Failure: SKILL.md and modern Cursor .cursor/rules/*.mdc files rely on three hyphens (---) to delimit YAML metadata from Markdown instruction bodies. When a file is saved with CRLF line endings, the delimiter byte sequence becomes 2D 2D 2D 0D 0A. Strict YAML 1.2 parsers frequently fail to recognize the closing delimiter, treating the entire instruction payload as invalid YAML frontmatter and failing to load the skill altogether.
2. Bash Script Interpreter Rejection: When an AI skill includes an executable script containing a shebang such as #!/usr/bin/env bash, a CRLF line ending causes the kernel to search for a binary named bash\r in the system $PATH. The execution immediately aborts with an exit code of 127 before the agent can inspect the failure.
3. UTF-8 Byte Order Mark (BOM) Ingestion: Windows PowerShell and legacy editors often save UTF-8 files with an unnecessary 3-byte Byte Order Mark (0xEF 0xBB 0xBF) at the beginning of the file. AI coding assistants parsing raw files ingest the BOM as non-printable whitespace, corrupting parameter schemas and prompt templates.

As documented in the official Git documentation on line endings and gitattributes:

"Git can handle this by auto-converting CRLF line endings into LF when you add a file to the index, and vice versa when it checks out code onto your filesystem."

However, when developers rely on default Git configurations with core.autocrlf = true on Windows, checking out files automatically injects CRLF into every Markdown and script file in the repository. To guarantee cross-platform immutability, engineering teams must commit an authoritative .gitattributes configuration at the root of their repositories.

How Can You Handle POSIX Symlinks vs Windows NTFS Junctions for Skills?

Handling POSIX symlinks and Windows NTFS junctions requires replacing raw relative file symlinks with directory junctions or absolute platform-specific link structures. While POSIX operating systems treat symbolic links as first-class filesystem primitives, Windows NTFS restricts symbolic link creation to privileged processes unless Developer Mode is explicitly enabled, making standard Git symlink repositories brittle.

When a repository contains a symbolic link connecting .cursor/rules/team-guidelines.mdc to a central skills folder, cloning that repository on a standard Windows 11 machine produces a 42-byte plain text file containing the string ../../shared-skills/team-guidelines.mdc rather than a functional pointer. When Cursor or Claude Code attempts to read the file, it receives the raw relative path string rather than the actual prompt instructions, silently disabling the rule during agent reasoning.

Microsoft provides detailed architectural specifications in the Microsoft Learn documentation on WSL file permissions and metadata. To resolve symlink divergence between macOS and Windows:

• NTFS Directory Junctions (mklink /J): On Windows, directory junctions allow linking local directories without requiring administrator privileges or Developer Mode. For example, linking a project rules directory to a central store can be executed via mklink /J .cursor\rules C:\Users\<user>\.central-rules. However, junctions function strictly for directories and cannot link individual .mdc files.
• Git Symlink Configuration (core.symlinks): Developers on Windows must enable Developer Mode under Windows Settings → System → For Developers and configure Git globally using git config --global core.symlinks true prior to cloning repositories containing agent instructions.
• WSL 2 DrvFS Path Translation Traps: When working inside WSL 2, accessing Windows drives via /mnt/c/ causes DrvFS to emulate Linux file permissions using NTFS metadata. Inode lookups on /mnt/c/ are up to 400% slower than native ext4 operations, causing agent tools scanning large skill libraries to hit execution timeouts. Always store active skill repositories within the native Linux root (~) rather than on mounted Windows drives.

Step-by-Step: Building an OS-Agnostic AI Skill Library

Building an OS-agnostic AI skill library requires establishing strict repository hygiene, automating line ending enforcement, normalizing path separators, and maintaining consistent execution permissions across macOS, Linux, and Windows. Follow this five-step engineering procedure to ensure your skills execute flawlessly on any machine.

Step 1: Enforce Strict LF Line Endings in .gitattributes

Create or update the .gitattributes file at the root of your repository or dotfiles repository to guarantee that all prompt, rule, and skill files are checked out with single-byte LF line endings regardless of the operating system:

# Enforce LF line endings for all AI agent instruction files
*.md text eol=lf
*.mdc text eol=lf
*.prompt text eol=lf
*.yaml text eol=lf
*.yml text eol=lf
*.json text eol=lf

# Shell scripts must strictly preserve LF for bash interpreters
*.sh text eol=lf
*.bash text eol=lf
*.py text eol=lf

# Windows PowerShell scripts
*.ps1 text eol=crlf

Step 2: Preserve POSIX Executable Permissions in Git Index

If your skill includes helper bash scripts or Node.js CLI tools, ensure the executable bit (755) is tracked explicitly in Git's index so it does not get stripped on Windows machines:

# Mark scripts as executable directly in the Git tree
git update-index --chmod=+x scripts/run-audit.sh
git update-index --chmod=+x scripts/verify-tokens.py
git commit -m "chore: enforce executable permissions on skill tools"

Step 3: Normalize Paths in Multi-File Skill Wrappers

When authoring multi-file skills that invoke external tools or read nested files, avoid hardcoded slashes or shell-specific path expansion. In Python or Node.js helper scripts, always utilize cross-platform path resolution libraries:

// Node.js cross-platform skill path resolver
import * as path from 'path';
import * as os from 'os';

export function resolveSkillPath(skillName: string): string {
    const homeDir = os.homedir();
    // Resolves correctly to /Users/<user>/.claude/skills on macOS,
    // /home/<user>/.claude/skills on Linux, and C:\Users\<user>\.claude\skills on Windows
    return path.join(homeDir, '.claude', 'skills', skillName, 'SKILL.md');
}

Step 4: Strip UTF-8 Byte Order Marks Automatically

Verify that no files contain the 3-byte UTF-8 BOM (EF BB BF) that crashes YAML 1.2 frontmatter parsers. On Linux and macOS, you can audit your entire skill library using a single command:

# Find and remove UTF-8 BOM from all Markdown files
find ~/.claude/skills -name "*.md" -type f -exec sed -i '1s/^\xEF\xBB\xBF//' {} +

Step 5: Configure Git Symlink and Line Ending Defaults Globally

On every machine you use for AI agent workflows, configure Git to respect cross-platform standards:

# On macOS and Linux:
git config --global core.autocrlf input

# On Windows (PowerShell with Admin / Developer Mode):
git config --global core.autocrlf false
git config --global core.symlinks true

The Sprawl Moment: The Broken Deploy Script on the Windows Workstation

You spend three hours on your MacBook Pro building an automated Kubernetes staging deployment skill for Claude Code. The skill coordinates a complex validation workflow: it parses a YAML manifest, runs a local bash verification script to check secret references, and validates container image digests before prompting for production rollout. The skill runs flawlessly in your local terminal. The following morning, an urgent customer outage occurs while you are working from your dedicated Windows 11 desktop. You pull the repository, launch Cursor with Composer, and invoke the deployment skill. Within ten seconds, the entire workflow crashes: the bash verification script aborts with \r: command not found, the YAML frontmatter fails to parse due to CRLF carriage return bytes, and the symlink to your shared microservice rules resolves as an unreadable 42-byte text file containing a dead relative path. While production alarms escalate, you are stuck in PowerShell running dos2unix utilities, reconfiguring Git symlink flags, and rebuilding NTFS junctions across two physical drives.

Eliminating Cross-Platform Skill Friction with Prompttly

Prompttly is a skill manager for AI agents — one library for your skills and prompts that syncs into Claude Code, Codex, ChatGPT, and Claude and is one hotkey away on your Mac, so your setup follows you across every machine, repo, and tool.

Instead of manually maintaining fragile .gitattributes files, debugging CRLF line endings, and configuring Windows Developer Mode symlinks across separate laptops and workstations, Prompttly abstracts away underlying filesystem differences:

• Automatic Line Ending Normalization: Prompttly automatically normalizes all skill and prompt definitions to clean, single-byte LF line endings. Whether you edit an instruction in a Windows browser or on an Ubuntu server, CRLF corruption is eliminated before files touch disk.
• Native Multi-OS Filesystem Compilation: Skills sync directly into real, native directory structures across macOS (~/.claude/skills), Linux (/home/user/.claude/skills), and Windows without relying on fragile symbolic links or DrvFS mounts.
• Sub-180ms Hotkey Palette on Mac: Press a global keyboard shortcut from anywhere in macOS to search your entire prompt library and insert instructions into any terminal emulator, IDE, or web browser.
• Full Model Context Protocol (MCP) Support: Connect any AI agent over standard MCP endpoints, allowing tools like Cursor and Codex CLI to fetch dynamic, versioned instructions without manual filesystem indexing.
• Free Developer Utility Suite: Generate structured, production-ready skills with the free Claude Skill Creator, build optimized chat preambles with the Custom Instructions Generator, or refine system directives using the Prompt Optimizer.

Frequently Asked Questions About Cross-Platform AI Agent Skills

Related Cross-Agent and Portability Resources

To explore advanced multi-machine synchronization architectures and agent rule engineering, explore our related technical resources:

• How to Sync Claude Skills Across Multiple Computers: Practical strategies for backing up and synchronizing Claude Code and Codex instructions across laptops and desktops.
• How to Sync Cursor Rules Across Machines Without Git Conflicts: Architecture for managing .cursor/rules/*.mdc files across multiple developer environments.
• One Reusable Skill Library Across Claude Code, Codex, Cursor, and Antigravity: Establishing a single synchronized source of truth across the top four coding agent runtimes.
• Multi-Agent Rules Architecture: AGENTS.md, .cursor/rules, and Claude Skills: Standardizing a three-tier rule hierarchy for production development teams.
• How to Build a Multi-Machine AI Skill Sync Pipeline Using MCP: Deep technical guide to building automated cross-machine sync over the Model Context Protocol.
• Browse the full directory on the Prompttly Resources Hub or get the native Mac app for system-wide hotkey access.