xcode-build

name	xcode-build
description	Xcode 构建配置与交付链路 Skill。用于 Build Settings、scheme、xcconfig、构建脚本、签名、证书、Archive、Export、CI/CD、XCFramework 与构建性能策略；不要把一次性 xcodebuild 验证、Simulator/真机执行路径、测试编写、代码审查或运行时排障误判到本 Skill。

Xcode 构建与配置

Purpose

Design, modify, or review Xcode build configuration, signing, archive/export, CI/CD, and distribution workflows while keeping one-off build verification delegated to verification-specific Skills.

中文说明

该 Skill 是 Xcode 构建配置与交付链路专项 Skill。

负责：

• Build Settings。
• scheme / configuration / xcconfig。
• 构建脚本。
• Signing、证书、Provisioning Profile、entitlements。
• Archive / Export / IPA 导出。
• CI/CD 中的 xcodebuild 流程。
• XCFramework 打包与分发策略。
• 构建性能优化策略。

不负责：

• 任务末尾一次性 xcodebuild 验证。
• 真机 / Simulator 自动化执行路径。
• 测试代码编写。
• 静态代码审查。
• 运行时 crash / 泄漏 / 卡顿排障。

When to Use

Use this Skill when the user asks about:

• Build Settings。
• scheme、target、configuration。
• .xcconfig 管理。
• build phases / run scripts。
• code signing、certificates、profiles、entitlements、capabilities。
• Archive / Export / IPA。
• CI/CD build pipeline。
• xcodebuild archive / -exportArchive 策略。
• XCFramework 构建或分发。
• 构建性能优化。
• workspace / project / scheme 选择策略。

When Not to Use

Do not use this Skill when:

• 用户只是要求“最后编译验证一下”或“跑一次 xcodebuild”；使用 ios-verification。
• 用户主要在问在哪个 Simulator / 真机上安装、启动、截图、导航；使用 ios-automation。
• 用户需要编写或执行最窄测试；使用 ios-feature-implementation(test-implementation)；执行最窄验证使用 ios-verification。
• 用户需要代码质量审查；使用 code-review。
• 用户需要分析 crash、泄漏、卡顿；使用 debugging / ios-performance。
• 用户需要判断现有验证证据是否足够；使用 ios-verification。

Agent Rules

Boundary Rules

• Treat this Skill as build configuration / delivery design, not default final verification.
• Do not run validation-type xcodebuild as the main purpose of this Skill.
• If actual project-environment verification is required, hand off to ios-verification.
• If device / simulator automation is required, hand off to ios-automation.
• If a build error log must be analyzed, prefer ios-verification first.

Build Configuration Rules

• Identify build entry first: .xcworkspace / .xcodeproj / target / scheme.
• For iOS projects with both .xcworkspace and .xcodeproj, prefer .xcworkspace.
• Identify the goal: local build, test pipeline, archive, export, signing, CI, XCFramework, or build performance.
• Separate configuration design from verification execution.
• Prefer explicit configuration over hidden environment assumptions.
• Keep project changes minimal and scoped to the build issue.

Signing Rules

When handling signing, always clarify:

• Bundle identifier.
• Team ID.
• Signing style: automatic or manual.
• Certificate type.
• Provisioning profile type.
• Entitlements and capabilities.
• Debug vs Release differences.
• Local vs CI signing environment.

Do not claim signing is fixed unless the evidence confirms it.

Archive / Export Rules

For Archive / Export work, specify:

• Archive action.
• Export method.
• Export options plist.
• Signing style.
• Destination path.
• App Store / Ad Hoc / Enterprise / Development intent.
• CI artifact output expectations.

Private Dependency Rules

• If build configuration involves private Pods or local components, inspect Podfile, Podfile.lock, and Pods/Manifest.lock.
• If a local :path Pod is active, modify the real component repository, not Pods/<LibraryName>.
• For private library / component changes, keep the main project on local :path dependency for development, validation, and independent code-review unless the user explicitly asks to restore versioned dependency; switch to local :path only when the project is not already pointing at the local source and the private-library source change must be validated. After modifying the real private library repository, validate and review through the main project using that local dependency.
• After validation passes, keep the local :path dependency state by default; do not commit local :path dependency references unless explicitly requested or required by an authorized main-project dependency-file commit.

DerivedData Rules

• Default local builds should use Xcode system DerivedData: ~/Library/Developer/Xcode/DerivedData.
• Do not introduce temporary public -derivedDataPath strategies as default.
• Do not reintroduce old public XCODE_DERIVED_DATA_* or CODEX_DERIVED_DATA_SLOT configuration.
• For validation-type builds, delegate to wrapper / build-queue policy through ios-verification.

File Header Rules

When adding .swift, .h, .m, .mm files and headers are required:

