Add iOS guides for skills (Re-opened with updates) by peterfriese · Pull Request #58 · firebase/agent-skills

peterfriese · 2026-03-31T10:31:23Z

This PR introduces iOS guides for several skills. It replaces PR #25 and incorporates the modern Swift practices and fixes merged from #55.

* Add firebase-data-connect-basics skill (#7) * Add firebase-data-connect-basics skill * Add firebase dataconnect basic skills --------- Co-authored-by: Muhammad Talha <muhammadtalhar@google.com> * [Dataconnect] Restructure SKILL.md into a development workflow guide --------- Co-authored-by: Muhammad Talha <muhammadtalhar@google.com> Co-authored-by: Muhammad Talha <126821605+mtr002@users.noreply.github.com>

* Add Cursor plugin configuration * Add logo to cursor plugin config * Move logo to assets directory * Restructure Cursor plugin to multi-plugin format * Clean up language * Use a symlink instead

…#19)

Change all `firebase` shell command mentioned in the skills to use `npx -y firebase-tools@latest` instead to ensure freshness and reduce frictions to the agents.

- Move all one-time-only local environment setup from `firebase-basic` to `firebase-local-env-setup` skill - Add description about how to install skills and MCP server.

Based on https://github.com/peter-evans/create-pull-request?tab=readme-ov-file#action-inputs

Co-authored-by: ssbushi <66321939+ssbushi@users.noreply.github.com>

* Add agent skills for firestore enterprise with native mode * Amend SKILL.md * Format SKILL * Address comments and rename standard edition * Remove files & update frontmatter * Updated to use "npx firebase-tools@latest" --------- Co-authored-by: Sichen Liu <sichenliu@google.com> Co-authored-by: Joe Hanley <joehanley@google.com>

Updated the installation reference guides for all supported agents (Antigravity, Claude Code, Cursor, Gemini CLI, GitHub Copilot, and others) in the `firebase-local-env-setup` skill. - Added detailed steps to locate, verify, and safely merge MCP configurations (`mcp.json`, `claude_desktop_config.json`, etc.) without overwriting existing entries. - Added explicit instructions to check for existing skill installations using `npx skills list` before installing. - Enforced "stop and wait" instructions for user restarts to ensure the agent correctly verifies the MCP server connection securely.

* Update `firebase-basics` skills - Optimize description so that it is more likely to be loaded - Clearly state the prerequisites, how to validate them and how to meet them. - Add principles about how to optimize agent ability to help with Firebase related task - Indexing other knowledges for progressive disclosure. Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

) - Update their description so that firebase-basics can be picked up more consistently - Update instructions about how to refresh skills for Antigravity and other agents.

* docs: improve local installation instructions * docs: address reviewer feedback on local installation instructions

@gemini-code-assist

#52) * adjusting cursor plugin to reflect skills and mcp setup path correctly * Apply suggestion from @gemini-code-assist[bot] Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com> * update mcp path to ensure it can find it * correct the path --------- Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

- standardize AI model names to gemini-flash-latest - restore context in AI Logic chat examples - remove non-existent android_setup.md reference - clarify automatic vs manual index management in Firestore guides"

Refine iOS and Firestore Skills with Proactive Indexing and Modern SwiftUI Standards

gemini-code-assist

Code Review

This pull request introduces comprehensive iOS (Swift) setup guides and best practices across multiple Firebase skills, including AI Logic, Auth, and Firestore. It emphasizes automated provisioning via the Firebase CLI, modern SwiftUI state management using the Observation framework, and critical initialization order to prevent crashes. Additionally, a new xcode-project-setup skill is added to automate Xcode project dependency management using a native Swift script. Feedback was provided regarding a dangerous force unwrap and incorrect string formatting in the iOS Auth setup guide.

skills/firebase-auth-basics/references/ios_setup.md

docs: address indexing, SDK versioning, and auth review feedback

peterfriese · 2026-03-31T11:14:15Z

/gemini review

gemini-code-assist

Code Review

This pull request introduces comprehensive iOS (Swift) support across several Firebase skills, including AI Logic, Auth, and Firestore. It adds a new xcode-project-setup skill that provides a native Swift script to automate SPM dependency management and project configuration, strictly avoiding Ruby-based tools. Key documentation updates include critical rules for SwiftUI initialization order, the transition from FirebaseFirestoreSwift to the main Firestore module, and a mandate for CLI-based service provisioning. A review comment suggests refining the Firestore realtime listener documentation to better reflect how Swift's .task handles cancellation, specifically recommending AsyncSequence or explicit task cancellation handling.

