Guide · Agent skill
How to use the Xcode Fleet Sync agent skill (xcode-sync)
Updated · written with AI from the project's own documentation and checked against our catalogue data
The xcode-sync skill is an agent skill that teaches an AI agent a careful routine for installing the same Xcode build on several Macs. It checks each downloaded Xcode archive's Apple signature and build number, installs it into fixed /Applications slots, and runs a command-line smoke test before old copies are discarded. This guide explains what the skill does, how to install it, how to ask for it, and what it needs before you let an agent run it.
Xcode Fleet Syncsteipete/agent-scripts · MIT Download the skill Quick start
- 1Download and unzip the skill. Download the ZIP from this page and unzip it so you have an xcode-sync folder containing SKILL.md and scripts.
- 2Place the folder. Move the xcode-sync folder into ~/.claude/skills/ for personal use, or into a project's .claude/skills/ folder. You can also upload it in the Claude apps under Settings → Capabilities → Skills.
- 3Prepare your fleet inventory. Make sure ~/Projects/manager/computers.yaml exists and lists your Macs, and that the companion $remote-mac skill is available.
- 4Confirm prerequisites. Check that Xcode .xip archives are downloaded locally, SSH and Tailscale work, and GNU timeout or gtimeout is installed.
- 5Ask for a read-only check. Request an inventory and simulator audit first so you can see which Macs are reachable and what state they are in.
- 6Approve the install. Review the plan the agent proposes, including host list, Xcode build and the /Applications slot, before approving writes or sudo use.
- 7Verify after install. Confirm the smoke gate passed and the agent reports each host's build, and that rollback copies were removed only after success.
What is an agent skill?
An agent skill is a folder containing a SKILL.md file and optional scripts that an AI agent loads when a task matches the skill's description. The SKILL.md file holds the instructions the agent follows, and the scripts do the checks and changes it describes.
The xcode-sync skill is one of these folders. Its SKILL.md file describes the full procedure, and it includes helper scripts in a scripts/ folder.
What the skill makes the agent do
The skill synchronizes exact Xcode builds across a fleet of Macs. The agent first inventories which machines are reachable, excluding handed-off and unknown hosts, and verifies each host's hostname, user, macOS version, architecture and hardware UUID before writing anything.
For each Xcode archive, the agent checks the Apple Software signature and compares the ProductBuildVersion, not just the version label. It then transfers the signed archive to each Mac, verifies its SHA-256 and signature, expands it there, and installs it into fixed slots: /Applications/Xcode.app for current stable, /Applications/Xcode-beta.app for the newest prerelease, and /Applications/Xcode-previous.app for the previous major stable for a limited window.
Before discarding an old copy, the agent runs a CLI smoke gate. If the new app fails, the helper restores the rollback copy where a selected path is involved.
The skill also audits unused iOS simulator runtimes. It removes only items Apple's CoreSimulator reports as outdated or unusable, and it refuses repairs while a simulator is booted.
Install the xcode-sync skill
Download the ZIP from this page and unzip it. Then place the xcode-sync folder in one of these locations, depending on whether you want it for all projects or one project:
For a personal setup, put it in ~/.claude/skills/. For a single project, put it in that project's .claude/skills/ folder.
Alternatively, in the Claude apps, open Settings, go to Capabilities, and upload the skill under Skills.
- Personal: ~/.claude/skills/xcode-sync/
- Project: .claude/skills/xcode-sync/ inside your project
- Claude apps: Settings → Capabilities → Skills
Check the requirements before you start
The skill assumes a specific setup. Confirm you have these before asking an agent to run it.
- macOS hosts with Xcode .xip archives downloaded locally
- SSH access to the fleet Macs and Tailscale for live reachability
- A local computers.yaml inventory file at ~/Projects/manager/
- GNU timeout or gtimeout (from coreutils)
- Passwordless sudo -n, or admin approval, for writes to /Applications when the folder is not writable
- The companion skill $remote-mac for fleet topology and SSH rules
How to trigger the skill with natural requests
You do not need a special command. Describe the outcome you want in plain language and mention Xcode and your Macs. The agent matches the request to the skill's description.
Good requests name the fleet, the Xcode version and what you want checked. For example, you can ask the agent to make every Mac in your fleet match a specific Xcode build, or to check which hosts are out of sync before changing anything.
If you only want a report, say so. The skill's inventory and audit steps can run without changes, and you can ask for those alone.
- "Check which of my Macs are reachable and what Xcode build each one has."
- "Install the Xcode .xip I downloaded on the three developer Macs, matching the build number."
- "Run the simulator hygiene audit on all fleet Macs and report drift, but don't repair anything yet."
- "Verify the signature and build number of this Xcode archive before transferring it."
Safety notes: scripts and network access
This skill runs scripts and uses the network. The procedure runs helper scripts, connects to other Macs over SSH, may delete apps and simulator runtimes, and may use sudo to write to /Applications. Read the SKILL.md file before you approve a run, and confirm the host list yourself.
The skill is designed to be cautious. It treats unreachable hosts as pending rather than synchronized, never changes a host's macOS version to make an Xcode build eligible unless you explicitly ask, and never changes xcode-select without a request. It also does not use age-based simulator deletion or the all option for routine maintenance.
Do not run this skill in an environment where agents must not run shell commands or touch /Applications.
Tips for reliable runs
Keep the Xcode archives you plan to install downloaded locally. The skill transfers the signed archive rather than an expanded app, and it does not redownload archives.
Run the inventory and simulator audit first, read the results, and then approve any repair step. Repairs are only run after the agent has verified the host identity and confirmed no current Xcode work depends on the simulator state.
If a broken Xcode-beta is selected and Git or Python hangs at startup, the SKILL.md file describes a diagnostic and a workaround using DEVELOPER_DIR. Follow those instructions in the affected session rather than changing xcode-select.
What people use it for
- Keeping the same Xcode build on a developer's laptop and a Mac mini used for builds.
- Rolling a small team's Macs forward to a new stable Xcode while keeping the previous major for a limited time.
- Auditing simulator runtimes across a fleet and removing only the ones Apple's CoreSimulator marks as outdated or unusable.
- Checking an Xcode archive's signature and ProductBuildVersion before copying it to other Macs.
Frequently asked questions
Is the xcode-sync skill free?
The skill is published under the MIT licence, as listed on this page. The source does not mention pricing, so check the repository for any terms that apply to you.
What do I need to use xcode-sync?
You need macOS hosts with Xcode .xip archives downloaded locally, SSH access to the Macs, Tailscale for reachability, a computers.yaml inventory at ~/Projects/manager/, GNU timeout or gtimeout, and the companion $remote-mac skill. Writes to /Applications may need passwordless sudo or admin approval.
Can I use this skill for a single Mac?
It is not designed for that. If you only want to install Xcode on one Mac, the skill's fleet procedure is heavier than you need, and it assumes SSH, Tailscale and a fleet layout.
Where do I install the skill folder?
Place it in ~/.claude/skills/ for personal use or in a project's .claude/skills/ folder. In the Claude apps, you can upload it under Settings → Capabilities → Skills.
Does the skill delete things on my Mac?
It can. The procedure may delete old Xcode copies after a successful smoke test and removes simulator runtimes that Apple's tools mark as outdated or unusable. It refuses simulator repairs while a device is booted.
How does xcode-sync compare with installing Xcode from the App Store?
The App Store route installs one copy on one Mac. xcode-sync checks signatures and build numbers and installs matching builds across several Macs with rollback steps. For a single machine, the App Store is the simpler choice.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use xcode-sync if you maintain several Macs and need matching Xcode builds with checks and rollback. Pick something simpler if you run a single Mac, or if your agent environment must not run shell commands or touch /Applications.
Download the skill