What is MCP-first policy?

Prioritize Apple’s Xcode MCP for supported actions and fallback to official CLI tools when MCP is unavailable.

How does mutation safety work?

If a request could modify Xcode-managed scope, a hard 2-step consent gate is required before any direct filesystem mutation.

How do I customize the policy?

Use the interactive customization flow: check the effective config, answer knob questions, map changes to files, and persist with customization_config.py.

apple-xcode-hybrid-orchestrator

npx machina-cli add skill gaelic-ghost/apple-dev-skills/apple-xcode-hybrid-orchestrator --openclaw

Files (1)

SKILL.md

2.8 KB

Apple Xcode Hybrid Orchestrator

Use this skill as the entrypoint for Apple and Swift tasks.

Workflow

Classify intent:

session/workspace
read/search
build/test/run
packaging/toolchain
docs lookup
mutation request

Route execution:

Use $xcode-mcp-first-executor first for anything supported by Xcode MCP.
If MCP is unavailable, times out, or lacks needed capability, hand off to $apple-swift-cli-fallback immediately.

Apply docs policy:

Use $apple-dev-safety-and-docs for Dash local-first docs routing and advisory cooldown handling.

Apply mutation safety:

If request can touch Xcode-managed scope, use $apple-dev-safety-and-docs hard 2-step consent gate before any direct filesystem fallback.

Required Policy

Always prefer Xcode MCP when it can perform the action.
Fallback to official tooling automatically when MCP path is blocked.
On fallback, include concise MCP setup guidance only if cooldown allows.
Never perform direct mutation in Xcode-managed scope unless safety policy conditions are satisfied.

References

references/workflow-policy.md
references/mcp-setup-advisory.md
references/skills-discovery.md

Scripts

scripts/advisory_cooldown.py

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/apple-xcode-hybrid-orchestrator/SKILL.md

View on GitHub

Overview

This skill serves as the entrypoint for Apple and Swift tasks, prioritizing Xcode MCP-driven execution and automatically falling back to official Apple and Swift CLI tooling. It covers Xcode, SwiftPM, build/test runs, toolchain checks, docs lookups, and mutation-safety decisions, including customization requests.

How This Skill Works

It classifies user intent and routes actions to the $xcode-mcp-first-executor when MCP supports the task. If MCP is unavailable or lacks capability, it automatically falls back to the $apple-swift-cli-fallback. It then applies the docs policy via $apple-dev-safety-and-docs and enforces a 2-step consent gate for any mutations touching Xcode-managed scope.

When to Use It

Tasks involving Xcode, SwiftPM, or build/test execution
Toolchain checks or environment validation
Docs lookup and knowledge retrieval for Apple/Swift tooling
Mutation-risk decisions or safety-sensitive operations
User requests to customize the orchestration policy for this skill

Quick Start

Step 1: Load current effective customization settings first: uv run python scripts/customization_config.py effective
Step 2: Answer targeted customization questions using references/customization-flow.md to drive knob-by-knob decisions
Step 3: Persist changes and apply overrides: uv run python scripts/customization_config.py apply --input <yaml-file>

Best Practices

Always route supported actions to the MCP-first executor when possible
If MCP cannot perform the action, automatically fallback to official Swift/Apple CLI tooling
Apply the docs policy before any direct filesystem mutation
Enforce the 2-step consent gate for requests touching Xcode-managed scope
Use the interactive customization flow to tailor policy safely

Example Use Cases

Orchestrating a SwiftPM package build with Xcode MCP routing
Running unit tests and artifact packaging with automatic CLI fallback
Querying Dash-local docs for Swift concurrency APIs
Mutating project configuration with safety gating in place
Customizing the orchestration policy to adjust MCP usage limits

Frequently Asked Questions

Add this skill to your agents