AgentSkillsCN

Xcode Project Manager

Xcode 项目管理器

SKILL.md

Xcode Project Manager Skill

Purpose

Automate Xcode project file manipulation without corruption. This skill safely manages .pbxproj files, adds files with proper target membership, and fixes common module import issues.

Primary Tool: sync-xcode-project.rb

The recommended way to add files to the Xcode project is using the Ruby-based sync script located at apps/your-ios-app/scripts/sync-xcode-project.rb. This tool uses the industry-standard Xcodeproj gem (same as CocoaPods/Fastlane).

Usage

bash
cd apps/your-ios-app

# Sync all new Swift files (recommended)
ruby scripts/sync-xcode-project.rb

# Preview what would be added (dry run)
ruby scripts/sync-xcode-project.rb --dry-run

# Verbose output for debugging
ruby scripts/sync-xcode-project.rb --verbose

# Quiet mode (only errors)
ruby scripts/sync-xcode-project.rb --quiet

Features

  • •Automatically detects new .swift files not in project
  • •Adds files to correct groups (matching directory structure)
  • •Creates missing groups as needed
  • •Adds files to YourApp target's Sources build phase
  • •Creates timestamped backups before modifications
  • •Idempotent (safe to run multiple times)

Backups

Backups are stored in apps/your-ios-app/.xcode-backups/ with timestamps. The script automatically keeps only the 10 most recent backups.

Capabilities

  • •Sync new Swift files from disk to Xcode project
  • •Fix module import and "cannot find type in scope" errors
  • •Backup project files before modifications
  • •Generate proper module maps
  • •Clean derived data and build caches

Fixing Module Issues

bash
./module_fixer.sh YourApp.xcodeproj

Legacy Tools (Deprecated)

Warning: The Python-based tools below have known bugs and should not be used. Use sync-xcode-project.rb instead.

  • •pbxproj_parser.py - DEPRECATED: Has a bug where save() doesn't persist changes
  • •file_adder.py - DEPRECATED: Depends on broken pbxproj_parser.py
  • •backup_manager.py - Still functional for backup/restore operations
  • •.cursor/scripts/add_to_xcode.py - DEPRECATED: Uses fragile regex patterns

Error Patterns

This skill handles:

  • •"Multiple commands produce" errors
  • •"Cannot find type in scope" issues
  • •Duplicate file references
  • •Missing target membership
  • •Corrupted project files

Best Practices

  1. •Run sync-xcode-project.rb --dry-run first to preview changes
  2. •Always let the script create backups (default behavior)
  3. •Verify build after modifications with xcodebuild
  4. •Use --verbose when debugging issues