Xcode Coding Intelligence Workflow

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
   • classify the requested MCP tool as workspace-independent, headless-project, or live-Xcode before deciding whether an app or project must be open
   • on Xcode 27 Beta 5, use xcrun mcp-server status to inspect headless mode; use start, open, or stop only when the user requested that lifecycle change and the selected toolchain provides the command
   • verify external-agent access is enabled before configuring an external MCP client
   • use xcrun mcpbridge as the Xcode-provided STDIO bridge for external MCP clients
   • use xcrun mcpbridge run-agent <agent-name> only when intentionally launching a coding agent with Xcode-provided configuration
   • use Xcode Settings > Intelligence > Plug-ins for official plug-in import checks
   • use Xcode Settings > Intelligence > Add an Agent for a documented ACP-compatible agent; validate the agent command separately before changing Xcode state
   • use MCP_XCODE_PID when multiple Xcode processes make auto-detection ambiguous
   • discover the live Xcode MCP tool inventory before naming a beta-era tool; Apple documents capability groups but does not make a stable tool-name contract part of this skill
   • use xcodebuild and xccov for code coverage unless a live Xcode MCP session exposes and documents an equivalent coverage contract
   • keep normal Codex config separate from Xcode-launched Codex config
5. Plan command and tool permissions:
   • separate global headless enablement, agent-executable approval, folder-tree approval, and individual Xcode tool permissions
   • identify the executable Xcode is authorizing; a Python, shell, package manager, or other wrapper may become the recorded identity instead of the intended agent
   • prefer code-signed agent executables for durable grants and use the shortest practical duration for ad hoc or unsigned diagnostic clients
   • identify which agent is allowed to read files, modify source, edit project settings, build, run tests, render previews, inspect devices, or search documentation
   • prefer plan-first work for architecture-sensitive or beta-sensitive changes
   • keep generated files, diffs, previews, screenshots, and other artifacts reviewable before committing
   • do not grant broad write or shell permissions just to fix setup uncertainty
6. Hand off execution:
   • build, run, preview, file membership, and project-integrity work goes to xcode-build-run-workflow
   • Swift Testing, XCTest, XCUITest, and .xctestplan work goes to xcode-testing-workflow
   • durable String Catalog implementation, translation review, and locale validation go to xcode-localization-workflow
   • docs lookup goes to explore-apple-swift-docs
   • repo guidance alignment goes to bootstrap-xcode-workspace --operation align
   • cross-client ACP diagnosis goes to agent-portability-skills:operate-acp-agent-integration
   • ACP agent implementation goes to agent-portability-skills:build-acp-agent
7. Report:
   • Xcode version or beta target checked
   • Apple docs or local Xcode tool output relied on
   • selected agent surface
   • setup state and permission boundary
   • external-agent command shape when relevant
   • handoff skill for the next executable step

Inputs

• request: optional free-text setup or workflow request.
• xcode_version: optional target such as 26.5, 27 beta, or installed.
• agent_surface: optional explicit surface such as xcode-hosted, acp-hosted, external-mcp, chat-provider, plugin, or unknown.
• agent_name: optional agent name when launching through Xcode, such as codex or claude.
• permission_focus: optional emphasis such as read-only, source-edits, project-settings, build, test, preview, device, or shell.
• Defaults:
  • docs-first guidance always applies
  • beta-specific claims require a checked date
  • setup and permissions stay here
  • execution and validation hand off to existing Xcode execution skills

Outputs

• status
  • success: the setup or workflow recommendation is ready
  • handoff: the request belongs to another Apple Dev skill after coding-intelligence classification
  • blocked: docs, local Xcode capability checks, permissions, or missing project context prevent a safe recommendation
• path_type
  • primary: the recommendation uses documented Xcode coding-intelligence or xcrun mcpbridge behavior
  • fallback: the recommendation is limited to local Xcode inspection because Apple docs are JavaScript-gated or incomplete
• output
  • resolved agent surface
  • documented behavior relied on
  • beta or stable status and date checked
  • setup prerequisites
  • permission boundary
  • command shape when relevant
  • recommended handoff skill

Guards and Stop Conditions

• Do not claim Xcode 27 beta behavior is stable Xcode behavior.
• Do not use mcp-server enable --unsafe-always-allow-all-agents for ordinary at-desk use. Apple scopes it to unattended environments, and it removes the per-agent approval boundary.
• Do not treat Xcode-generated or Xcode-copied plug-in files as Socket source of truth unless the user explicitly asks to compare or import them.
• Do not claim a particular ACP agent works in Xcode merely because Xcode supports ACP; validate the executable, authentication, negotiated capabilities, and Xcode client behavior separately.
• Do not collapse Xcode-hosted agents and external MCP clients into one vague "agent"; name which process owns the UI, config, context, permissions, and execution.
• Do not mutate normal Codex config, Xcode-launched agent config, shell rc files, keychains, or provider credentials without explicit user intent.
• Do not set DEVELOPER_DIR unless it is genuinely the only viable path and Gale has explicitly approved that exception after hearing why xcode-select cannot serve the task.
• Do not store provider API keys in repo files or app binaries.
• Stop with blocked when no relevant Apple documentation or local Xcode evidence can be found for a requested setup claim.
• If Xcode is not running, first inspect whether the selected toolchain and permission state support headless MCP. Open the intended Xcode app only when the requested tool needs live editor/run/debug state, settings UI, plug-in UI, or project context that was not opened headlessly. Stop with blocked only when neither the headless nor live path can provide the required state.

Fallbacks and Handoffs

• Recommend explore-apple-swift-docs when current Apple docs need to be gathered before setup can be trusted.
• Recommend xcode-build-run-workflow when the next step is Xcode build, run, preview, file membership, target membership, or project-integrity work.
• Recommend xcode-testing-workflow when the next step is Swift Testing, XCTest, XCUITest, .xctestplan, or test diagnosis.
• Recommend bootstrap-xcode-workspace --operation align when the target product workspace needs durable Apple/Xcode guidance alignment.
• Recommend references/snippets/apple-xcode-project-core.md when the user needs reusable Xcode project guidance in a repo that will rely on Xcode coding intelligence.
• Keep custom Xcode plug-in writers research-first until the live package, runtime behavior, and permission surface are verified. Route ACP-agent implementation to Agent Portability Skills.

Fixed Policy

Keep this skill focused on setup and permission decisions. If future iterations add deterministic checks for Xcode settings exports, agent config folders, or MCP bridge status, document the knobs before runtime behavior depends on them.

References

Workflow References

• references/setup-and-agent-surfaces.md
• references/mcpbridge-and-external-agents.md
• references/permissions-and-artifacts.md
• references/source-evidence.md

Support References

• Recommend explore-apple-swift-docs when the user needs current Apple docs before an Xcode coding-intelligence setup claim.
• Recommend xcode-build-run-workflow when the next step is build, run, preview, project membership, or project-integrity follow-through.
• Recommend xcode-testing-workflow when the next step is test generation, execution, .xctestplan, or failure diagnosis.
• Recommend bootstrap-xcode-workspace --operation align when repo-local Apple workspace guidance needs updating.
• Recommend references/snippets/apple-xcode-project-core.md when the user needs reusable Xcode project guidance for a repo that will use Xcode coding intelligence.

Script Inventory