What is xcode-mcp-first-executor?

A skill that routes Apple and Swift tasks through Xcode MCP tools first and uses a structured fallback when MCP can’t satisfy the operation, with workspacePath-based tab resolution.

How does the fallback handoff work?

If MCP fails after the one retry, the skill emits a structured payload to apple-swift-cli-fallback including the intent category, preferred official CLI commands, and the reason MCP path failed.

Can I customize MCP behavior?

Yes. Use the Interactive Customization Flow to load the current config, answer knob-by-knob questions, map changes, and persist overrides that adjust MCP retry/handoff policies.

xcode-mcp-first-executor

npx machina-cli add skill gaelic-ghost/apple-dev-skills/xcode-mcp-first-executor --openclaw

Files (1)

SKILL.md

2.7 KB

Xcode MCP First Executor

Use this skill when a task can be performed through Xcode MCP.

Core Rules

Resolve target workspace by workspacePath from XcodeListWindows.
Do not trust stale tab index assumptions.
Use MCP tools first for supported actions.
If MCP fails after retry policy, output structured handoff to $apple-swift-cli-fallback.

Workflow

Resolve active tab:

call XcodeListWindows
pick tab by matching workspacePath

Execute via MCP matrix:

use references/mcp-tool-matrix.md

Retry on transient MCP failures:

one immediate retry for timeout or transport error
if still failing, generate fallback handoff payload

Handoff payload:

include intent category
include preferred official CLI command(s)
include reason MCP path failed

Mutation Note

For mutation requests in Xcode-managed scope, continue through MCP mutation tools if available. If falling back to direct filesystem edits, route to $apple-dev-safety-and-docs first.

References

references/mcp-tool-matrix.md
references/mcp-failure-handoff.md
references/mutation-via-mcp.md

Interactive Customization Flow

Load current effective customization settings first:

uv run python scripts/customization_config.py effective

Ask targeted customization questions:

Use references/customization-flow.md to drive knob-by-knob questions.
Confirm desired behavior changes and safety constraints.

Map requested changes to implementation files:

Update SKILL.md, references/*, and any runtime script files listed in references/customization-flow.md.

Persist durable customization state:

Start from customization.template.yaml defaults.
Apply approved overrides with uv run python scripts/customization_config.py apply --input <yaml-file>.
Durable path: ~/.config/gaelic-ghost/apple-dev-skills/<skill-name>/customization.yaml.
Optional override root: APPLE_DEV_SKILLS_CONFIG_HOME.

Report resulting effective configuration:

Re-run uv run python scripts/customization_config.py effective and summarize final active settings.
If the user asks to remove customization state, run uv run python scripts/customization_config.py reset.

Use references/customization-flow.md for skill-specific knobs, file mapping, guardrails, validation checks, and example requests.

Source

git clone https://github.com/gaelic-ghost/apple-dev-skills/blob/main/swift-xcode-tools/xcode-mcp-first-executor/SKILL.mdView on GitHub

Overview

Routes Apple and Swift tasks through the Xcode MCP pipeline first, resolving the correct Xcode tab via workspacePath and avoiding stale tab indices. When MCP is unavailable, times out, or cannot satisfy the operation, it falls back to a structured handoff. This is ideal for MCP-first execution routing or when you want to customize the MCP retry/handoff policy.

How This Skill Works

1) Resolve the active tab by matching workspacePath from XcodeListWindows. 2) Execute via the MCP matrix (references/mcp-tool-matrix.md). 3) On transient MCP failures, retry once; if it still fails, emit a structured handoff payload to the apple-swift-cli-fallback channel. For mutations, continue via MCP mutation tools if available; if direct edits are needed, route to $apple-dev-safety-and-docs first.

When to Use It

When you want Apple/Swift tasks routed through MCP first.
When you need strict workspacePath-based tab resolution to select the correct Xcode tab.
When MCP is unavailable or times out and a structured fallback is required.
When you want to customize MCP retry/hand-off behavior via the Interactive Customization Flow.
When handling mutation requests in Xcode scope and MCP mutation tools should be preferred.

Quick Start

Step 1: Resolve the active Xcode tab by matching workspacePath from XcodeListWindows.
Step 2: Execute the task via the MCP tool matrix (references/mcp-tool-matrix.md).
Step 3: If a transient MCP failure occurs, retry once; if still failing, emit a structured handoff to $apple-swift-cli-fallback.

Best Practices

Resolve the active tab deterministically using XcodeListWindows and workspacePath before MCP calls.
Prefer actions that are supported by the MCP tool matrix (references/mcp-tool-matrix.md).
Implement a single immediate retry for transient failures (timeout or transport error).
If MCP cannot satisfy after retry, generate a structured handoff payload to $apple-swift-cli-fallback with intent, preferred CLI commands, and reason.
For mutation requests, use MCP mutation tools first; if direct edits are needed, route through apple-dev-safety-and-docs.

Example Use Cases

Route a build task through MCP-first to leverage cached targets in a multi-target Swift project.
Open and edit a file in the correct Xcode tab by resolving workspacePath and MCP-tab selection.
Fetch module maps via MCP and gracefully fall back if MCP times out.
Add a new target to an Xcode project by routing through MCP-first mutation tools when possible.
When MCP cannot satisfy a request, send a structured handoff payload to apple-swift-cli-fallback for manual review.

Frequently Asked Questions

Add this skill to your agents