iOS Simulator Skill: a cloned repository silently fails to load, and on Xcode 27 an old companion reports success while dropping every tap

Cloning the repository whole leaves the skill three levels too deep

The manual install section opens with the rule a loader actually follows: a skill is read from a file at the root of its own directory, so it has to land directly inside the skills directory. Then it explains why the obvious thing fails. This repository is a plugin, not a skill, and the skill itself lives inside it, under a directory named after the project, then a skills directory, then the skill directory. Cloning the whole repository into your skills folder therefore puts that file three levels below where the loader looks, and the outcome is silence: no error, no skill, just a feature that never appears. The documented workarounds are all explicit about the path. From a release, a zip is downloaded and unpacked into the target directory:

curl -L https://github.com/conorluddy/ios-simulator-skill/releases/latest/download/ios-simulator-skill.zip -o skill.zip
unzip skill.zip -d ~/.claude/skills/ios-simulator-skill

From a clone, the nested directory is copied rather than cloned. And the same destination works at project scope, which is the one to use if you do not want the scripts available everywhere.

Four install routes, one of them inside the tool itself

The recommended route is not a package manager at all, it is two slash commands typed into Claude Code, one to add the plugin marketplace and one to install the skill from it. The other three are manual. A release zip, as quoted above. A clone, where the repository goes to a source directory and the nested skill directory is copied to the destination. And a project-local install, which differs only in the destination path. All four converge on the same requirement, which the documentation states after them: restart the tool afterwards, and check that the skill file exists at the expected place. That last instruction is the useful one, because the failure mode in this project is a silent no-op rather than an error message, so a verification step is not ceremony. It also means a fresh machine is verified by listing one file, which takes less time than debugging a missing capability later.

idb left Homebrew core, and a stale copy on the path decides which one runs

The simulator interaction scripts need a companion tool, and how you install it changed recently enough that the documentation leads with a warning. The command that used to work no longer does, because the companion package was removed from Homebrew core and now lives in Meta's own tap:

brew tap facebook/fb
brew install facebook/fb/idb-companion facebook/fb/idb-cli

There is a second path and it is explicitly second class. The old pip package still installs a working command, but the documentation says the Homebrew route is the maintained one. And then it names the trap: if both are installed, whichever comes first on the path wins, with a command to inspect every candidate. That is the whole reason the check exists, because a working pip install sitting in front of an outdated brew one produces behaviour that belongs to the wrong binary, and nothing in either tool's output says so.

On Xcode 27 an old companion reports success and does nothing

This is the single most important paragraph in the file. Under Xcode 27, the companion must be at least a specific version, and the reason is a moved framework: older builds look for a framework where the previous Xcode kept it. The failure that results is not an error. The companion still starts, the accessibility tree still reads correctly, and every tap, swipe and keystroke is silently dropped, with the tool reporting success while nothing happens on screen. The upgrade and verification are two commands:

brew upgrade facebook/fb/idb-companion facebook/fb/idb-cli
brew list --versions idb-companion        # expect >= 1.5.1

The release that added this is version 1.5.0, and its title is the compatibility statement rather than a feature list, which tells you how the project prioritises. For anyone automating a simulator, this is the difference between a suite that appears to work and one that works, and it is invisible unless you know to look.

Xcode 27 removed the application you are told to open

Three notes cover the vendor changes that break habits rather than code. First, there is no longer an application with the old name. Xcode 27 replaced it with a different application, living inside the Xcode bundle rather than in the applications folder, and the documentation says scripts drive simulators headlessly so you rarely need either one, while opening the old name will fail. Second, quitting that application shuts down the simulator it is hosting, which turns a routine tidy-up into an interrupted test run. Third, the health check script exists because of a specific failure mode: if calls start failing with a connection refused error after a crash or a manual kill, a dead companion is still registered, and it is cleared by disconnecting it by device identifier, which the health check detects for you. That is a documented stale-state bug in the underlying tooling, with a documented remedy.

The design goal is measured in tokens

The reason this project exists is stated as cost. Navigation is done through accessibility APIs rather than pixel coordinates, and the file gives the comparison: an element query costs about ten tokens in default output, against one thousand six hundred to six thousand three hundred tokens for a screenshot of the same screen. It shows both forms side by side, the coordinate tap and the find by text:

python scripts/navigator.py --find-text "Login" --tap

Builds follow the same discipline. The build wrapper returns one summary line carrying an xcresult identifier, and the detail is pulled on demand through separate flags for errors, warnings and the log. The savings table is specific: screen analysis from over two hundred lines to five, finding and tapping a button from over a hundred to one, a login flow from over four hundred to fifteen. Screenshots, when they are genuinely needed, are resized and compressed automatically, and the claimed default across all 29 scripts is three to five lines. Treat the percentages as claims about default output rather than measurements, but the direction is right and the design is deliberate.

Every script takes the same two flags, and linting skips the root

Twenty nine scripts, and the contract is stated once: each one supports a help flag and a machine readable output flag. That uniformity is what makes the suite usable by an agent, because the calling convention never changes between a build script, a device state script and a navigation script. The build group has two entries, the device state group two, and the navigation group begins with a screen mapper whose key flag column is cut off partway through a second flag, so the reference in this file is incomplete and the complete version lives in the skill's own reference file. The static analysis configuration is narrower than the repository. The linter is configured to include only the scripts inside the skill directory, with a comment saying it checks skill code and not the root level development scripts, and the formatter is configured for a specific language target and line length. So the code the users run is strictly checked, and the tooling around it is not.

Editorial conclusion

This skill fits a team building iOS apps on macOS that wants an agent to run builds and drive a simulator without screenshot archaeology. It does not fit a cross-platform team, since the prerequisites begin at a specific macOS version and a specific Xcode version and go up from there. Four things to check before you install it. Where the skill directory goes, because the repository is a plugin rather than a skill and cloning it whole puts the definition three levels too deep for anything to find. Which Xcode you are on and which companion build goes with it, because the mismatch produces a false success rather than an error. Where idb came from, because the package you are likely to have installed by habit is no longer in Homebrew core and a second copy on the path decides which one runs. And what the numbers mean, because the token reductions in this file are claims about the scripts' own default output compared against unspecified raw tool output, and the honest way to judge them is to run the health check and one navigation command on your own project.

Frequently asked questions

Official sources

1. conorluddy/ios-simulator-skill on GitHub
2. License: MIT
3. Project website
4. README
5. Releases