xcode-project-setup

Name: xcode-project-setup
Author: firebase

71kinstalls74forks

How to install xcode-project-setup?

firebase/agent-skills/xcode-project-setup

$npx -y skills add firebase/agent-skills --skill xcode-project-setup

Installs into the current project.

Summary

Safely modifies Xcode projects (.pbxproj) to add Swift Packages and link files. Use this skill whenever an iOS project needs dependencies installed (e.g. Firebase, Alamofire).

Files · 1

View on GitHub

SKILL.md

1	# Xcode Project Setup
2
3	## ⛔️ CRITICAL RULES & ENVIRONMENT CHECKS
4
5	Before performing any Xcode setup or file manipulation, you MUST adhere to
6	the following rules. A hefty fee will be applied if you violate them.
7
8	### 1. The Anti-Ruby Mandate
9
10	You are strictly forbidden from using Ruby, Rails, or any Ruby gems
11	(including the `xcodeproj` gem). Under no circumstances may you write or execute
12	Ruby scripts.
13
14	### 2. Modern Xcode Folder Synchronization
15
16	Modern Xcode projects support folder synchronization. When adding new source
17	code (`.swift`) or resource files, simply write them to the correct directory on
18	disk. They will be automatically included in the Xcode project. **Never manually
19	modify the `.pbxproj` file to add files.**
20
21	### 3. Allowed Scripting Languages
22
23	If you absolutely must write a script to manipulate the project environment
24	(e.g., configuring SPM packages beyond what the provided `xcode_spm_setup`
25	script does), you must use Swift. Only as an absolute last resort, if Swift
26	is completely unviable, may you use Node.js or TypeScript.
27
28	### 4. Toolchain Verification
29
30	Because this skill relies entirely on a native Swift script, you must verify the
31	environment:
32
33	- Run `swift --version` before proceeding.
34	- If the Swift command is not found, you must stop and recommend the user
35	install the Swift toolchain (e.g., via `xcode-select --install` on macOS), or
36	ask if you can attempt to install it for them. Do not attempt to proceed
37	without Swift.
38
39	### 5. Mandatory Linker Flags for Static Frameworks (Firebase)
40
41	When setting up SPM dependencies that heavily rely on internal Objective-C
42	categories and `+load` methods (such as the Firebase iOS SDK suite), the Apple
43	linker will aggressively strip these methods out if they are linked statically.
44
45	This causes fatal runtime crashes (e.g.,
46	`FirebaseAuth/Auth.swift:167: Fatal error: Unexpectedly found nil`).
47
48	**The provided `xcode_spm_setup` Swift script automatically injects the `-ObjC`
49	flag to `OTHER_LDFLAGS` when adding Firebase products.** However, you should
50	still verify it is present in the build settings if you encounter issues.
51
52	- Failing to include this flag when adding Firebase dependencies is a critical
53	error.
54
55	______________________________________________________________________
56
57	## Empty Directory Workflow
58
59	If you are asked to build an iOS app or configure Xcode dependencies but **no
60	`.xcodeproj` or `.xcworkspace` exists**, you MUST ask the user to create the
61	project first:
62
63	**"No Xcode project found in this directory. Please create an empty Xcode
64	project manually and let me know when you are ready to proceed."**
65
66	Wait for the user to confirm they have created the `.xcodeproj` via Xcode, then
67	proceed with the Standard Xcode Workflow below.
68
69	______________________________________________________________________
70
71	## Standard Xcode Workflow
72
73	Do not use raw text parsing, `sed`, or Ruby scripts to modify `.pbxproj` files
74	directly.
75
76	Instead, execute the Swift configuration package bundled with this skill
77	(`scripts/xcode_spm_setup`) to securely install SPM packages and link optional
78	config files (like `GoogleService-Info.plist`).
79
80	### CRITICAL: Always Use Latest SDK Version
81
82	To ensure access to the latest features and security fixes, always use the most
83	recent version of the Firebase iOS SDK. Check for the latest release version at
84	[https://github.com/firebase/firebase-ios-sdk/releases](https://github.com/firebase/firebase-ios-sdk/releases).
85
86	- Use the most recent version number (e.g., `11.x.y`) in your commands instead
87	of hardcoded placeholders.
88
89	### Understanding the Script's Actions
90
91	When adding a Swift Package to an Xcode project, two distinct steps must occur:
92
93	1. Adding the package repository dependency (e.g.,
94	`https://github.com/Alamofire/Alamofire`).
95	1. Selecting the target (e.g., `MyApp`), navigating to **General > Frameworks,
96	Libraries, and Embedded Content**, and hitting the `+` button to explicitly
97	link the specific product modules (e.g., `Alamofire`).
98
99	**The provided `xcode_spm_setup` Swift script automatically handles BOTH of
100	these steps for you.** By passing the list of modules as arguments, it safely
101	injects the package dependency and automatically wires those modules to the main
102	target's Frameworks build phase. You do not need to do any manual linking.
103
104	## Usage
105
106	1. Locate the package path: Find the absolute path to this skill's
107	`scripts/xcode_spm_setup` directory on disk.
108	1. Execute: Run the native `swift run` command using the signature below:
109
110	```bash
111	swift run --package-path <PATH_TO_SKILL>/scripts/xcode_spm_setup xcode_spm_setup <ProjectPath.xcodeproj> <RepoURL> <VersionRequirement> [--plist <Optional/Pa

People who liked this also viewed

6 picks

Type

xcode-project-setup

71kinstalls74forks

View on GitHub

How to install xcode-project-setup?

firebase/agent-skills/xcode-project-setup

$npx -y skills add firebase/agent-skills --skill xcode-project-setup

Installs into the current project.

Summary

Safely modifies Xcode projects (.pbxproj) to add Swift Packages and link files. Use this skill whenever an iOS project needs dependencies installed (e.g. Firebase, Alamofire).

Files · 1

View on GitHub

SKILL.md

1	# Xcode Project Setup
2
3	## ⛔️ CRITICAL RULES & ENVIRONMENT CHECKS
4
5	Before performing any Xcode setup or file manipulation, you MUST adhere to
6	the following rules. A hefty fee will be applied if you violate them.
7
8	### 1. The Anti-Ruby Mandate
9
10	You are strictly forbidden from using Ruby, Rails, or any Ruby gems
11	(including the `xcodeproj` gem). Under no circumstances may you write or execute
12	Ruby scripts.
13
14	### 2. Modern Xcode Folder Synchronization
15
16	Modern Xcode projects support folder synchronization. When adding new source
17	code (`.swift`) or resource files, simply write them to the correct directory on
18	disk. They will be automatically included in the Xcode project. **Never manually
19	modify the `.pbxproj` file to add files.**
20
21	### 3. Allowed Scripting Languages
22
23	If you absolutely must write a script to manipulate the project environment
24	(e.g., configuring SPM packages beyond what the provided `xcode_spm_setup`
25	script does), you must use Swift. Only as an absolute last resort, if Swift
26	is completely unviable, may you use Node.js or TypeScript.
27
28	### 4. Toolchain Verification
29
30	Because this skill relies entirely on a native Swift script, you must verify the
31	environment:
32
33	- Run `swift --version` before proceeding.
34	- If the Swift command is not found, you must stop and recommend the user
35	install the Swift toolchain (e.g., via `xcode-select --install` on macOS), or
36	ask if you can attempt to install it for them. Do not attempt to proceed
37	without Swift.
38
39	### 5. Mandatory Linker Flags for Static Frameworks (Firebase)
40
41	When setting up SPM dependencies that heavily rely on internal Objective-C
42	categories and `+load` methods (such as the Firebase iOS SDK suite), the Apple
43	linker will aggressively strip these methods out if they are linked statically.
44
45	This causes fatal runtime crashes (e.g.,
46	`FirebaseAuth/Auth.swift:167: Fatal error: Unexpectedly found nil`).
47
48	**The provided `xcode_spm_setup` Swift script automatically injects the `-ObjC`
49	flag to `OTHER_LDFLAGS` when adding Firebase products.** However, you should
50	still verify it is present in the build settings if you encounter issues.
51
52	- Failing to include this flag when adding Firebase dependencies is a critical
53	error.
54
55	______________________________________________________________________
56
57	## Empty Directory Workflow
58
59	If you are asked to build an iOS app or configure Xcode dependencies but **no
60	`.xcodeproj` or `.xcworkspace` exists**, you MUST ask the user to create the
61	project first:
62
63	**"No Xcode project found in this directory. Please create an empty Xcode
64	project manually and let me know when you are ready to proceed."**
65
66	Wait for the user to confirm they have created the `.xcodeproj` via Xcode, then
67	proceed with the Standard Xcode Workflow below.
68
69	______________________________________________________________________
70
71	## Standard Xcode Workflow
72
73	Do not use raw text parsing, `sed`, or Ruby scripts to modify `.pbxproj` files
74	directly.
75
76	Instead, execute the Swift configuration package bundled with this skill
77	(`scripts/xcode_spm_setup`) to securely install SPM packages and link optional
78	config files (like `GoogleService-Info.plist`).
79
80	### CRITICAL: Always Use Latest SDK Version
81
82	To ensure access to the latest features and security fixes, always use the most
83	recent version of the Firebase iOS SDK. Check for the latest release version at
84	[https://github.com/firebase/firebase-ios-sdk/releases](https://github.com/firebase/firebase-ios-sdk/releases).
85
86	- Use the most recent version number (e.g., `11.x.y`) in your commands instead
87	of hardcoded placeholders.
88
89	### Understanding the Script's Actions
90
91	When adding a Swift Package to an Xcode project, two distinct steps must occur:
92
93	1. Adding the package repository dependency (e.g.,
94	`https://github.com/Alamofire/Alamofire`).
95	1. Selecting the target (e.g., `MyApp`), navigating to **General > Frameworks,
96	Libraries, and Embedded Content**, and hitting the `+` button to explicitly
97	link the specific product modules (e.g., `Alamofire`).
98
99	**The provided `xcode_spm_setup` Swift script automatically handles BOTH of
100	these steps for you.** By passing the list of modules as arguments, it safely
101	injects the package dependency and automatically wires those modules to the main
102	target's Frameworks build phase. You do not need to do any manual linking.
103
104	## Usage
105
106	1. Locate the package path: Find the absolute path to this skill's
107	`scripts/xcode_spm_setup` directory on disk.
108	1. Execute: Run the native `swift run` command using the signature below:
109
110	```bash
111	swift run --package-path <PATH_TO_SKILL>/scripts/xcode_spm_setup xcode_spm_setup <ProjectPath.xcodeproj> <RepoURL> <VersionRequirement> [--plist <Optional/Pa

People who liked this also viewed

6 picks

Type