/xcode-coding-intelligence-workflow

name: xcode-coding-intelligence-workflow
description: Guide Xcode coding-intelligence setup, ACP-hosted agents, external-agent access through xcrun mcpbridge, permissions, Xcode-only agent configuration, and stable or beta agentic workflows.

Xcode Coding Intelligence Workflow

Purpose

Guide setup and reasoning for Xcode coding intelligence without taking over normal build, run, preview, or testing execution.

This skill owns Xcode Intelligence setup, Xcode-hosted ACP agents, chat providers, external-agent access through `xcrun mcpbridge`, Xcode 27 headless MCP service lifecycle, Xcode plug-in import inspection, command and tool permissions, Xcode-only agent configuration homes, and the boundary between Xcode's assistant UI and external agent sessions. It is the setup and permissions companion for `xcode-build-run-workflow` and `xcode-testing-workflow`.

Current note: Apple documents ACP agent setup in Xcode 26.6 and Xcode 27. Xcode 27-only behavior remains beta-specific unless the target machine's installed Xcode and current Apple docs confirm it.

When To Use

• Use this skill when the task is about Xcode Intelligence settings, coding assistants, Xcode-hosted agents, chat providers, model choice, agent conversations, plan mode, artifacts, or command and tool permissions.
• Use this skill when configuring external agents to use Xcode capabilities through `xcrun mcpbridge`.
• Use this skill when adding an ACP-compatible agent such as Hermes to Xcode's own agent UI.
• Use this skill when inspecting Xcode's Plug-ins UI import paths for skills, hooks, and MCP servers.
• Use this skill when the user needs to distinguish Xcode-hosted agents from normal Codex sessions that connect to Xcode through MCP.
• Use this skill when the task mentions Xcode-only agent configuration homes, Xcode-launched Codex, Claude, Gemini, ChatGPT in Xcode, or other chat-provider setup.
• Use this skill when Xcode agent workflows should be checked before a build, test, preview, localization, or Device Hub handoff.
• Recommend `xcode-build-run-workflow` when the next step is workspace inspection, build, run, preview, file membership, target membership, diagnostics, or guarded project mutation.
• Recommend `xcode-testing-workflow` when the next step is Swift Testing, XCTest, XCUITest, `.xctestplan`, test filtering, retries, or test diagnosis.
• Recommend `explore-apple-swift-docs` when the user primarily needs current Apple documentation lookup rather than setup and workflow planning.
• Recommend `bootstrap-xcode-workspace --operation align` when an existing Apple product workspace needs durable Xcode guidance alignment.
• Recommend `agent-portability-skills:operate-acp-agent-integration` for cross-client ACP launch and diagnosis.
• Recommend `agent-portability-skills:build-acp-agent` for implementing an ACP agent/server.
• Do not use this skill as the owner for implementing custom ACP agents, custom MCP servers, Xcode plug-in packages, or broad agent-configuration sync.

Single-Path Workflow

1. Classify the coding-intelligence request:

• Xcode Intelligence settings
• Xcode-hosted agent setup
• ACP agent setup through Xcode's Add an Agent flow
• chat provider or model-provider setup
• external-agent access through `xcrun mcpbridge`
• command, tool, approval, or permission policy
• Xcode-only agent configuration home
• Xcode 27 MCP capability discovery for run state, debugger, schemes, destinations, project settings, runtime insights, simulators, previews, or localization
• plan-mode, artifacts, diff-review, preview, build, or test handoff
• beta documentation or installed-Xcode capability check

2. Apply the Apple docs gate before making setup or behavior claims:

• read current Apple Xcode documentation, Xcode pages, WWDC transcripts, or local Xcode tool output first
• state the documented behavior being relied on and the date checked for beta-specific behavior
• if Apple docs and local Xcode behavior disagree, stop and report the conflict
• if no relevant Apple documentation can be found, say that explicitly before proceeding

3. Establish which agent surface is in play:

• Xcode-hosted agent: started inside Xcode, uses Xcode's assistant UI, Xcode's project context, Xcode's artifact review surfaces, and Xcode-managed tool permissions
• ACP-hosted agent: an external agent executable launched by Xcode as the ACP client; the agent owns its runtime/auth/config while Xcode owns the editor UI and Xcode-side permissions
• external agent through MCP: started outside Xcode and connected through

`xcrun mcpbridge`; it may use the Xcode 27 Beta 5 headless service when enabled, while editor/run/debug state still requires the matching live Xcode or headlessly opened project context

• chat provider: model or chat setup for Xcode coding intelligence that may not imply autonomous Xcode tool use
• ACP agent implementation: hand off to Agent Portability Skills while keeping Xcode client setup and permissions here

4. Plan setup:

• verify the target Xcode version and whether the relevant behavior is stable, beta, or local-only
• check whether the intended Xcode app is running and open it when needed for editor state, active run/debug state, agent settings, or UI/plugin inspection; do not require the app merely for a headless-capable documentation lookup
• use the Xcode CLI toolchain Gale selected through `xcode-select`; when a switch is needed, use the already-open Xcode app or open the intended app, then change Settings > Locations > Command Line Tools and let macOS obtain Touch ID or administrator approval; verify afterward with `xcode-select -p` and do not override with `DEVELOPER_DIR`
• open the intended beta app when the beta UI or live bridge state is required
• do not invoke terminal `xcode-select --switch` as the default path; preserve the GUI-selected toolchain and restore only when Gale asked for a temporary switch
• class