--- title: "firebase/agent-skills" description: "Agent Skills for Firebase" source: https://github.com/firebase/agent-skills ref: main license: Apache-2.0 licenseName: "Apache License 2.0" canonical: https://skillsdocs.com/firebase/agent-skills base: https://github.com/firebase/agent-skills/blob/main/ chapters: 12 inlined: 12 withheld: 0 words: 5429 updated: 2026-08-06T18:29:13Z generator: "Skills Docs" --- > **firebase/agent-skills** — every Agent Skill in this repository, inlined verbatim. > > Canonical HTML: https://skillsdocs.com/firebase/agent-skills > Per-chapter Markdown: https://skillsdocs.com/firebase/agent-skills/.md > Machine manifest: https://skillsdocs.com/firebase/agent-skills/.well-known/agent-skills/index.json > JSON: https://skillsdocs.com/api/v1/books/firebase/agent-skills > Install: `npx skills add firebase/agent-skills` > Upstream: https://github.com/firebase/agent-skills @ `main` > Licence: Apache-2.0 > > Content is mirrored from GitHub and © its authors, served unmodified. Takedown: https://github.com/kyleledbetter/skillsdocs/issues/new?labels=takedown&title=Takedown+request # firebase/agent-skills Agent Skills for Firebase - **Chapters:** 12 - **Inlined:** 12 (licence detected) - **Words:** 5,429 - **Reading time:** 25 min - **Stars:** 402 ## Table of contents 1. [extension-to-functions-codebase](https://skillsdocs.com/firebase/agent-skills/extension-to-functions-codebase.md) — Skill for converting an installed Firebase Extension (or extension source) into a standalone Cloud Functions for Firebase codebase or publishable npm package,… 2. [firebase-ai-logic-basics](https://skillsdocs.com/firebase/agent-skills/firebase-ai-logic-basics.md) — Official skill for integrating Firebase AI Logic (Gemini API) into web applications. Covers setup, multimodal inference, structured output, and security. 3. [firebase-app-hosting-basics](https://skillsdocs.com/firebase/agent-skills/firebase-app-hosting-basics.md) — Deploys and manages full-stack web applications (Next.js, Angular) with Server-Side Rendering (SSR) using Firebase App Hosting. Use when deploying Next.js/Angu… 4. [firebase-auth-basics](https://skillsdocs.com/firebase/agent-skills/firebase-auth-basics.md) — Guide for setting up and using Firebase Authentication. Use this skill when the user's app requires user sign-in, user management, or secure data access using… 5. [firebase-basics](https://skillsdocs.com/firebase/agent-skills/firebase-basics.md) — Provides foundational Firebase CLI setup, CLI installation, version checks (`firebase-tools@latest --version`), CLI login (including --no-localhost), project c… 6. [firebase-crashlytics](https://skillsdocs.com/firebase/agent-skills/firebase-crashlytics.md) — Comprehensive guide for Firebase Crashlytics, including provisioning and SDK usage. Use this skill when the user needs help setting up Crashlytics, adding cras… 7. [firebase-data-connect](https://skillsdocs.com/firebase/agent-skills/firebase-data-connect-basics.md) — Builds and deploys Firebase SQL Connect (aka Firebase Data Connect) backends with PostgreSQL securely. Use when designing schemas with tables and relations, wr… 8. [firebase-firestore](https://skillsdocs.com/firebase/agent-skills/firebase-firestore.md) — Sets up, manages, queries, and configures Cloud Firestore databases (Standard/Enterprise edition), including data modeling, security rules, indexes, and SDK in… 9. [firebase-hosting-basics](https://skillsdocs.com/firebase/agent-skills/firebase-hosting-basics.md) — Deploys and configures classic Firebase Hosting for static websites, single-page apps (SPAs), and microservices. Use when deploying static sites/SPAs, setting… 10. [firebase-remote-config-basics](https://skillsdocs.com/firebase/agent-skills/firebase-remote-config-basics.md) — Manages Firebase Remote Config templates, feature flags, loading strategies, and SDKs (Android, iOS). Use when downloading/deploying remoteconfig JSON template… 11. [firebase-security-rules-auditor](https://skillsdocs.com/firebase/agent-skills/firebase-security-rules-auditor.md) — Audits Firebase (Firestore, Cloud Storage) security rules for vulnerabilities, privilege escalation, role bypasses, create vs update inconsistencies, resource… 12. [xcode-project-setup](https://skillsdocs.com/firebase/agent-skills/xcode-project-setup.md) — Safely modifies Xcode projects (.pbxproj) to add Swift Packages and link files. Use this skill whenever an iOS project needs dependencies installed (e.g. Fireb… ## Front matter _The repository README, verbatim except that relative links are resolved against https://github.com/firebase/agent-skills/blob/main/._

Logo Firebase Agent Skills