skills/firebase-firestore-standard/references/ios_setup.md

…listeners

…k id

peterfriese

/gemini review

peterfriese · 2026-03-31T12:11:25Z

/gemini review

gemini-code-assist

Code Review

This pull request introduces comprehensive iOS support across multiple Firebase skills, including AI Logic, Auth, and Firestore. A significant addition is the xcode-project-setup skill, which provides a native Swift-based automation tool for managing SPM dependencies and project configuration without relying on Ruby. The updates establish critical development patterns for iOS, such as prioritizing the Observation framework, enforcing strict initialization orders to prevent crashes, and migrating away from the deprecated FirebaseFirestoreSwift module. Feedback is provided regarding a technical error in the Firestore iOS setup guide where a synchronous listener is incorrectly shown being awaited within a SwiftUI task block.

skills/firebase-firestore-standard/references/ios_setup.md

@mainactor

In response to swift-concurrency and swiftui-expert-skill guidelines: - Applied @mainactor to ViewModels to ensure thread-safe UI updates and fix Swift 6 strict concurrency data races. - Applied 'final' to ViewModels. - Used 'isolated deinit' in DataManager for safe actor-isolated cleanup of ListenerRegistrations (Swift 6.2+ pattern). - Replaced deprecated .foregroundColor with modern .foregroundStyle.

skills/firebase-ai-logic-basics/references/ios_setup.md

rachelsaunders · 2026-04-01T20:37:19Z

skills/firebase-auth-basics/references/ios_setup.md

+}
+```
+
+## 5. Legacy Options (Completion Handlers)


Should we be including this? Will devs be commonly using Agent Skills with older codebases? I'm worried about confusing the model.

Will remove it.

+1 - I think ti makes sense to cut this unless its addressing a specific confusion that we've seen agents have. In general, I find that agents are pretty good at handling conversions like this on their own (at least in other languages)

rachelsaunders · 2026-04-01T20:38:27Z

skills/firebase-auth-basics/SKILL.md

 - **Firebase Project**: Created via `npx -y firebase-tools@latest projects:create` (see `firebase-basics`).
 - **Firebase CLI**: Installed and logged in (see `firebase-basics`).

+## 🤖 Core Automation Mandate


Should all the changes in this file be in a separate PR? Except the changes in line 92, they don't seem to be specific to iOS Agent Skills, are they?

Agreed, but not bocking. These seem like good changes to get in for all users.

rachelsaunders · 2026-04-01T20:41:36Z

skills/firebase-basics/references/firebase-project-create.md

 2. Enter a **display name**.
+
+## 2. Register Platform-Specific Apps
+A Firebase Project is just a container. To actually use Firebase in code, you must register a platform-specific "App" (iOS, Android, or Web) within the project and download its configuration file.


Suggested change

A Firebase Project is just a container. To actually use Firebase in code, you must register a platform-specific "App" (iOS, Android, or Web) within the project and download its configuration file.

A Firebase Project is just a container. To actually use Firebase in code, you must register a platform-specific "App" (iOS, Android, or Web) within the Firebase project and download its configuration file so that it can be added to the codebase.

rachelsaunders · 2026-04-01T20:45:24Z

skills/firebase-basics/references/ios_setup.md

+1. Create the project: `npx -y firebase-tools@latest projects:create`
+2. Register the iOS app: `npx -y firebase-tools@latest apps:create IOS <bundle-id>`
+3. Fetch the config: `npx -y firebase-tools@latest apps:sdkconfig IOS <App-ID>`
+4. Save the output as `GoogleService-Info.plist` in your Xcode project folder. Ensure you remove any non-XML CLI output headers.


Will they need to add the config file to all targets?

rachelsaunders · 2026-04-01T20:46:57Z

skills/firebase-basics/references/web_setup.md

 npm install firebase
 ```

+> **💡 TIP: ALWAYS USE THE LATEST SDK VERSION**


Should this be in a separate PR? It's not specific to the iOS Agent Skills.

rachelsaunders · 2026-04-01T20:48:30Z

skills/firebase-basics/SKILL.md