• Created by must use local whoami.
• Do not use Codex as creator.
• Date format: YYYY/M/D.

Token Budget

• Do not paste full build logs.
• Do not dump full .xcresult JSON.
• Do not scan DerivedData recursively.
• Prefer targeted build setting snippets.
• Prefer diagnostics.json and build-summary.txt for error context.
• Summarize only actionable configuration deltas.

Core Workflow

1. Identify target project entry: workspace / project / scheme / target.
2. Identify task goal: build config, signing, archive, export, CI, XCFramework, or performance strategy.
3. Inspect only relevant files: project settings, xcconfig, scheme, plist, entitlements, Podfile, CI config, export options.
4. Define the desired configuration state.
5. Propose or apply minimal scoped changes.
6. Document CI/local impact.
7. If evidence is required, hand off to ios-verification or ios-verification rather than running ad-hoc verification inside this Skill.
8. If the desired deliverable is a formal HTML build/CI/signing strategy document, prepare a source packet and route final document generation to html-docs.
9. Report residual risk and next action.

Inputs

Expected input contract:

{
  "goal": "configure signing | archive | export | ci | build settings | xcframework",
  "workspace": "App.xcworkspace",
  "project": null,
  "scheme": "App",
  "target": "App",
  "configuration": "Debug | Release",
  "destination": "optional",
  "ci_provider": "Jenkins | GitHub Actions | local | other",
  "signing": {
    "team_id": "optional",
    "bundle_id": "optional",
    "style": "automatic | manual | unknown",
    "export_method": "app-store | ad-hoc | enterprise | development | unknown"
  },
  "changed_files": [],
  "constraints": []
}

Outputs

Return compact structured output:

{
  "status": "completed | proposed | blocked | partial",
  "build_entry": {
    "workspace": "App.xcworkspace",
    "project": null,
    "scheme": "App",
    "target": "App",
    "configuration": "Release"
  },
  "build_strategy": "...",
  "signing_strategy": "...",
  "archive_strategy": "...",
  "export_strategy": "...",
  "ci_changes": [],
  "changed_files": [],
  "validation_handoff": "none | ios-verification | ios-verification",
  "known_risks": [],
  "next_action": "none | review | verify | provide_signing_assets | blocked"
}

Exit Conditions

Return completed when:

• Build/signing/archive/CI configuration change or design is complete.
• Changed files are listed.
• Local and CI impact is described.
• Verification handoff is clear.

Return proposed when:

• The user requested a strategy/design only and no repository change was made.

Return partial when:

• Some configuration was completed but final signing credentials, CI secrets, or device/team access are missing.

Return blocked when:

• Required signing assets, team access, project files, CI credentials, or dependency access are unavailable.
• The repository is not an Xcode project.
• Required decision between signing/export/CI paths is missing.

Escalation Rules

Escalate to ios-verification when:

• The user explicitly asks to run real project-environment build verification.
• Build configuration changes need actual final evidence.
• Current validation/review/build evidence may be insufficient.
• Targeted validation, affected test selection, or compact build failure attribution is needed.

Escalate to ios-automation when:

• The task becomes install, launch, simulator lifecycle, real-device workflow, screenshot, or accessibility verification.

Escalate to ios-feature-implementation(test-implementation) when:

• The task becomes test writing or testability seam implementation.

Escalate to code-review when:

• Configuration changes need static review and risk assessment.

Escalate to ios-feature-implementation with sdk-contract mode when:

• The task is SDK distribution boundary, module design, package layout, or XCFramework product strategy.

Escalate to html-docs when:

• Build, signing, Archive/Export, CI/CD, or XCFramework decisions must become a formal HTML strategy, review, or handoff document.

Reporting Format

Build entry:
- Workspace/Project:
- Scheme:
- Target:
- Configuration:

Build strategy:
- ...

Signing strategy:
- ...

Archive/export strategy:
- ...

CI impact:
- ...

Validation handoff:
- none | ios-verification

Known risks:
- ...

Next action:
- ...

Reference Resources

• references/build-settings.md
• references/ci-templates.md

Relationship to Other Skills

• Use this Skill for Build Settings, signing, Archive/Export, CI/CD, XCFramework, and build scripts.
• Use ios-verification for one-off project-environment build verification.
• Use ios-automation for simulator/device execution and app lifecycle automation.
• Use ios-feature-implementation(test-implementation) for unit/UI test writing and ios-verification for targeted validation.
• Use code-review for static review of configuration changes.
• Use ios-verification for compact build failure attribution.
• Use ios-feature-implementation with sdk-contract mode for SDK distribution and module boundary strategy; keep concrete build/signing/archive mechanics in this Skill.
• Use html-docs for final formal HTML build / CI / signing documents; this Skill provides the configuration source packet and risks.