Cross-Platform Sync

Ensures agent instruction files are synchronized across GitHub Copilot, OpenAI Codex, Windsurf, Claude Code, and Manus.

When to Use This Skill

•Setting up a new repository for multi-agent development
•Auditing existing agent configuration files
•Debugging inconsistent agent behavior across platforms
•After modifying AGENTS.md or any agent instruction file

Canonical Structure

code

repo-root/
├── AGENTS.md                      # Canonical source (all platforms)
├── CLAUDE.md                      # Symlink → AGENTS.md
├── .github/
│   ├── copilot-instructions.md    # Symlink → ../AGENTS.md
│   └── instructions/              # Path-specific Copilot rules
│       └── *.instructions.md
├── .claude/
│   └── CLAUDE.md                  # Symlink → ../AGENTS.md
├── .codex/
│   ├── AGENTS.md                  # Symlink → ../AGENTS.md
│   └── skills/                    # Symlink → ../skills/
└── skills/                        # Canonical skills location
    └── <skill-name>/
        └── SKILL.md

Validation Steps

Step 1: Check Symlinks Exist

bash

ls -la AGENTS.md CLAUDE.md .github/copilot-instructions.md .codex/AGENTS.md .claude/CLAUDE.md 2>/dev/null

Expected output shows symlinks pointing to AGENTS.md:

code

lrwxrwxrwx CLAUDE.md -> AGENTS.md
lrwxrwxrwx .github/copilot-instructions.md -> ../AGENTS.md
lrwxrwxrwx .codex/AGENTS.md -> ../AGENTS.md
lrwxrwxrwx .claude/CLAUDE.md -> ../AGENTS.md

Step 2: Verify Symlinks Resolve

bash

# All should show identical content
head -5 AGENTS.md
head -5 CLAUDE.md
head -5 .github/copilot-instructions.md

Step 3: Check Skills Symlink

bash

ls -la .codex/skills
# Should show: .codex/skills -> ../skills

Step 4: Validate No Duplicate Content

bash

# These should fail (files should be symlinks, not copies)
diff AGENTS.md CLAUDE.md 2>/dev/null && echo "WARNING: CLAUDE.md is a copy, not symlink"

Setup Commands

Create Symlinks (New Repo)

bash

# Create AGENTS.md as canonical source first
# Then create symlinks

ln -sf AGENTS.md CLAUDE.md
mkdir -p .github .claude .codex
ln -sf ../AGENTS.md .github/copilot-instructions.md
ln -sf ../AGENTS.md .claude/CLAUDE.md
ln -sf ../AGENTS.md .codex/AGENTS.md
ln -sf ../skills .codex/skills

Fix Broken Symlinks

bash

# Remove existing files and recreate symlinks
rm -f CLAUDE.md .github/copilot-instructions.md .codex/AGENTS.md .claude/CLAUDE.md
ln -s AGENTS.md CLAUDE.md
ln -s ../AGENTS.md .github/copilot-instructions.md
ln -s ../AGENTS.md .codex/AGENTS.md
ln -s ../AGENTS.md .claude/CLAUDE.md

Platform-Specific Notes

Platform	File	Notes
GitHub Copilot	`.github/copilot-instructions.md`	Also reads `AGENTS.md` at root
OpenAI Codex	`.codex/AGENTS.md`	Hierarchical discovery
Windsurf	`AGENTS.md`	Case-insensitive
Claude Code	`CLAUDE.md` or `.claude/CLAUDE.md`	Supports `@import` syntax
Manus	`skills/*/SKILL.md`	Skills directory

Troubleshooting

Symlink Not Working on Windows

Windows requires admin privileges for symlinks. Use junction points or copy files instead:

bash

# sync-instructions.bat
copy AGENTS.md CLAUDE.md
copy AGENTS.md .github\copilot-instructions.md

Agent Not Reading Instructions

•Check file exists and is readable
•Verify symlink resolves correctly
•Check for syntax errors in YAML frontmatter
•Ensure file is committed to git (not gitignored)

Different Agents Behave Differently

•Run validation steps above
•Check if any file is a copy instead of symlink
•Verify all symlinks point to same canonical source
•Check for platform-specific overrides in subdirectories