-5. **Keep Plugin / Agent Skills updated:** Since Firebase best practices evolve quickly, remind the user to regularly check for and install updates to their Firebase plugin or Agent Skills, ensuring you both operate with the latest workflows. Similarly, if you encounter issues with outdated tools or commands, follow the steps below based on your agent environment:
+3. **Always use the latest SDK versions:** To ensure access to the latest features and security fixes, always use the most recent version of the Firebase SDKs for your platform. 
+   - For **iOS**, check the latest release version at [https://github.com/firebase/firebase-ios-sdk/releases](https://github.com/firebase/firebase-ios-sdk/releases).
+   - For **Android**, check the Firebase Android Release Notes for the latest BoM version at [https://github.com/firebase/firebase-android-sdk/releases](https://github.com/firebase/firebase-android-sdk/releases).


Shouldn't this be added with the Android PR? Not the iOS PR.

rachelsaunders · 2026-04-01T20:48:56Z

skills/firebase-basics/SKILL.md

+   - For **Web**, check the latest release version at [https://github.com/firebase/firebase-js-sdk/releases](https://github.com/firebase/firebase-js-sdk/releases).
+4. **Follow Agent Skills for implementation guidance:** Skills provide opinionated workflows (CUJs), security rules, and best practices. Always consult them to understand *how* to implement Firebase features correctly instead of relying on general knowledge.
+5. **Use Firebase MCP Server tools instead of direct API calls:** Whenever you need to interact with remote Firebase APIs (such as fetching Crashlytics logs or executing Data Connect queries), use the tools provided by the Firebase MCP Server instead of attempting manual API calls.
+6. **Keep Plugin / Agent Skills updated:** Since Firebase best practices evolve quickly, remind the user to regularly check for and install updates to their Firebase plugin or Agent Skills, ensuring you both operate with the latest workflows. Similarly, if you encounter issues with outdated tools or commands, follow the steps below based on your agent environment:


Shouldn't all this be added in a separate PR? This isn't specific to the iOS Agent Skills.

rachelsaunders · 2026-04-01T20:50:27Z

skills/firebase-firestore-standard/SKILL.md

+When writing complex queries using the SDK, **anticipate** the need for composite indexes (e.g., combining `==` on one field with `orderBy` on another) and proactively generate the `firestore.indexes.json` file. 
+


separate PR?

This commit addresses Rachel's feedback on PR #58 by: - Reverting out-of-scope changes (Android/Web SDK versioning, Auth/Firestore automation mandates) to be handled in separate PRs. - Reordering AI Logic sections so Chat Session correctly precedes Function Calling. - Removing legacy completion handler snippets from the Auth iOS guide to prevent AI confusion. - Clarifying that a Firebase Project is just a container and requires an App registration. - Adding explicit instructions for the AI agent to read the Xcode project to find the bundle ID before registering the iOS app. - Clarifying that the downloaded plist config should be linked to the main application target.

peterfriese

@rachelsaunders I've addressed all of your feedback! I removed the out-of-scope files, fixed the AI Logic numbering/ordering, removed the legacy completion handlers from the Auth guide to avoid confusing the model, and clarified the setup instructions regarding the Bundle ID and Xcode target. Let me know if everything looks good now!

joehan · 2026-04-02T17:09:43Z

FYI - just pointed this to next and resolved the merge conflicts.

joehan · 2026-04-02T16:55:54Z

skills/firebase-auth-basics/SKILL.md

 - **Firebase Project**: Created via `npx -y firebase-tools@latest projects:create` (see `firebase-basics`).
 - **Firebase CLI**: Installed and logged in (see `firebase-basics`).

+## 🤖 Core Automation Mandate


Agreed, but not bocking. These seem like good changes to get in for all users.

joehan · 2026-04-02T17:11:39Z

skills/xcode-project-setup/SKILL.md

@@ -0,0 +1,87 @@
+---


Did this make it in accidentally? Seems a bit beyond the scope of this repo. If it is completely necessary to get reasonable behavior, we can consider leaving it up

joehan · 2026-04-02T17:12:35Z

skills/firebase-local-env-setup/SKILL.md

@@ -0,0 +1,70 @@
+---


I think I screwed this up in the move to next - this was removed on main, so we can remove it here too

joehan · 2026-04-02T17:23:49Z

skills/firebase-data-connect-basics/SKILL.md


 ```bash
 # Initialize Data Connect
-<<<<<<< HEAD


Oops, missed this while syncing branches - fixing on next.

ryanwilson · 2026-04-02T13:49:45Z

skills/firebase-basics/references/ios_setup.md

+## 1. Create a Firebase Project and App (Automated)
+Do not use the Firebase Console. Use the CLI to automate setup:
+
+1. Create the project: `npx -y firebase-tools@latest projects:create`


I think this is fine for now - but I imagine we should have something to handle if an existing project exists, ask the user if you want to add the app to project XXXX or create a new project

Yes, might be good to explicitly state "check if a Firebase project exists".

ryanwilson · 2026-04-02T13:50:45Z

skills/firebase-basics/references/ios_setup.md

+2. Action: Read the Xcode project (`.pbxproj` or `Info.plist`) to determine the iOS bundle ID.
+3. Register the iOS app: `npx -y firebase-tools@latest apps:create IOS <bundle-id>`
+4. Fetch the config: `npx -y firebase-tools@latest apps:sdkconfig IOS <App-ID>`
+5. Save the output as `GoogleService-Info.plist` in your Xcode project folder. Ensure you remove any non-XML CLI output headers, and ensure the file is linked to the main application target.


Maybe "in the same directory as your Xcode project"? right now I worry an agent would put it in the .xcodeproj directory

This phrasing has worked well for me, but we should see if anyonen runs into issues, and be more explicit if that happens.

ryanwilson · 2026-04-02T13:59:54Z

skills/xcode-project-setup/scripts/xcode_spm_setup/Sources/main.swift

@@ -0,0 +1,145 @@
+import Foundation


Nit: license

ryanwilson · 2026-04-02T14:00:37Z

skills/xcode-project-setup/scripts/xcode_spm_setup/Sources/main.swift

+func main() {
+    let args = CommandLine.arguments
+    guard args.count >= 5 else {
+        print("Usage: swift run --package-path <path> xcode_spm_setup <Path/To/Project.xcodeproj> <RepoURL> <VersionRequirement> [--plist <Path/To/Plist>] <Product1> [Product2 ...]")


I assume we don't want to have a big project and use ArgumentParser, right?

ryanwilson · 2026-04-02T14:01:36Z

skills/xcode-project-setup/scripts/xcode_spm_setup/Sources/main.swift

@@ -0,0 +1,145 @@
+import Foundation
+import XcodeProj
+import PathKit


Does this provide a ton of value?

The purpose of our script is:
a) prevent the agent from using Ruby to write scripts to edit Xcode [rojects
b) wrap XcodeProject (the Swift SDK that Tuist uses to edit Xcode projects).

So - yes, these imports are the entire reason this script exists. I would NOT want use to write a clone of XcodeProj.

ryanwilson · 2026-04-02T14:02:07Z

skills/xcode-project-setup/scripts/xcode_spm_setup/Package.swift

+    name: "xcode_spm_setup",
+    platforms: [.macOS(.v13)],
+    dependencies: [
+        .package(url: "https://github.com/tuist/XcodeProj.git", .upToNextMajor(from: "8.27.7")),


Can we lock to a specific commit hash to prevent any future issues?

Hm.... Not a big fan of this, although I see why you're suggesting it.

joehan and others added 30 commits February 11, 2026 14:57

Explanding out contributor guidelines (#3)

fce063e

update claude plugin marketplace command to use the new repo (#2)

62cf00e

add kiro power (#4)

60ef4b7

update license (#8)

771cef2

Adding a token counting script (#11)

88c0f8e

Adding a Cursor plugin (#13)

11db8e9

* Add Cursor plugin configuration * Add logo to cursor plugin config * Move logo to assets directory * Restructure Cursor plugin to multi-plugin format * Clean up language * Use a symlink instead

Add theme to GCLI extension (#17)

2720ebc

Remove curl|bash (#18)

c66a8c0

Update SKILL.md to remove references to 2.5 and instead use latest. (…

77cd16a

…#19)

feat: Add sync job for genkit-ai/skills (#23)

e67411e

Change to use npx to invoke Firebase CLI (#26)

16b47b6

Change all `firebase` shell command mentioned in the skills to use `npx -y firebase-tools@latest` instead to ensure freshness and reduce frictions to the agents.

use pat for cla reasons (#29)

b5085bf

fix: update workflow title and committer details (#33)

1287aca

Move the local environment setup to a new skill + MCP setup (#31)

06797c1

- Move all one-time-only local environment setup from `firebase-basic` to `firebase-local-env-setup` skill - Add description about how to install skills and MCP server.

fix: Add reviewers to sync-genkit-skills workflow (#35)

87575fe

Based on https://github.com/peter-evans/create-pull-request?tab=readme-ov-file#action-inputs

chore: sync updated skills (#34)

c33c1db

Co-authored-by: ssbushi <66321939+ssbushi@users.noreply.github.com>

Update skill names in security rules documentation (#37)

7a30158

update the skill verification instruction (#38)

720d3ba

chore: sync updated skills (#39)

c4fcaab

gemini-3-pro-preview --> gemini-3.1-pro-preview (#40)

afbce83

Update firebase-basics skill and firebase-local-env-setup skill (#43

3f55d5a

) - Update their description so that firebase-basics can be picked up more consistently - Update instructions about how to refresh skills for Antigravity and other agents.

Split out python sdk content (#45)

861027a

Fixing up Cursor plugin format (#46)

da81537

docs: Improve local installation instructions (#47)

fcf78b8

* docs: improve local installation instructions * docs: address reviewer feedback on local installation instructions

Add new skills logo (#51)

83ee3be

peterfriese added 3 commits March 30, 2026 17:43

docs: address feedback from PR review

2997364

- standardize AI model names to gemini-flash-latest - restore context in AI Logic chat examples - remove non-existent android_setup.md reference - clarify automatic vs manual index management in Firestore guides"

docs(guides): fix dictionary write snippet and add AIViewModel defer

5ee1b1c

Merge pull request #55 from firebase/feature/ios-guides-peterfriese

f882218

Refine iOS and Firestore Skills with Proactive Indexing and Modern SwiftUI Standards

gemini-code-assist bot reviewed Mar 31, 2026

View reviewed changes

skills/firebase-auth-basics/references/ios_setup.md Outdated Show resolved Hide resolved

skills/firebase-auth-basics/references/ios_setup.md Outdated Show resolved Hide resolved

peterfriese added 3 commits March 31, 2026 13:04

docs: address indexing, SDK versioning, and auth review feedback

17d3944

Merge pull request #59 from firebase/feature/ios-guides-peterfriese

9ed9257

docs: address indexing, SDK versioning, and auth review feedback

chore: revert unnecessary changes to web and python guides

6dae64f

gemini-code-assist bot reviewed Mar 31, 2026

View reviewed changes

skills/firebase-firestore-standard/references/ios_setup.md Outdated Show resolved Hide resolved

peterfriese added 2 commits March 31, 2026 13:25

docs(firestore): implement explicit task suspension for safe SwiftUI …

6e06b26

…listeners

docs(firestore): refine listener best practices to use deinit and tas…

6ffee9f

…k id

peterfriese commented Mar 31, 2026

View reviewed changes

peterfriese requested review from charlotteliang, joehan and ryanwilson March 31, 2026 12:02

gemini-code-assist bot reviewed Mar 31, 2026

View reviewed changes

skills/firebase-firestore-standard/references/ios_setup.md Outdated Show resolved Hide resolved

peterfriese added 2 commits March 31, 2026 14:13

docs(firestore): remove redundant invalid code block caught by review

b59745f

rachelsaunders reviewed Apr 1, 2026

View reviewed changes

peterfriese added 3 commits April 2, 2026 15:33

docs(ai-logic): group advanced features to avoid sequential confusion

dd2f57e

chore: revert out-of-scope iOS injection in enterprise firestore skill

d2ef11b

peterfriese commented Apr 2, 2026

View reviewed changes

joehan changed the base branch from main to next April 2, 2026 17:04

Merge branch 'next' into feature/ios-guides

f0a352a

joehan reviewed Apr 2, 2026

View reviewed changes

ryanwilson reviewed Apr 2, 2026

View reviewed changes

	A Firebase Project is just a container. To actually use Firebase in code, you must register a platform-specific "App" (iOS, Android, or Web) within the project and download its configuration file.
	A Firebase Project is just a container. To actually use Firebase in code, you must register a platform-specific "App" (iOS, Android, or Web) within the Firebase project and download its configuration file so that it can be added to the codebase.

		When writing complex queries using the SDK, anticipate the need for composite indexes (e.g., combining `==` on one field with `orderBy` on another) and proactively generate the `firestore.indexes.json` file.

Conversation

peterfriese commented Mar 31, 2026

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Uh oh!

peterfriese commented Mar 31, 2026

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

peterfriese left a comment

Choose a reason for hiding this comment

Uh oh!

peterfriese commented Mar 31, 2026

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

peterfriese left a comment

Choose a reason for hiding this comment

Uh oh!

joehan commented Apr 2, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

peterfriese Apr 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

peterfriese Apr 3, 2026 •

edited

Loading