apple-device-integration
Apple Device Integration
PaulRBerg · Static checks on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add PaulRBerg/agent-skills --skill apple-device-integrationAbout this skill
compatibility: Requires macOS and Apple's Xcode MCP device-interaction tools. coordination: exempt name: apple-device-integration description: Use for device or simulator UI verification through Apple's Xcode MCP after UI changes or an explicit device check. Inspect screenshots and UI hierarchies, exercise controls, and report functional or visual defects.
Apple Device Integration
User instructions take precedence over this skill. Follow the target repository's build, fixture, privacy, device ownership, and cleanup rules. This skill is coordination-exempt: skip the ai-coord gate for its declared work. Its declared work is runtime verification and captured artifacts, without changes to tracked application source.
Forked from Apple's Xcode 27.2 (27B52) skill export, with local catalog metadata and MCP tool-name corrections.
TRIGGER when: user asks to verify/test/check if the app works on device, after implementing a UI-affecting feature that needs device verification, user says "does it work", "test this", "check on device", user reports UI doesn't work as expected, need to debug touch/interaction issues. DO NOT TRIGGER when: user asks about unit tests only, build-only requests without device testing, code review without device testing, simulator configuration questions, changes that don't affect UI (e.g. comments, refactors, non-UI logic).
Verification Scope
For a small check, verify the changed flow directly in the parent session. Delegate only when an independent or long verification task benefits from a separate verifier, or when the user asks for delegation.
Check the changed flow and its affected states. Use one representative task-owned simulator by default, or the specific device named in the request. Add device variants only when a concrete risk or user or release requirement calls for them.
Keep one controller per device at a time. When you delegate, the parent owns session creation, installation, and cleanup. Give the verifier exclusive use of that session and pass the workspace identifier when applicable, exact device UUID, simulator flag, session key, requested checks, and repository constraints. Include these interaction instructions in its brief before input. The verifier must not change application source, commit, or broaden the authorized device actions.
Verify the session's returned UUID and simulator flag before input. Physical-device installation and live-service actions require task authorization. Use fixture launch arguments when the repository provides them, and preserve unrelated devices, sessions, and workspaces.
Verify after a coherent change, not after each edit. Repeat the selected checks after further relevant code changes or observed failures. Stop when the selected checks pass.
Session Lifecycle
Use the target repository's build and install driver first. Follow its runtime and device ownership rules.
If the repository already built, installed, and launched the app, start a standalone session with
DeviceInteractionStartSession and use the exact task-owned device UUID. Do not rebuild through
DeviceInteractionInstallAndRun when the app is already running and unchanged.
If the repository uses Apple's MCP to build and install, start a workspace session and use
DeviceInteractionInstallAndRun for the initial build and launch. Reuse the running app for interaction checks when its
code has not changed. Use DeviceInteractionSynthesize to interact and observe, then end the session when done.
Preflight the live tool catalog for the capabilities this task needs. Require workspace tools only when the selected repository workflow needs them.
There are two ways to start a session:
- DeviceInteractionStartWorkspaceSession — bound to a workspace. Required for DeviceInteractionInstallAndRun. Use this when the repository workflow uses Apple's MCP to build and install the app.
- DeviceInteractionStartSession — not bound to any workspace. Use this for an already-installed app, including one built and launched by the repository's own driver.
DeviceInteraction(Workspace)StartSession tools
Device Discovery
When opening a new device interaction session, pass a device identifier to select a device, or omit it to use the current destination. Pass an empty string to get a list of available targets.
DeviceInteractionInstallAndRun tool
Optional Parameters
commandLineArguments— arguments passed to the app at launch. Use$(inherited)as a token to preserve the scheme's existing arguments (e.g.["$(inherited)", "--reset-state"]to add an extra argument at the end).environmentVariables— key/value pairs set in the app's environment at launch. Use"$(inherited)"as a key to preserve the scheme's existing environment variables (e.g.{"$(inherited)": "", "DEBUG_MODE": "1"}).
Omit both parameters to leave the scheme's arguments and environment unchanged.
Prefer these parameters over editing the scheme directly. They are applied only for that one run and have no lasting effect on the user's configuration.
For the Verifier
ALWAYS report UI issues that might be caused by code: overlapping or unreadable text, unexpectedly cropped image/text, wrong colors etc.
DeviceInteractionSynthesize tool
This tool allows performing an interaction and observing the state of a device.
Reading Hierarchy Files
The hierarchy files include calculated hitPoint positions for each element:
UIView {{100, 200}, {60, 30}}, hitPoint: {130.0, 215.0}
UIButton "Login" {{110, 205}, {30, 20}}, hitPoint: {125.0, 215.0}
UIButton "Login2" {{140, 205}, {20, 20}}, hitPoint: {150.0, 215.0}, activationBundleId: com.your.app
{100, 200}- origin position{50, 30}- width and heighthitPoint: {125.0, 215.0}- calculated hitPoint point (best for tapping)
Always prefer the hitPoint coordinates for touch events. Only after tapping a hitPoint and confirming (via recapture) it had no ef
Read the complete source ↗