A collection of skills for AI coding agents, to help them understand and work with Firebase more effectively. Skills are packaged instructions and scripts that extend agent capabilities, following the [Agent Skills](https://agentskills.io/home) format. ## Installation ### Option 1: Agent Skills CLI For most popular AI-assistive tools, you can use the `skills` CLI to install Firebase agent skills: ```bash npx skills add firebase/skills ``` ### Option 2: Gemini CLI Extension This repository is configured as a Gemini CLI extension. You can add it using the Gemini CLI: ```bash gemini extensions install https://github.com/firebase/skills ``` ### Option 3: Claude Plugin 1. Add the Firebase marketplace for Claude plugins: ```bash claude plugin marketplace add firebase/skills ``` Install the Claude plugin for Firebase: ```bash claude plugin install firebase@firebase ``` Verify the installation: ```bash claude plugin marketplace list ``` ### Option 4: Codex Plugin Add the Firebase marketplace for Codex plugins: ```bash codex plugin marketplace add firebase/skills ``` Install the Firebase plugin: ```bash codex plugin add firebase@firebase ``` ### Option 5: Kimi Plugin Install the Firebase plugin in Kimi Code CLI: ```bash /plugins install https://github.com/firebase/skills ``` Verify the installation: ```bash /plugins list ``` ### Option 6: Manual Set Up 1. Clone this repository: ```bash git clone https://github.com/firebase/skills.git ``` 2. Copy the contents of the `skills` directory to the appropriate location for your AI tool. Common locations include: - **Cursor**: `.cursor/rules/` - **Windsurf**: `.windsurfrules/` - **GitHub Copilot**: `.github/copilot-instructions.md` (or project-specific instruction files) ### Option 7: Local Path via Agent Skills CLI The `skills` CLI also supports installing skills from a local directory. If you have cloned this repository, you can add skills by pointing the CLI to your local folder: ```bash npx skills add /path/to/your/local/firebase-skills/skills ``` If you make changes to the local skills repository and want to update your project with the new changes, you can update them by running: ```bash npx skills experimental_install ``` ### Option 8: Local Development (Live Symlinking) If you are actively contributing to or developing these skills, using `npx skills add` or copying files means you have to manually update them every time you make a change. Instead, use a symlink so that changes in your local clone are immediately reflected in your test project. For example, to test with Cursor: ```bash ln -s /path/to/firebase-skills/skills /path/to/your/test-project/.cursor/rules ``` ## 🤝 Contributing 1. Fork the repository 1. Create a feature branch: `git checkout -b feature/amazing-feature` 1. Commit changes: `git commit -m 'Add amazing feature'` 1. Push to branch: `git push origin feature/amazing-feature` 1. Open a Pull Request (PR) ## 📄 License This project is licensed under the Apache 2 License - see the [LICENSE](https://github.com/firebase/agent-skills/blob/main/LICENSE) file for details. **Made with ❤️ from Firebase for the AI community** --- ## 1. extension-to-functions-codebase - **Source:** https://github.com/firebase/agent-skills/blob/main/skills/extension-to-functions-codebase/SKILL.md - **Raw:** https://raw.githubusercontent.com/firebase/agent-skills/main/skills/extension-to-functions-codebase/SKILL.md - **Markdown:** https://skillsdocs.com/firebase/agent-skills/extension-to-functions-codebase.md - **Licence:** Apache-2.0 — https://spdx.org/licenses/Apache-2.0.html Bundled files (3), referenced from this skill's directory: - `references/configuration-migration.md` — https://raw.githubusercontent.com/firebase/agent-skills/main/skills/extension-to-functions-codebase/references/configuration-migration.md - `references/destructuring-shim.md` — https://raw.githubusercontent.com/firebase/agent-skills/main/skills/extension-to-functions-codebase/references/destructuring-shim.md - `references/signature-mapping.md` — https://raw.githubusercontent.com/firebase/agent-skills/main/skills/extension-to-functions-codebase/references/signature-mapping.md --- name: extension-to-functions-codebase description: Skill for converting an installed Firebase Extension (or extension source) into a standalone Cloud Functions for Firebase codebase or publishable npm package, including V1 to V2 trigger upgrades, lifecycle hooks, and declarative security metadata: category: Serverless --- # Extension to Functions Codebase & npm Package Migration ## Overview Migrates a Firebase Extension into either: 1. **A local Cloud Functions codebase** (`functions/src/` for app integration). 1. **A publishable npm package** (reusable open-source package exporting V2 functions). Leverages native Cloud Functions features (declarative IAM, Parameterized Config, SDK Lifecycle Hooks) and modernizes 1st Gen triggers to 2nd Gen using the Destructuring Compatibility Shim. ______________________________________________________________________ ## Target Migration Workflows - **Target A: Local Functions Codebase** (End-User App Integration) - Output: Code under `functions/src/`. Config in `.env`. - Deployment: `firebase deploy --only functions`. - **Target B: Publishable npm Package / Shareable Package** - Output: Reusable npm package exporting V2 functions. - Configuration: `package.json` specifying `exports` map, `engines: { "node": ">=22" }`, and `peerDependencies: { "firebase-functions": ">=6.0.0" }`. - Usage: Consumers install package and re-export functions in `index.ts` (`export * from ""`). ______________________________________________________________________ ## Core Rules & Constraints ### 1. Declarative IAM & APIs (Zero-Local-Overhead) Use native SDK declarations instead of manual `gcloud` scripts or console instructions: - Use `requiresRole("roles/...")` for required GCP IAM permissions. - Use `requiresAPI("service.googleapis.com", "Description")` for Google APIs. ### 2. Global Parameter Access Restriction - **Never call `.value()` at top-level module load scope.** - Initialize global SDK instances inside `onInit()` or lazy getters: ```typescript import { defineString } from "firebase-functions/params"; import { onInit } from "firebase-functions/v2"; const dataset = defineString("DATASET_ID"); let client: BigQuery; onInit(() => { client = new BigQuery({ datasetId: dataset.value() }); }); ``` ### 3. V2 Concurrency & Cost Parity V2 enables concurrency (up to 80 requests). To preserve V1 single-concurrency pricing, set `cpu: "gcf_gen1"`. ______________________________________________________________________ ## Step-by-Step Migration Execution ### Step 1: Inventory Extension Resources 1. **`extension.yaml`**: - `params` → `defineString`, `defineInt`, `defineBoolean`, `defineSecret`. - `apis` → `requiresAPI(...)`. - `roles` → `requiresRole(...)`. - `lifecycleEvents` → `afterFirstDeploy` & `afterRedeploy`. - `resources` → Upgrade 1st Gen triggers to 2nd Gen (`onDocumentWritten`, `onTaskDispatched`, `onRequest`). 1. **Files & Scripts**: Preserve devDependencies, test framework (`jest`), and test scripts. ### Step 2: Configure `package.json` - Set `name: ""`, `engines: { "node": ">=22" }`. - Set `peerDependencies`: ```json "peerDependencies": { "firebase-admin": "^11.0.0 || ^12.0.0", "firebase-functions": ">=6.0.0" } ``` - Configure `exports` map targeting ESM/CommonJS and TypeScript declarations (`lib/index.js`, `lib/index.d.ts`). ### Step 3: Upgrade Triggers from V1 to V2 - Firestore: Use `onDocumentWritten` from `firebase-functions/v2/firestore`. - Tasks: Use `onTaskDispatched` from `firebase-functions/v2/tasks`. Remove `EXT_INSTANCE_ID` when enqueueing tasks. - HTTP: Use `onRequest` from `firebase-functions/v2/https`. - Apply Destructuring Compatibility Shim (`{ change, context }`, `{ snapshot, context }`) where legacy 1st Gen handlers expect `(change, context)`. ### Step 4: Convert Lifecycle Events Map extension lifecycle events to SDK lifecycle hooks in `src/index.ts`: - `onInstall` → `afterFirstDeploy({ task: { function: "initTask" } })` - `onUpdate` / `onConfigure` → `afterRedeploy({ task: { function: "setupTask" } })` ### Step 5: Package README & Export Instructions Generate `README.md` containing: 1. Installation instructions (`npm install`). 1. Re-export snippet (`export * from ""`). 1. Parameterized Configuration `.env` reference table. 1. What Changed (Extension vs Package) comparison table. _Reminder: NEVER execute `npm publish`._ --- ## 2. firebase-ai-logic-basics - **Source:** https://github.com/firebase/agent-skills/blob/main/skills/firebase-ai-logic-basics/SKILL.md - **Raw:** https://raw.githubusercontent.com/firebase/agent-skills/main/skills/firebase-ai-logic-basics/SKILL.md - **Markdown:** https://skillsdocs.com/firebase/agent-skills/firebase-ai-logic-basics.md - **Licence:** Apache-2.0 — https://spdx.org/licenses/Apache-2.0.html Bundled files (4), referenced from this skill's directory: - `references/flutter_setup.md` — https://raw.githubusercontent.com/firebase/agent-skills/main/skills/firebase-ai-logic-basics/references/flutter_setup.md - `references/ios_setup.md` — https://raw.githubusercontent.com/firebase/agent-skills/main/skills/firebase-ai-logic-basics/references/ios_setup.md - `references/usage_patterns_android.md` — https://raw.githubusercontent.com/firebase/agent-skills/main/skills/firebase-ai-logic-basics/references/usage_patterns_android.md - `references/usage_patterns_web.md` — https://raw.githubusercontent.com/firebase/agent-skills/main/skills/firebase-ai-logic-basics/references/usage_patterns_web.md --- name: firebase-ai-logic-basics description: Official skill for integrating Firebase AI Logic (Gemini API) into web applications. Covers setup, multimodal inference, structured output, and security. version: 1.0.1 metadata: category: AiAndMachineLearning --- # Firebase AI Logic Basics ## Overview Firebase AI Logic is a product of Firebase that allows developers to add gen AI to their mobile and web apps using client-side SDKs. You can call Gemini models directly from your app without managing a dedicated backend. Firebase AI Logic, which was previously known as "Vertex AI for Firebase", represents the evolution of Google's AI integration platform for mobile and web developers. It supports the two Gemini API providers: - **Gemini Developer API**: It has a free tier ideal for prototyping, and pay-as-you-go for production - **Agent Platform Gemini API** (formerly branded Vertex AI): Ideal for scale with enterprise-grade production readiness, requires Blaze plan Use the Gemini Developer API as a default, and only Agent Platform Gemini API (formerly branded Vertex AI) if the application requires it. ## Setup & Initialization ### Prerequisites - Before starting, ensure you have **Node.js 16+** and npm installed. Install them if they aren’t already available. - Identify the platform the user is interested in building on prior to starting: Android, iOS, Flutter or Web. - If their platform is unsupported, Direct the user to Firebase Docs to learn how to set up AI Logic for their application (share this link with the user https://firebase.google.com/docs/ai-logic/get-started) ### Installation The library is part of the standard Firebase Web SDK. `npm install -g firebase@latest` If you're in a firebase directory (with a firebase.json) the currently selected project will be marked with "current" using this command: `npx -y firebase-tools@latest projects:list` Ensure there's at least one app associated with the current project `npx -y firebase-tools@latest apps:list` Initialize AI logic SDK with the init command `npx -y firebase-tools@latest init ailogic` This will automatically enable the Gemini Developer API in the Firebase console. More info in [Firebase AI Logic Getting Started](https://firebase.google.com/docs/ai-logic/get-started.md.txt) ## Core Capabilities > [!WARNING] **CRITICAL: Use current model names:** Always check the > [Firebase AI Logic Models documentation](https://firebase.google.com/docs/ai-logic/models.md.txt) > for the currently supported model names. Do NOT use `gemini-2.0-pro` or > `gemini-2.0-flash` or other older models that are shutdown. ### Text-Only Generation ### Multimodal (Text + Images/Audio/Video/PDF input) Firebase AI Logic allows Gemini models to analyze image files directly from your app. This enables features like creating captions, answering questions about images, detecting objects, and categorizing images. Beyond images, Gemini can analyze other media types like audio, video, and PDFs by passing them as inline data with their MIME type. For files larger than 20 megabytes (which can cause HTTP 413 errors as inline data), store them in Cloud Storage for Firebase and pass their URLs to the Gemini Developer API. ### Chat Session (Multi-turn) Maintain history automatically using `startChat`. ### Streaming Responses To improve the user experience by showing partial results as they arrive (like a typing effect), use `generateContentStream` instead of `generateContent` for faster display of results. ### Generate Images with Nano Banana > [!WARNING] **Use current Image model names:** Always check the > [Firebase AI Logic Models documentation](https://firebase.google.com/docs/ai-logic/models.md.txt) > for the currently supported image generation (Nano Banana) model names. - Requires an upgraded Blaze pay-as-you-go billing plan. ### Search Grounding with the built in googleSearch tool ## Supported Platforms and Frameworks Supported Platforms and Frameworks include Kotlin and Java for Android, Swift for iOS, JavaScript for web apps, Dart for Flutter, and C Sharp for Unity. ## Advanced Features ### Structured Output (JSON) Enforce a specific JSON schema for the response. ### On-Device AI (Hybrid) Hybrid on-device inference for web apps, where the Firebase Javascript SDK automatically checks for Gemini Nano's availability (after installation) and switches between on-device or cloud-hosted prompt execution. This requires specific steps to enable model usage in the Chrome browser, more info in the [hybrid-on-device-inference documentation](https://firebase.google.com/docs/ai-logic/hybrid-on-device-inference.md.txt). ## Security & Production ### App Check > [!WARNING] **Critical Safety Requirement:** In order to use AI Logic safely, > you MUST set up App Check on your app. This prevents unauthorized clients from > using your API quota and accessing your backend resources. See [App Check with reCAPTCHA Enterprise](https://firebase.google.com/docs/app-check/web/recaptcha-enterprise-provider.md.txt) for setup instructions. #### App Check Debug Tokens for Local Development & CI/CD Because App Check attestation providers (like Play Integrity or DeviceCheck) reject emulators, simulators, or CI environments, you must use **App Check Debug Tokens** during development and testing to bypass standard attestation. ##### Local Development (Auto-Generated) 1. Configure your code's App Check provider to use the debug factory: * **Web**: Set `self.FIREBASE_APPCHECK_DEBUG_TOKEN = true;` before initializing App Check. * **Android**: Install `DebugAppCheckProviderFactory.getInstance()`. * **iOS**: Set provider factory to `AppCheckDebugProviderFactory()`. 2. Run your app in the emulator/localhost. 3. Look at your runtime debugger console / Logcat logs for the generated UUID: * *Example:* `AppCheck debug token: "123a4567-b89c-12d3-e456-789012345678"` 4. Register this token in the Firebase Console under **Security > App Check > Apps > Manage debug tokens**. ##### CI/CD Pipelines (Pre-Provisioned) 1. Generate and register a new debug token in the Firebase Console under **Security > App Check > Apps > Manage debug tokens**. 2. Add this token string as an encrypted secret in your CI system (e.g. `APP_CHECK_DEBUG_TOKEN`). 3. Configure your build to pass this secret as an environment variable to the SDK during test execution (e.g. `self.FIREBASE_APPCHECK_DEBUG_TOKEN = process.env.APP_CHECK_DEBUG_TOKEN`). ### Remote Config Consider that you do not need to hardcode model names (e.g., a specific model version string). Use Firebase Remote Config to update model versions dynamically without deploying new client code. See [Changing model names remotely](https://firebase.google.com/docs/ai-logic/change-model-name-remotely.md.txt) > [!WARNING] **CRITICAL: Backend Provisioning Required** For all platforms > (Flutter, Android, iOS, Web), you MUST run `npx firebase-tools init ailogic` > to provision the service. `flutterfire configure` ONLY handles client > configuration and does NOT enable the AI service, leading to > `PERMISSION_DENIED` errors. ## Initialization Code References | Language, | Gemini API | Context URL | : Framework, : provider : : : Platform : : : | :---------- | :--------- | :---------------------------------------------- | | Web Modular | Gemini | firebase://docs/ai-logic/get-started | : API : Developer : : : : API : : : : (Developer : : : : API) : : | iOS (Swift) | Gemini | [ios_setup.md](references/ios_setup.md) | : : Developer : : : : API : : | Flutter | Gemini | [flutter_setup.md](references/flutter_setup.md) | : (Dart) : Developer : : : : API : : > [!WARNING] **CRITICAL: Use current model names:** Always check the > [Firebase AI Logic Models documentation](https://firebase.google.com/docs/ai-logic/models.md.txt) > for the currently supported model names. Do NOT use `gemini-2.0-pro` or > `gemini-2.0-flash` or other older models that are shutdown. ## References [Web SDK code examples and usage patterns](references/usage_patterns_web.md) [iOS SDK code examples and usage patterns](references/ios_setup.md) [Flutter SDK code examples and usage patterns](references/flutter_setup.md) [Android (Kotlin) SDK usage patterns](references/usage_patterns_android.md) --- ## 3. firebase-app-hosting-basics - **Source:** https://github.com/firebase/agent-skills/blob/main/skills/firebase-app-hosting-basics/SKILL.md - **Raw:** https://raw.githubusercontent.com/firebase/agent-skills/main/skills/firebase-app-hosting-basics/SKILL.md - **Markdown:** https://skillsdocs.com/firebase/agent-skills/firebase-app-hosting-basics.md - **Licence:** Apache-2.0 — https://spdx.org/licenses/Apache-2.0.html Bundled files (3), referenced from this skill's directory: - `references/cli_commands.md` — https://raw.githubusercontent.com/firebase/agent-skills/main/skills/firebase-app-hosting-basics/references/cli_commands.md - `references/configuration.md` — https://raw.githubusercontent.com/firebase/agent-skills/main/skills/firebase-app-hosting-basics/references/configuration.md - `references/emulation.md` — https://raw.githubusercontent.com/firebase/agent-skills/main/skills/firebase-app-hosting-basics/references/emulation.md --- name: firebase-app-hosting-basics description: >- Deploys and manages full-stack web applications (Next.js, Angular) with Server-Side Rendering (SSR) using Firebase App Hosting. Use when deploying Next.js/Angular apps, configuring apphosting.yaml or firebase.json apphosting blocks, managing secrets, setting up GitHub CI/CD, or configuring Blaze billing requirements. Don't use for classic static web hosting, Auth, Firestore, Crashlytics, or Xcode. metadata: category: Serverless --- # App Hosting Basics ## Description This skill enables the agent to deploy and manage modern, full-stack web applications (Next.js, Angular, etc.) using Firebase App Hosting. **Important**: In order to use App Hosting, your Firebase project must be on the Blaze pricing plan. Direct the user to https://console.firebase.google.com/project/_/overview?purchaseBillingPlan=metered to upgrade their plan. ## Hosting vs App Hosting **Choose Firebase Hosting if:** - You are deploying a static site (HTML/CSS/JS). - You are deploying a simple SPA (React, Vue, etc. without SSR). - You want full control over the build and deploy process via CLI. **Choose Firebase App Hosting if:** - You are using a supported full-stack framework like Next.js or Angular. - You need Server-Side Rendering (SSR) or ISR. - You want an automated "git push to deploy" workflow with zero configuration. ## Deploying to App Hosting ### Deploy from Source This is the recommended flow for most users. 1. Configure `firebase.json` with an `apphosting` block. ```json { "apphosting": { "backendId": "my-app-id", "rootDir": "/", "ignore": [ "node_modules", ".git", "firebase-debug.log", "firebase-debug.*.log", "functions" ] } } ``` 1. Create or edit `apphosting.yaml`- see [Configuration](references/configuration.md) for more information on how to do so. 1. If the app needs safe access to sensitive keys, use `npx -y firebase-tools@latest apphosting:secrets` commands to set and grant access to secrets. 1. Run `npx -y firebase-tools@latest deploy` when you are ready to deploy. ### Automated deployment via GitHub (CI/CD) Alternatively, set up a backend connected to a GitHub repository for automated deployments "git push" deployments. This is only recommended for more advanced users, and is not required to use App Hosting. See [CLI Commands](references/cli_commands.md) for more information on how to set this up using CLI commands. ## Emulation See [Emulation](references/emulation.md) for more information on how to test your app locally using the Firebase Local Emulator Suite. --- ## 4. firebase-auth-basics - **Source:** https://github.com/firebase/agent-skills/blob/main/skills/firebase-auth-basics/SKILL.md - **Raw:** https://raw.githubusercontent.com/firebase/agent-skills/main/skills/firebase-auth-basics/SKILL.md - **Markdown:** https://skillsdocs.com/firebase/agent-skills/firebase-auth-basics.md - **Licence:** Apache-2.0 — https://spdx.org/licenses/Apache-2.0.html Bundled files (5), referenced from this skill's directory: - `references/client_sdk_android.md` — https://raw.githubusercontent.com/firebase/agent-skills/main/skills/firebase-auth-basics/references/client_sdk_android.md - `references/client_sdk_web.md` — https://raw.githubusercontent.com/firebase/agent-skills/main/skills/firebase-auth-basics/references/client_sdk_web.md - `references/flutter_setup.md` — https://raw.githubusercontent.com/firebase/agent-skills/main/skills/firebase-auth-basics/references/flutter_setup.md - `references/ios_setup.md` — https://raw.githubusercontent.com/firebase/agent-skills/main/skills/firebase-auth-basics/references/ios_setup.md - `references/security_rules.md` — https://raw.githubusercontent.com/firebase/agent-skills/main/skills/firebase-auth-basics/references/security_rules.md --- name: firebase-auth-basics description: Guide for setting up and using Firebase Authentication. Use this skill when the user's app requires user sign-in, user management, or secure data access using auth rules. compatibility: This skill is best used with the Firebase CLI, but does not require it. Firebase CLI can be accessed through `npx -y firebase-tools@latest`. metadata: category: Identity --- ## Prerequisites - **Firebase Project**: Created via `npx -y firebase-tools@latest projects:create` (see `firebase-basics`). - **Firebase CLI**: Installed and logged in (see `firebase-basics`). ## Core Concepts Firebase Authentication provides backend services, easy-to-use SDKs, and ready-made UI libraries to authenticate users to your app. ### Users A user is an entity that can sign in to your app. Each user is identified by a unique ID (`uid`) which is guaranteed to be unique across all providers. User properties include: - `uid`: Unique identifier. - `email`: User's email address (if available). - `displayName`: User's display name (if available). - `photoURL`: URL to user's photo (if available). - `emailVerified`: Boolean indicating if the email is verified. ### Identity Providers Firebase Auth supports multiple ways to sign in: - **Email/Password**: Basic email and password authentication. - **Federated Identity Providers**: Google, Facebook, Twitter, GitHub, Microsoft, Apple, etc. - **Phone Number**: SMS-based authentication. - **Anonymous**: Temporary guest accounts that can be linked to permanent accounts later. - **Custom Auth**: Integrate with your existing auth system. Google Sign In is recommended as a good and secure default provider. ### Tokens When a user signs in, they receive an ID Token (JWT). This token is used to identify the user when making requests to Firebase services (Realtime Database, Cloud Storage, Firestore) or your own backend. - **ID Token**: Short-lived (1 hour), verifies identity. - **Refresh Token**: Long-lived, used to get new ID tokens. ## Workflow ### 1. Provisioning #### Option 1. Enabling Authentication via CLI Only Google Sign In, anonymous auth, and email/password auth can be enabled via CLI. For other providers, use the Firebase Console. Configure Firebase Authentication in `firebase.json` by adding an 'auth' block: ``` { "auth": { "authorizedDomains": ["localhost"], "providers": { "anonymous": true, "emailPassword": true, "googleSignIn": { "oAuthBrandDisplayName": "Your Brand Name", "supportEmail": "support@example.com" } } } } ``` > [!NOTE] If the Google Sign-In popup opens and immediately closes with the > error `[firebase_auth/unauthorized-domain]`, it means the domain is not > authorized. For local development, ensure `localhost` is included in the > **Authorized Domains** list in the Firebase Console or via the > `authorizedDomains` field in `firebase.json`. **CRITICAL**: Do NOT include the > protocol or port number in the Authorized Domains list (e.g., use `localhost`, > NOT `http://localhost:9090`). **CRITICAL**: After configuring `firebase.json`, you MUST deploy the auth configuration to the Firebase backend for the changes to take effect. This is essential for auth providers like Google Sign-In, email/password, etc. to auto-generate the necessary OAuth clients for your app platforms. Run: ```bash npx -y firebase-tools@latest deploy --only auth ``` #### Option 2. Enabling Authentication in Console Enable other providers in the Firebase Console. 1. Go to the https://console.firebase.google.com/project/_/authentication/providers 1. Select your project. 1. Enable the desired Sign-in providers (e.g., Email/Password, Google). ### 2. Client Setup & Usage **Web** See [references/client_sdk_web.md](references/client_sdk_web.md). **Flutter** See [references/flutter_setup.md](references/flutter_setup.md). **Android (Kotlin)** See [references/client_sdk_android.md](references/client_sdk_android.md). ### 3. Security Rules Secure your data using `request.auth` in Firestore/Storage rules. See [references/security_rules.md](references/security_rules.md). --- ## 5. firebase-basics - **Source:** https://github.com/firebase/agent-skills/blob/main/skills/firebase-basics/SKILL.md - **Raw:** https://raw.githubusercontent.com/firebase/agent-skills/main/skills/firebase-basics/SKILL.md - **Markdown:** https://skillsdocs.com/firebase/agent-skills/firebase-basics.md - **Licence:** Apache-2.0 — https://spdx.org/licenses/Apache-2.0.html Bundled files (19), referenced from this skill's directory: - `references/android_setup.md` — https://raw.githubusercontent.com/firebase/agent-skills/main/skills/firebase-basics/references/android_setup.md - `references/firebase-cli-guide.md` — https://raw.githubusercontent.com/firebase/agent-skills/main/skills/firebase-basics/references/firebase-cli-guide.md - `references/firebase-service-init.md` — https://raw.githubusercontent.com/firebase/agent-skills/main/skills/firebase-basics/references/firebase-service-init.md - `references/flutter_setup.md` — https://raw.githubusercontent.com/firebase/agent-skills/main/skills/firebase-basics/references/flutter_setup.md - `references/ios_setup.md` — https://raw.githubusercontent.com/firebase/agent-skills/main/skills/firebase-basics/references/ios_setup.md - `references/local-env-setup.md` — https://raw.githubusercontent.com/firebase/agent-skills/main/skills/firebase-basics/references/local-env-setup.md - `references/refresh/android_studio.md` — https://raw.githubusercontent.com/firebase/agent-skills/main/skills/firebase-basics/references/refresh/android_studio.md - `references/refresh/antigravity.md` — https://raw.githubusercontent.com/firebase/agent-skills/main/skills/firebase-basics/references/refresh/antigravity.md - `references/refresh/claude.md` — https://raw.githubusercontent.com/firebase/agent-skills/main/skills/firebase-basics/references/refresh/claude.md - `references/refresh/gemini-cli.md` — https://raw.githubusercontent.com/firebase/agent-skills/main/skills/firebase-basics/references/refresh/gemini-cli.md - `references/refresh/other-agents.md` — https://raw.githubusercontent.com/firebase/agent-skills/main/skills/firebase-basics/references/refresh/other-agents.md - `references/setup/android_studio.md` — https://raw.githubusercontent.com/firebase/agent-skills/main/skills/firebase-basics/references/setup/android_studio.md - `references/setup/antigravity.md` — https://raw.githubusercontent.com/firebase/agent-skills/main/skills/firebase-basics/references/setup/antigravity.md - `references/setup/claude_code.md` — https://raw.githubusercontent.com/firebase/agent-skills/main/skills/firebase-basics/references/setup/claude_code.md - `references/setup/cursor.md` — https://raw.githubusercontent.com/firebase/agent-skills/main/skills/firebase-basics/references/setup/cursor.md - `references/setup/gemini_cli.md` — https://raw.githubusercontent.com/firebase/agent-skills/main/skills/firebase-basics/references/setup/gemini_cli.md - `references/setup/github_copilot.md` — https://raw.githubusercontent.com/firebase/agent-skills/main/skills/firebase-basics/references/setup/github_copilot.md - `references/setup/other_agents.md` — https://raw.githubusercontent.com/firebase/agent-skills/main/skills/firebase-basics/references/setup/other_agents.md - `references/web_setup.md` — https://raw.githubusercontent.com/firebase/agent-skills/main/skills/firebase-basics/references/web_setup.md --- name: firebase-basics description: >- Provides foundational Firebase CLI setup, CLI installation, version checks (`firebase-tools@latest --version`), CLI login (including --no-localhost), project creation, project selection (`firebase use`), and app config file downloads (`google-services.json`, `GoogleService-Info.plist`). Use ONLY for CLI login, project creation/switching, or downloading app config files. Don't use for Firebase Hosting deploy, Firestore, Auth, App Hosting, Data Connect, Crashlytics, or Remote Config. metadata: category: CloudInfrastructureAndServices --- # Prerequisites Complete these setup steps before proceeding: 1. **Local Environment Setup:** Verify the environment is properly set up so we can use Firebase tools: - Run `npx -y firebase-tools@latest --version` to check if the Firebase CLI is installed. - Verify if the Firebase MCP server is installed using your existing tools. - **CRITICAL**: Before configuring any extensions or agent environments below, you MUST read [references/local-env-setup.md](references/local-env-setup.md). - **DO NOT SKIP** this step: if 'firebase-basics' is the only Firebase skill available to you, you must follow the reference for your agent environment to set up the full suite of Firebase skills: - **Gemini CLI**: Review [references/setup/gemini_cli.md](references/setup/gemini_cli.md) - **Antigravity**: Review [references/setup/antigravity.md](references/setup/antigravity.md) - **Android Studio**: Review [references/setup/android_studio.md](references/setup/android_studio.md) - **Claude Code**: Review [references/setup/claude_code.md](references/setup/claude_code.md) - **Cursor**: Review [references/setup/cursor.md](references/setup/cursor.md) - **GitHub Copilot**: Review [references/setup/github_copilot.md](references/setup/github_copilot.md) - **Other Agents**: Review [references/setup/other_agents.md](references/setup/other_agents.md) 1. **Authentication:** Ensure you are logged in to Firebase so that commands have the correct permissions. Run `npx -y firebase-tools@latest login`. For environments without a browser (e.g., remote shells), use `npx -y firebase-tools@latest login --no-localhost`. - The command should output the current user. - If you are not logged in, follow the interactive instructions from this command to authenticate. 1. **Active Project:** Most Firebase tasks require an active project context. > [!IMPORTANT] **For Agents:** Before proceeding with project configuration, > you MUST pause and ask the developer if they prefer to: > > 1. **Provide an existing Firebase Project ID**, or > 1. **Create a new Firebase project**. - **If using an existing Project ID:** 1. Check the current project by running `npx -y firebase-tools@latest use`. 1. If the command outputs `Active Project: `, confirm with the user if this is the intended project. 1. If not, or if no project is active, set the project provided by the user: ```bash npx -y firebase-tools@latest use ``` - **If creating a new project:** Run the following command to create it: ```bash npx -y firebase-tools@latest projects:create --display-name "" ``` *Note: The `` must be 6-30 characters, lowercase, and can contain digits and hyphens. It must be globally unique.* # Firebase Usage Principles Adhere to these principles: 1. **Use npx for CLI commands:** To ensure you always use the latest version of the Firebase CLI, always prepend commands with `npx -y firebase-tools@latest` instead of just `firebase`. For example, use `npx -y firebase-tools@latest --version`. NEVER suggest the naked `firebase` command as an alternative. 1. **Prioritize official knowledge:** For any Firebase-related knowledge, consult the `developerknowledge_search_documents` MCP tool before falling back to Google Search or your internal knowledge base. Including "Firebase" in your search query significantly improves relevance. 1. **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. 1. **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. 1. **Keep Plugin / Agent Skills updated:** Since Firebase best practices evolve quickly, regularly check for and install updates to their Firebase plugin or Agent Skills. Similarly, if you encounter issues with outdated tools or commands, follow the steps below based on your agent environment: - **Antigravity**: Follow [references/refresh/antigravity.md](references/refresh/antigravity.md) - **Gemini CLI**: Follow [references/refresh/gemini-cli.md](references/refresh/gemini-cli.md) - **Claude Code**: Follow [references/refresh/claude.md](references/refresh/claude.md) - **Cursor**: Follow [references/refresh/other-agents.md](references/refresh/other-agents.md) - **Android Studio**: Follow [references/refresh/android_studio.md](references/refresh/android_studio.md) - **Others**: Follow [references/refresh/other-agents.md](references/refresh/other-agents.md) 1. **Automate Config File Retrieval:** When setting up iOS or Android apps, do NOT direct users to the Firebase Console to download `google-services.json` or `GoogleService-Info.plist`. Instead, use the Firebase CLI to fetch the config programmatically: - For Android: `npx -y firebase-tools@latest apps:sdkconfig ANDROID --project ` - For iOS: `npx -y firebase-tools@latest apps:sdkconfig IOS --project ` Save the output to the appropriate location (e.g., `app/google-services.json` for Android, or a path to be linked by `xcode-project-setup` for iOS). # References - **Initialize Firebase:** See [references/firebase-service-init.md](references/firebase-service-init.md) when you need to initialize new Firebase services using the CLI. - **Exploring Commands:** See [references/firebase-cli-guide.md](references/firebase-cli-guide.md) to discover and understand CLI functionality. - **SDK Setup:** For detailed guides on adding Firebase to your app: - **Web**: See [references/web_setup.md](references/web_setup.md) - **Android**: See [references/android_setup.md](references/android_setup.md) - **iOS**: See [references/ios_setup.md](references/ios_setup.md) # Common Issues - **Login Issues:** If the browser fails to open during the login step, use `npx -y firebase-tools@latest login --no-localhost` instead. - **Genkit:** If using Genkit, install the skills: ```bash npx skills add genkit-ai/skills ``` --- ## 6. firebase-crashlytics - **Source:** https://github.com/firebase/agent-skills/blob/main/skills/firebase-crashlytics/SKILL.md - **Raw:** https://raw.githubusercontent.com/firebase/agent-skills/main/skills/firebase-crashlytics/SKILL.md - **Markdown:** https://skillsdocs.com/firebase/agent-skills/firebase-crashlytics.md - **Licence:** Apache-2.0 — https://spdx.org/licenses/Apache-2.0.html Bundled files (2), referenced from this skill's directory: - `references/android_setup.md` — https://raw.githubusercontent.com/firebase/agent-skills/main/skills/firebase-crashlytics/references/android_setup.md - `references/ios_setup.md` — https://raw.githubusercontent.com/firebase/agent-skills/main/skills/firebase-crashlytics/references/ios_setup.md --- name: firebase-crashlytics description: Comprehensive guide for Firebase Crashlytics, including provisioning and SDK usage. Use this skill when the user needs help setting up Crashlytics, adding crash reporting, or using the Crashlytics SDK in their application. compatibility: This skill is best used with the Firebase CLI, but does not require it. Firebase CLI can be accessed through `npx -y firebase-tools@latest`. metadata: category: CloudObservabilityAndMonitoring --- # Crashlytics This skill provides a complete guide for getting started with Crashlytics on Android or iOS. Crash data collected from client applications can be read using the MCP server in the Firebase CLI. ## Prerequisites Provisioning Crashlytics requires both a Firebase project and a Firebase app, either Android or iOS. To read the data collected by Crashlytics, install the MCP server in the Firebase CLI. See the `firebase-basics` skill for references. ## SDK Setup To learn how to setup Crashlytics in your application code, choose your platform: - **Android**: [android_setup.md](references/android_setup.md) - **iOS**: [ios_setup.md](references/ios_setup.md) ## SDK Usage The SDK provides a number of features to make crash reports more actionable. - Add custom keys - Add custom logs - Set user identifiers - Report non-fatal exceptions To learn how to customize crash reports and add additional debugging data, consult the documentation for your platform. - **Android**: [Customize Crash Reports for Android](https://firebase.google.com/docs/crashlytics/android/customize-crash-reports.md) - **iOS**: [Customize Crash Reports for Apple Platforms](https://firebase.google.com/docs/crashlytics/ios/customize-crash-reports.md) --- ## 7. firebase-data-connect - **Source:** https://github.com/firebase/agent-skills/blob/main/skills/firebase-data-connect-basics/SKILL.md - **Raw:** https://raw.githubusercontent.com/firebase/agent-skills/main/skills/firebase-data-connect-basics/SKILL.md - **Markdown:** https://skillsdocs.com/firebase/agent-skills/firebase-data-connect-basics.md - **Licence:** Apache-2.0 — https://spdx.org/licenses/Apache-2.0.html Bundled files (16), referenced from this skill's directory: - `examples.md` — https://raw.githubusercontent.com/firebase/agent-skills/main/skills/firebase-data-connect-basics/examples.md - `reference/cloud_functions.md` — https://raw.githubusercontent.com/firebase/agent-skills/main/skills/firebase-data-connect-basics/reference/cloud_functions.md - `reference/config.md` — https://raw.githubusercontent.com/firebase/agent-skills/main/skills/firebase-data-connect-basics/reference/config.md - `reference/data_seeding.md` — https://raw.githubusercontent.com/firebase/agent-skills/main/skills/firebase-data-connect-basics/reference/data_seeding.md - `reference/native_sql.md` — https://raw.githubusercontent.com/firebase/agent-skills/main/skills/firebase-data-connect-basics/reference/native_sql.md - `reference/operations.md` — https://raw.githubusercontent.com/firebase/agent-skills/main/skills/firebase-data-connect-basics/reference/operations.md - `reference/realtime.md` — https://raw.githubusercontent.com/firebase/agent-skills/main/skills/firebase-data-connect-basics/reference/realtime.md - `reference/schema.md` — https://raw.githubusercontent.com/firebase/agent-skills/main/skills/firebase-data-connect-basics/reference/schema.md - `reference/sdk_admin_node.md` — https://raw.githubusercontent.com/firebase/agent-skills/main/skills/firebase-data-connect-basics/reference/sdk_admin_node.md - `reference/sdk_android.md` — https://raw.githubusercontent.com/firebase/agent-skills/main/skills/firebase-data-connect-basics/reference/sdk_android.md - `reference/sdk_flutter.md` — https://raw.githubusercontent.com/firebase/agent-skills/main/skills/firebase-data-connect-basics/reference/sdk_flutter.md - `reference/sdk_ios.md` — https://raw.githubusercontent.com/firebase/agent-skills/main/skills/firebase-data-connect-basics/reference/sdk_ios.md - `reference/sdk_web.md` — https://raw.githubusercontent.com/firebase/agent-skills/main/skills/firebase-data-connect-basics/reference/sdk_web.md - `reference/search.md` — https://raw.githubusercontent.com/firebase/agent-skills/main/skills/firebase-data-connect-basics/reference/search.md - `reference/security.md` — https://raw.githubusercontent.com/firebase/agent-skills/main/skills/firebase-data-connect-basics/reference/security.md - `templates.md` — https://raw.githubusercontent.com/firebase/agent-skills/main/skills/firebase-data-connect-basics/templates.md --- name: firebase-data-connect description: Builds and deploys Firebase SQL Connect (aka Firebase Data Connect) backends with PostgreSQL securely. Use when designing schemas with tables and relations, writing authorized queries and mutations, configuring real-time data updates, or generating type-safe SDKs. Use when you need a relational database with Firebase, or when the user mentions SQL Connect or Data Connect. metadata: category: Databases --- # Firebase SQL Connect Firebase SQL Connect is a relational database service using Cloud SQL for PostgreSQL with GraphQL schema, auto-generated queries/mutations, and type-safe SDKs. > [!NOTE] **Product Rename**: Firebase Data Connect was renamed to **Firebase > SQL Connect**. All instructions, references, and examples in this skill > repository referring to "Data Connect" or "Firebase Data Connect" apply to > "SQL Connect" and "Firebase SQL Connect" as well. ## Project Structure ```text dataconnect/ ├── dataconnect.yaml # Service configuration ├── seed_data.gql # LOCAL ONLY — prototype/test data ├── schema/ │ └── schema.gql # Data model (types with @table) └── connector/ ├── connector.yaml # Connector config + SDK generation ├── queries.gql # Queries └── mutations.gql # Mutations ``` ## Key Tools for Validation Rely on these two mechanisms to ensure project correctness: 1. **Review GraphQL Schema**: Both user-defined and generated extensions (in `.dataconnect/schema/main/`). 1. **Validate Operations**: Run `npx -y firebase-tools@latest dataconnect:compile` against the schema. ## Operation Strategies: GraphQL vs. Native SQL Always default to **Native GraphQL**. **Native SQL lacks type safety** and bypasses schema-enforced structures. Only use **Native SQL** when the user explicitly requests it or when the task requires advanced database features. | Strategy | When to use | Implementation | | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | | **Native GraphQL** (Default) | Almost all use cases. Standard CRUD, basic filtering/sorting, simple relational joins. Requires full type safety. | Auto-generated fields (`movie_insert`, `movies`). Strong typing and schema enforcement. | | **Native SQL** (Advanced) | PostgreSQL extensions (e.g., PostGIS), window functions (`RANK()`), complex aggregations, or highly tuned sub-queries. | Raw SQL string literals via `_select`, `_execute`, etc. Requires strict positional parameters (`$1`). No type safety. | ## Development Workflow Follow this strict workflow to build your application. You **must** read the linked reference files for each step to understand the syntax and available features. ### 1. Define Data Model (`schema/schema.gql`) Define your GraphQL types, tables, and relationships (which map to a Postgres schema). > **Read [reference/schema.md](reference/schema.md)** for: > > - `@table`, `@col`, `@default` > - Relationships (`@ref`, one-to-many, many-to-many) > - Data types (UUID, Vector, JSON, etc.) ### 2. Define Authorized Operations (`connector/queries.gql`, `connector/mutations.gql`) Write the queries and mutations your client will use, including authorization logic. SQL Connect is secure by default. > **Read [reference/operations.md](reference/operations.md)** for: > > - **Queries**: Filtering (`where`), Ordering (`orderBy`), Pagination > (`limit`/`offset`). > - **Mutations**: Create (`_insert`), Update (`_update`), Delete (`_delete`). > - **Upserts**: Use `_upsert` to "insert or update" records (CRITICAL for user > profiles). > - **Transactions**: Use `@transaction` for multi-step atomic operations. Use > `_expr: "response."` to pass data between steps. > > **Read [reference/security.md](reference/security.md)** for authorization: > > - `@auth(level: ...)` for PUBLIC, USER, or NO_ACCESS. > - `@check` and `@redact` for row-level security and validation. > > **Read [reference/realtime.md](reference/realtime.md)** for real-time > subscriptions: > > - `@refresh` directive for time-based polling and event-driven updates. > - CEL conditions to scope refresh triggers precisely. > > **Read [reference/native_sql.md](reference/native_sql.md)** for Native SQL > operations: > > - Embedding raw SQL with `_select`, `_selectFirst`, `_execute` > - Strict rules for positional parameters (`$1`, `$2`), quoting, and CTEs > - Advanced PostgreSQL features (PostGIS, Window Functions) ### 3. Use type-safe SDK in your apps Generate type-safe code for your client platform. Configure SDK generation in `connector.yaml`: ```yaml connectorId: my-connector generate: javascriptSdk: outputDir: "../web-app/src/lib/dataconnect" package: "@movie-app/dataconnect" kotlinSdk: outputDir: "../android-app/app/src/main/kotlin/com/example/dataconnect" package: "com.example.dataconnect" swiftSdk: outputDir: "../ios-app/DataConnect" ``` Generate SDKs: ```bash npx -y firebase-tools@latest dataconnect:sdk:generate ``` For platform-specific instructions on how to use the generated SDKs, read: - **Web (TypeScript)**: [reference/sdk_web.md](reference/sdk_web.md) - **Android (Kotlin)**: [reference/sdk_android.md](reference/sdk_android.md) - **iOS (Swift)**: [reference/sdk_ios.md](reference/sdk_ios.md) - **Admin (Node.js)**: [reference/sdk_admin_node.md](reference/sdk_admin_node.md) - **Flutter (Dart)**: [reference/sdk_flutter.md](reference/sdk_flutter.md) ______________________________________________________________________ ## Feature Capability Map If you need to implement a specific feature, consult the mapped reference file: | Feature | Reference File | Key Concepts | | :------------------------------ | :----------------------------------------------------------- | :------------------------------------------------- | | **Data Modeling** | [reference/schema.md](reference/schema.md) | `@table`, `@unique`, `@index`, Relations | | **Vector Search** | [reference/search.md](reference/search.md) | `Vector`, `@col(dataType: "vector")`, embeddings | | **Full-Text Search** | [reference/search.md](reference/search.md) | `@searchable`, `movies_search` | | **Upserting Data** | [reference/operations.md](reference/operations.md) | `_upsert` mutations | | **Complex Filters** | [reference/operations.md](reference/operations.md) | `_or`, `_and`, `_not`, `eq`, `contains` | | **Transactions** | [reference/operations.md](reference/operations.md) | `@transaction`, `response` binding | | **Environment Config** | [reference/config.md](reference/config.md) | `dataconnect.yaml`, `connector.yaml` | | **Realtime Subscriptions** | [reference/realtime.md](reference/realtime.md) | `@refresh`, `subscribe()`, auto-refresh | | **Cloud Functions Integration** | [reference/cloud_functions.md](reference/cloud_functions.md) | `onMutationExecuted`, triggering events | | **Data Seeding & Migrations** | [reference/data_seeding.md](reference/data_seeding.md) | `seed_data.gql`, `_insertMany`, Admin SDK bulk | | **Starter Templates** | [templates.md](templates.md) | CRUD, user-owned resources, many-to-many, SDK init | ______________________________________________________________________ ## Deployment & CLI > **Read [reference/config.md](reference/config.md)** for deep dive on > configuration. Follow these patterns based on your current task: ### How to initialize SQL Connect in a Firebase project 1. Understand the app idea. Ask clarification questions if unclear. 1. Run `npx -y firebase-tools@latest init dataconnect`. 1. Validate that the app template and generated SDK are setup. ### How to build apps using SQL Connect locally 1. Start the emulator: `npx -y firebase-tools@latest emulators:start --only dataconnect`. 1. Write schema and operations. 1. Seed local test data into `seed_data.gql`. Read [reference/data_seeding.md](reference/data_seeding.md#local-prototyping-data-seeding). 1. Run `npx -y firebase-tools@latest dataconnect:compile` or `npx -y firebase-tools@latest dataconnect:sdk:generate` to validate them. 1. Use the operations in your app and build it. ### How to deploy SQL Connect to Cloud SQL 1. Run `npx -y firebase-tools@latest deploy --only dataconnect`. ## Examples For complete, working code examples of schemas and operations, see **[examples.md](examples.md)**. For ready-to-use starter templates (CRUD, user-owned resources, many-to-many, YAML configs, SDK init), see **[templates.md](templates.md)**. --- ## 8. firebase-firestore - **Source:** https://github.com/firebase/agent-skills/blob/main/skills/firebase-firestore/SKILL.md - **Raw:** https://raw.githubusercontent.com/firebase/agent-skills/main/skills/firebase-firestore/SKILL.md - **Markdown:** https://skillsdocs.com/firebase/agent-skills/firebase-firestore.md - **Licence:** Apache-2.0 — https://spdx.org/licenses/Apache-2.0.html Bundled files (16), referenced from this skill's directory: - `references/enterprise/android_sdk_usage.md` — https://raw.githubusercontent.com/firebase/agent-skills/main/skills/firebase-firestore/references/enterprise/android_sdk_usage.md - `references/enterprise/data_model.md` — https://raw.githubusercontent.com/firebase/agent-skills/main/skills/firebase-firestore/references/enterprise/data_model.md - `references/enterprise/flutter_setup.md` — https://raw.githubusercontent.com/firebase/agent-skills/main/skills/firebase-firestore/references/enterprise/flutter_setup.md - `references/enterprise/indexes.md` — https://raw.githubusercontent.com/firebase/agent-skills/main/skills/firebase-firestore/references/enterprise/indexes.md - `references/enterprise/ios_setup.md` — https://raw.githubusercontent.com/firebase/agent-skills/main/skills/firebase-firestore/references/enterprise/ios_setup.md - `references/enterprise/provisioning.md` — https://raw.githubusercontent.com/firebase/agent-skills/main/skills/firebase-firestore/references/enterprise/provisioning.md - `references/enterprise/python_sdk_usage.md` — https://raw.githubusercontent.com/firebase/agent-skills/main/skills/firebase-firestore/references/enterprise/python_sdk_usage.md - `references/enterprise/security_rules.md` — https://raw.githubusercontent.com/firebase/agent-skills/main/skills/firebase-firestore/references/enterprise/security_rules.md - `references/enterprise/web_sdk_usage.md` — https://raw.githubusercontent.com/firebase/agent-skills/main/skills/firebase-firestore/references/enterprise/web_sdk_usage.md - `references/standard/android_sdk_usage.md` — https://raw.githubusercontent.com/firebase/agent-skills/main/skills/firebase-firestore/references/standard/android_sdk_usage.md - `references/standard/flutter_setup.md` — https://raw.githubusercontent.com/firebase/agent-skills/main/skills/firebase-firestore/references/standard/flutter_setup.md - `references/standard/indexes.md` — https://raw.githubusercontent.com/firebase/agent-skills/main/skills/firebase-firestore/references/standard/indexes.md - `references/standard/ios_setup.md` — https://raw.githubusercontent.com/firebase/agent-skills/main/skills/firebase-firestore/references/standard/ios_setup.md - `references/standard/provisioning.md` — https://raw.githubusercontent.com/firebase/agent-skills/main/skills/firebase-firestore/references/standard/provisioning.md - `references/standard/security_rules.md` — https://raw.githubusercontent.com/firebase/agent-skills/main/skills/firebase-firestore/references/standard/security_rules.md - `references/standard/web_sdk_usage.md` — https://raw.githubusercontent.com/firebase/agent-skills/main/skills/firebase-firestore/references/standard/web_sdk_usage.md --- name: firebase-firestore description: >- Sets up, manages, queries, and configures Cloud Firestore databases (Standard/Enterprise edition), including data modeling, security rules, indexes, and SDK integrations (Web, Python, iOS, Android, Flutter). Use when creating/listing Firestore databases, defining data models/indexes, writing SDK queries, or integrating Firestore SDKs. Don't use for Firebase Hosting, Data Connect, Auth, Storage/GCS, Crashlytics, Functions, or BigQuery. compatibility: This skill is best used with the Firebase CLI, but does not require it. Firebase CLI can be accessed through `npx -y firebase-tools@latest`. metadata: category: Databases --- # Cloud Firestore Database and Operations Before setting up dependencies, writing data models, or configuring security rules, you MUST always identify the Firestore instance edition. ## 1. Instance Selection and Edition Detection Run the following command to list current Firestore databases: `bash npx -y firebase-tools@latest firestore:databases:list` ### A. Instance Found 1. For each database found, inspect its edition and details: `bash npx -y firebase-tools@latest firestore:databases:get ` 1. Ask the user which database instance they wish to target or if they would prefer to create a new instance. 1. Once the target instance is established: - If the **`edition`** is `STANDARD`, follow the guides under `references/standard/`. - If the **`edition`** is `ENTERPRISE` or native mode, follow the guides under `references/enterprise/`. ### B. No Instance Found (or New Requested) If no databases exist or the user requests a new one, default to provisioning an **Enterprise** edition database and ask the user what location to use. Run `npx -y firebase-tools@latest firestore:locations` to get the list of options. Suggest colocating with other resources if applicable. Once the location is determined, create the database: `bash npx -y firebase-tools@latest firestore:databases:create --edition="enterprise" --location=""` Proceed with using the guides under `references/enterprise/`. ______________________________________________________________________ ## 2. Specialized Guides Based on the identified or created instance edition, open and read the corresponding reference guides: ### Standard Edition (`references/standard/`) - **Provisioning**: Read [provisioning.md](references/standard/provisioning.md) - **Security Rules**: Read [security_rules.md](references/standard/security_rules.md) - **SDK Usage**: Read [web_sdk_usage.md](references/standard/web_sdk_usage.md), [android_sdk_usage.md](references/standard/android_sdk_usage.md), [ios_setup.md](references/standard/ios_setup.md), or [flutter_setup.md](references/standard/flutter_setup.md) - **Indexes**: Read [indexes.md](references/standard/indexes.md) ### Enterprise Edition / Native Mode (`references/enterprise/`) - **Provisioning**: Read [provisioning.md](references/enterprise/provisioning.md) - **Data Model**: Read [data_model.md](references/enterprise/data_model.md) - **Security Rules**: Read [security_rules.md](references/enterprise/security_rules.md) - **SDK Usage**: > [!CRITICAL] **Mandatory Reference Reading** Before writing or modifying any > application code for Firestore Enterprise Edition, you **MUST** read at > least one of the relevant reference documents below for the target > platform/language to understand specific architectural requirements and > pipeline initialization patterns. Read [web_sdk_usage.md](references/enterprise/web_sdk_usage.md), [python_sdk_usage.md](references/enterprise/python_sdk_usage.md), [android_sdk_usage.md](references/enterprise/android_sdk_usage.md), [ios_setup.md](references/enterprise/ios_setup.md), or [flutter_setup.md](references/enterprise/flutter_setup.md) - **Indexes**: Read [indexes.md](references/enterprise/indexes.md) --- ## 9. firebase-hosting-basics - **Source:** https://github.com/firebase/agent-skills/blob/main/skills/firebase-hosting-basics/SKILL.md - **Raw:** https://raw.githubusercontent.com/firebase/agent-skills/main/skills/firebase-hosting-basics/SKILL.md - **Markdown:** https://skillsdocs.com/firebase/agent-skills/firebase-hosting-basics.md - **Licence:** Apache-2.0 — https://spdx.org/licenses/Apache-2.0.html Bundled files (2), referenced from this skill's directory: - `references/configuration.md` — https://raw.githubusercontent.com/firebase/agent-skills/main/skills/firebase-hosting-basics/references/configuration.md - `references/deploying.md` — https://raw.githubusercontent.com/firebase/agent-skills/main/skills/firebase-hosting-basics/references/deploying.md --- name: firebase-hosting-basics description: >- Deploys and configures classic Firebase Hosting for static websites, single-page apps (SPAs), and microservices. Use when deploying static sites/SPAs, setting up custom domains, configuring firebase.json hosting settings (redirects, rewrites, headers, multi-site), or managing preview channels. Don't use for Firebase App Hosting (Next.js/SSR), Auth, Firestore queries/rules, Data Connect, or Crashlytics. metadata: category: Serverless --- # hosting-basics This skill provides instructions and references for working with Firebase Hosting, a fast and secure hosting service for your web app, static and dynamic content, and microservices. ## Overview Firebase Hosting provides production-grade web content hosting for developers. With a single command, you can deploy web apps and serve both static and dynamic content to a global CDN (content delivery network). **Key Features:** - **Fast Content Delivery:** Files are cached on SSDs at CDN edges around the world. - **Secure by Default:** Zero-configuration SSL is built-in. - **Preview Channels:** View and test changes on temporary preview URLs before deploying live. - **GitHub Integration:** Automate previews and deploys with GitHub Actions. - **Dynamic Content:** Serve dynamic content and microservices using Cloud Functions or Cloud Run. ## Hosting vs App Hosting **Choose Firebase Hosting if:** - You are deploying a static site (HTML/CSS/JS). - You are deploying a simple SPA (React, Vue, etc. without SSR). - You want full control over the build and deploy process via CLI. **Choose Firebase App Hosting if:** - You are using a supported full-stack framework like Next.js or Angular. - You need Server-Side Rendering (SSR) or ISR. - You want an automated "git push to deploy" workflow with zero configuration. ## Instructions ### 1. Configuration (`firebase.json`) For details on configuring Hosting behavior, including public directories, redirects, rewrites, and headers, see [configuration.md](references/configuration.md). ### 2. Deploying For instructions on deploying your site, using preview channels, and managing releases, see [deploying.md](references/deploying.md). ### 3. Emulation To test your app locally: ```bash npx -y firebase-tools@latest emulators:start --only hosting ``` This serves your app at `http://localhost:5000` by default. --- ## 10. firebase-remote-config-basics - **Source:** https://github.com/firebase/agent-skills/blob/main/skills/firebase-remote-config-basics/SKILL.md - **Raw:** https://raw.githubusercontent.com/firebase/agent-skills/main/skills/firebase-remote-config-basics/SKILL.md - **Markdown:** https://skillsdocs.com/firebase/agent-skills/firebase-remote-config-basics.md - **Licence:** Apache-2.0 — https://spdx.org/licenses/Apache-2.0.html Bundled files (2), referenced from this skill's directory: - `references/android_setup.md` — https://raw.githubusercontent.com/firebase/agent-skills/main/skills/firebase-remote-config-basics/references/android_setup.md - `references/ios_setup.md` — https://raw.githubusercontent.com/firebase/agent-skills/main/skills/firebase-remote-config-basics/references/ios_setup.md --- name: firebase-remote-config-basics description: >- Manages Firebase Remote Config templates, feature flags, loading strategies, and SDKs (Android, iOS). Use when downloading/deploying remoteconfig JSON templates, managing version history/feature flags, setting in-app defaults, fetchAndActivate(), real-time listeners, or SDK setup. Don't use for Firebase Hosting, Auth, Firestore, Data Connect, Crashlytics, or App Hosting. compatibility: This skill is best used with the Firebase CLI, but does not require it. Firebase CLI can be accessed through `npx -y firebase-tools@latest`. metadata: category: ApplicationDevelopment --- # Remote Config This skill provides a complete guide for getting started with Remote Config on Android or iOS. Remote Config allows you to change the behavior and appearance of your app without publishing an app update by maintaining a cloud-based configuration template. ## Prerequisites Provisioning Remote Config requires both a Firebase project and a Firebase app, either Android or iOS. To manage the Remote Config template and conditions via the command line, use the Firebase CLI. See the `firebase-basics` skill for references on project initialization. ## Troubleshooting Execution ### Handling npx 403 Forbidden Errors If `npx -y firebase-tools@latest` fails due to registry permissions (403 error): 1. **Inform the user**: "I am unable to fetch the latest Firebase tools via npx due to a registry error." 1. **Fallback**: Attempt to use the local `firebase` command directly if the user confirms it is installed globally (`npm install -g firebase-tools`). ### Handling Project Context Issues If a command fails because "no active project is selected": 1. **Check login**: Run `npx -y firebase-tools@latest login:list`. 1. **Prompt for ID**: If logged in but no project is active, ask the user: "Please provide your Firebase Project ID to proceed." 1. **Use Flag**: Append `--project ` to every subsequent command. ## SDK Setup To learn how to set up Remote Config in your application code, choose your platform: - **Android**: [android_setup.md](references/android_setup.md) - **iOS**: [ios_setup.md](references/ios_setup.md) ## Best Practices and Template Management Follow these guidelines and use the associated CLI tools to ensure efficient and safe use of Remote Config. ### Fetching Strategies To optimize app performance and user experience, follow these recommended patterns (see [Loading Strategies](https://firebase.google.com/docs/remote-config/loading)): - **Load new values for next startup**: The most effective pattern is to activate previously fetched values immediately on startup and fetch new values in the background to be used next time. This minimizes user wait time. - **Real-time Updates**: Use the SDK's real-time listener to update the app instantly without a refresh when server-side configuration changes. ### Template Management via CLI Use the following commands to manage your Remote Config template and version history through the terminal: ### Template Management via CLI Use the following commands to manage your Remote Config template and version history through the terminal: - **Get current template**: Save the remote template to a local JSON file for auditing or modification. ```bash npx -y firebase-tools@latest remoteconfig:get -o remote_config.json ``` - **Autonomous Editing & Discovery** : Modify the local `remote_config.json` directly. Determine the correct signal (e.g., device.country or percent) and update the "conditions" array and "parameters" map accordingly. - **MANDATORY: User Review and Verification** : STOP and ask the user to verify your changes before proceeding to deployment. - Action: Inform the user: "I have prepared the changes in remote_config.json. Please review the file for accuracy. Once you are satisfied, tell me to 'deploy' to make the changes live." - **Deployment Orchestration** : To push changes, you must ensure the environment is configured for deployment. - Config Mapping: If a firebase.json file is missing, create one to map the local JSON to the Remote Config service: ```json { "remoteconfig": { "template": "remote_config.json" } } ``` - Deploy: Execute the partial deployment command ```bash npx -y firebase-tools@latest deploy --only remoteconfig ``` - **Verification**: After deployment, verify the update by listing the version history. ```bash npx -y firebase-tools@latest remoteconfig:versions:list ``` The SDK provides a number of features to make your application dynamic and responsive to user segments. - **Set In-App Defaults**: Define baseline values to ensure the app functions offline or before the first fetch. - **Fetch and Activate**: Retrieve values from the Firebase backend and apply them to the local UI/Logic. - **Template Management**: Use the Firebase CLI to version-control, get, and deploy your config JSON files. --- ## 11. firebase-security-rules-auditor - **Source:** https://github.com/firebase/agent-skills/blob/main/skills/firebase-security-rules-auditor/SKILL.md - **Raw:** https://raw.githubusercontent.com/firebase/agent-skills/main/skills/firebase-security-rules-auditor/SKILL.md - **Markdown:** https://skillsdocs.com/firebase/agent-skills/firebase-security-rules-auditor.md - **Licence:** Apache-2.0 — https://spdx.org/licenses/Apache-2.0.html --- name: firebase-security-rules-auditor description: >- Audits Firebase (Firestore, Cloud Storage) security rules for vulnerabilities, privilege escalation, role bypasses, create vs update inconsistencies, resource exhaustion, type safety, size limits, and hasOnly ownership checks. Use when auditing/reviewing rules, running red-team rule assessments, or scoring against auditor checklists. Don't use for Firebase CLI (login, deploy), Auth, Crashlytics, Remote Config, or database queries. metadata: category: CloudSecurity --- # Overview This skill acts as an auditor for Firebase Security Rules, evaluating them against a rigorous set of criteria to ensure they are secure, robust, and correctly implemented. # Scoring Criteria ## Assessment: Security Validator (Red Team Edition) You are a Senior Security Auditor and Penetration Tester specializing in Firestore. Your goal is to find "the hole in the wall." Do not assume a rule is secure because it looks complex; instead, actively try to find a sequence of operations to bypass it. ### Mandatory Audit Checklist: 1. **The Update Bypass:** Compare 'create' and 'update' rules. Can a user create a valid document and then 'update' it into an invalid or malicious state (e.g., changing their role, bypassing size limits, or corrupting data types)? 1. **Authority Source:** Does the security rely on user-provided data (request.resource.data) for sensitive fields like 'role', 'isAdmin', or 'ownerId'? Carefully consider the source for that authority. 1. **Business Logic vs. Rules:** Does the rule set actually support the app's purpose? (e.g., In a collaboration app, can collaborators actually read the data? If not, the rules are "broken" or will force insecure workarounds). 1. **Storage Abuse:** Are there string length or array size limits? If not, label it as a "Resource Exhaustion/DoS" risk. 1. **Type Safety:** Are fields checked with 'is string', 'is int', or 'is timestamp'? 1. **Field-Level vs. Identity-Level Security:** Be careful with rules that use \`hasOnly()\` or \`diff()\`. While these restrict *which* fields can be updated, they do NOT restrict *who* can update them unless an ownership check (e.g., \`resource.data.uid == request.auth.uid\`) is also present. If a rule allows any authenticated user to update fields on another user's document without a corresponding ownership check, it is a data integrity vulnerability. ### Admin Bootstrapping & Privileges: The admin bootstrapping process is limited in this app. If the rules use a single hardcoded admin email (e.g., checking request.auth.token.email == 'admin@example.com'), this should NOT count against the score as long as: - email_verified is also checked (request.auth.token.email_verified == true). - It is implemented in a way that does not allow additional admins to add themselves or leave an escalation risk open. ### Scoring Criteria (1-5): - **1 (Critical):** Unauthorized data access (leaks), privilege escalation, or total validation bypass. - **2 (Major):** Broken business logic, self-assigned roles, bypass of controls. - **3 (Moderate):** PII exposure (e.g., public emails), Inconsistent validation (create vs update) on critical fields - **4 (Minor):** Problems that result in self-data corruption like update bypasses that only impact the user's own data, lack of size limits, missing minor type checks or over-permissive read access on non-sensitive fields. - **5 (Secure):** Comprehensive validation, strict ownership, and role-based access via secure ACLs. Return your assessment in JSON format using the following structure: { "score": 1-5, "summary": "overall assessment", "findings": \[ { "check": "checklist item", "severity": "critical|major|moderate|minor", "issue": "description", "recommendation": "fix" } \] } --- ## 12. xcode-project-setup - **Source:** https://github.com/firebase/agent-skills/blob/main/skills/xcode-project-setup/SKILL.md - **Raw:** https://raw.githubusercontent.com/firebase/agent-skills/main/skills/xcode-project-setup/SKILL.md - **Markdown:** https://skillsdocs.com/firebase/agent-skills/xcode-project-setup.md - **Licence:** Apache-2.0 — https://spdx.org/licenses/Apache-2.0.html Bundled files (4), referenced from this skill's directory: - `scripts/xcode_spm_setup/.gitignore` — https://raw.githubusercontent.com/firebase/agent-skills/main/skills/xcode-project-setup/scripts/xcode_spm_setup/.gitignore - `scripts/xcode_spm_setup/Package.resolved` — https://raw.githubusercontent.com/firebase/agent-skills/main/skills/xcode-project-setup/scripts/xcode_spm_setup/Package.resolved - `scripts/xcode_spm_setup/Package.swift` — https://raw.githubusercontent.com/firebase/agent-skills/main/skills/xcode-project-setup/scripts/xcode_spm_setup/Package.swift - `scripts/xcode_spm_setup/Sources/main.swift` — https://raw.githubusercontent.com/firebase/agent-skills/main/skills/xcode-project-setup/scripts/xcode_spm_setup/Sources/main.swift --- name: xcode-project-setup description: 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). compatibility: Requires Swift to be installed locally and macOS environment. metadata: category: ApplicationDevelopment --- # Xcode Project Setup ## ⛔️ CRITICAL RULES & ENVIRONMENT CHECKS Before performing any Xcode setup or file manipulation, you **MUST** adhere to the following rules. A hefty fee will be applied if you violate them. ### 1. The Anti-Ruby Mandate You are **strictly forbidden** from using Ruby, Rails, or any Ruby gems (including the `xcodeproj` gem). Under no circumstances may you write or execute Ruby scripts. ### 2. Modern Xcode Folder Synchronization Modern Xcode projects support folder synchronization. When adding new source code (`.swift`) or resource files, simply write them to the correct directory on disk. They will be automatically included in the Xcode project. **Never manually modify the `.pbxproj` file to add files.** ### 3. Allowed Scripting Languages If you absolutely must write a script to manipulate the project environment (e.g., configuring SPM packages beyond what the provided `xcode_spm_setup` script does), you **must use Swift**. Only as an absolute last resort, if Swift is completely unviable, may you use Node.js or TypeScript. ### 4. Toolchain Verification Because this skill relies entirely on a native Swift script, you must verify the environment: - Run `swift --version` before proceeding. - If the Swift command is not found, you must stop and recommend the user install the Swift toolchain (e.g., via `xcode-select --install` on macOS), or ask if you can attempt to install it for them. Do not attempt to proceed without Swift. ### 5. Mandatory Linker Flags for Static Frameworks (Firebase) When setting up SPM dependencies that heavily rely on internal Objective-C categories and `+load` methods (such as the Firebase iOS SDK suite), the Apple linker will aggressively strip these methods out if they are linked statically. This causes fatal runtime crashes (e.g., `FirebaseAuth/Auth.swift:167: Fatal error: Unexpectedly found nil`). **The provided `xcode_spm_setup` Swift script automatically injects the `-ObjC` flag to `OTHER_LDFLAGS` when adding Firebase products.** However, you should still verify it is present in the build settings if you encounter issues. - Failing to include this flag when adding Firebase dependencies is a critical error. ______________________________________________________________________ ## Empty Directory Workflow If you are asked to build an iOS app or configure Xcode dependencies but **no `.xcodeproj` or `.xcworkspace` exists**, you MUST ask the user to create the project first: **"No Xcode project found in this directory. Please create an empty Xcode project manually and let me know when you are ready to proceed."** Wait for the user to confirm they have created the `.xcodeproj` via Xcode, then proceed with the Standard Xcode Workflow below. ______________________________________________________________________ ## Standard Xcode Workflow Do not use raw text parsing, `sed`, or Ruby scripts to modify `.pbxproj` files directly. Instead, execute the Swift configuration package bundled with this skill (`scripts/xcode_spm_setup`) to securely install SPM packages and link optional config files (like `GoogleService-Info.plist`). ### **CRITICAL: Always Use Latest SDK Version** To ensure access to the latest features and security fixes, always use the most recent version of the Firebase iOS SDK. Check for the latest release version at [https://github.com/firebase/firebase-ios-sdk/releases](https://github.com/firebase/firebase-ios-sdk/releases). - Use the most recent version number (e.g., `11.x.y`) in your commands instead of hardcoded placeholders. ### Understanding the Script's Actions When adding a Swift Package to an Xcode project, two distinct steps must occur: 1. Adding the package repository dependency (e.g., `https://github.com/Alamofire/Alamofire`). 1. Selecting the target (e.g., `MyApp`), navigating to **General > Frameworks, Libraries, and Embedded Content**, and hitting the `+` button to explicitly link the specific product modules (e.g., `Alamofire`). **The provided `xcode_spm_setup` Swift script automatically handles BOTH of these steps for you.** By passing the list of modules as arguments, it safely injects the package dependency and automatically wires those modules to the main target's Frameworks build phase. You do not need to do any manual linking. ## Usage 1. **Locate the package path:** Find the absolute path to this skill's `scripts/xcode_spm_setup` directory on disk. 1. **Execute:** Run the native `swift run` command using the signature below: ```bash swift run --package-path /scripts/xcode_spm_setup xcode_spm_setup [--plist ] [Product2 ...] ``` ### Example 1: Generic Package (e.g., Alamofire) Adding Alamofire to a standard Xcode project. Notice there is no `--plist` flag. ```bash swift run --package-path /Users/foo/.agents/skills/xcode-project-setup/scripts/xcode_spm_setup xcode_spm_setup MyApp.xcodeproj https://github.com/Alamofire/Alamofire 5.8.1 Alamofire ``` ### Example 2: Firebase (Requires Plist) Adding Firebase and linking the `GoogleService-Info.plist` to the resources build phase automatically. *Note: Replace `11.0.0` with the actual latest version from [the releases page](https://github.com/firebase/firebase-ios-sdk/releases).* ```bash swift run --package-path /Users/foo/.agents/skills/xcode-project-setup/scripts/xcode_spm_setup xcode_spm_setup MyApp.xcodeproj https://github.com/firebase/firebase-ios-sdk 11.0.0 --plist MyApp/GoogleService-Info.plist FirebaseCore FirebaseAuth FirebaseFirestore ``` *Note: The script is idempotent. It will automatically skip linking files or packages that are already present in the project.*