Firebase

View saved version →

---
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:
  author: Google LLC
  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 "<package-name>"`).

______________________________________________________________________

## 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: "<package-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 S

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 3 — file references are metadata, not package contents.

View saved version →

---
name: firebase-ai-logic-basics
description: >-
  Integrates Firebase AI Logic (formerly Vertex AI for Firebase) into mobile and web apps (Android, iOS, Web, and Flutter) to call Gemini models from client code. Use when provisioning or initializing Firebase AI Logic, or adding Gemini features to an app: text generation, multimodal input, chat, streaming, structured output, hybrid on-device inference, App Check protection, or switching models with Remote Config.
version: 1.0.1
metadata:
  author: Google LLC
  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. The app can directly call
Gemini models via Firebase AI Logic without the developer needing to manage a
dedicated backend. Firebase AI Logic was previously known as "Vertex AI for
Firebase".

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 pricing 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

- Identify the platform the user is interested in building on prior to starting:
  Android, iOS, Web, or Flutter.
- 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)
- The Firebase CLI commands below run through `npx` on every platform, so they
  need **Node.js 20+** and npm. Use the `firebase-basics` skill to check for
  them and to log in to the Firebase CLI. If Node.js is missing or older than
  version 20, ask the user to install it as that skill describes. Don't install
  system packages yourself, for example with `sudo apt-get`, because that
  changes the user's machine without their consent.

### 1. Provision Firebase AI Logic (ALL platforms)

Use the **Firebase CLI** to provision Firebase AI Logic for the Firebase
Project:

1. Make sure that you're in a firebase directory (with a `firebase.json`).

1. Verify that you're running Firebase CLI commands against the intended
   Firebase Project. When you run this command, the active project is marked
   with "current":

   ```bash
   npx -y firebase-tools@latest projects:list
   ```

1. Make sure there's at least one Firebase App for the target platform
   registered with the current Firebase Project:

   ```bash
   npx -y firebase-tools@latest apps:list
   ```

1. Provision Firebase AI Logic for the Firebase Project:

   ```bash
   npx -y firebase-tools@latest init ailogic
   ```

   This command will enable the Gemini Developer API in the Firebase project.

> [!WARNING] **CRITICAL: Provisioning Firebase AI Logic is Required** For all
> platforms (Android, iOS, Web, or Flutter), even if the app already uses
> Firebase, you MUST run `npx -y firebase-tools@latest init ailogic` to
> provision the service. The configuration files of `GoogleService-Info.plist`,
> `google-services.json`, and `firebase_options.dart` ONLY handle client
> configuration and do NOT enable the Firebase AI Logic service, leading to
> `PERMISSION_DENIED` errors.

If you can't run `init ailogic` yourself (for example because Node.js is missing
or the Firebase CLI isn't logged in) do NOT skip it. The app's requests to
Gemini models will fail until the Firebase AI Logic service is provisioned. Tell
the user to run this command in their project directory, and include it in your
final summary:

```bash
npx -y firebase-tools@latest init ailogic
```

### 2. Add the SDK and initialize the service in the 

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 5 — file references are metadata, not package contents.

View saved version →

---
name: firebase-analytics
description: >-
  Comprehensive guide for Google Analytics for Firebase (GA4F), including base
  setup, SDK initialization, screen tracking, and event logging on Android and
  iOS. Use this skill when setting up Google Analytics, adding the SDK, or
  logging analytics events. Don't use for standalone CLI login or project/config
  file downloads without Analytics (use firebase-basics), or for Crashlytics,
  Remote Config, Auth, Firestore, Hosting, App Hosting, or Data Connect.
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`.
version: 1.0.0
metadata:
  author: Google LLC
  category: CloudObservabilityAndMonitoring
---

# Firebase Analytics

This skill provides a complete guide for getting started with Google Analytics
for Firebase (GA4F) on Android or iOS. It covers base dependency setup,
configuration file placement, initialization, screen tracking, and real-time
event verification.

## Prerequisites

An active Firebase project
[linked to a Google Analytics property](https://support.google.com/analytics/answer/9289234).
See the `firebase-basics` skill for references on project initialization, CLI
login, and downloading app configuration files (`google-services.json` or
`GoogleService-Info.plist`).

## SDK Setup

To learn how to set up Google Analytics for Firebase in your application code
and verify events in real time with DebugView, choose your platform:

*   **Android**: [android_setup.md](references/android_setup.md)
*   **iOS**: [ios_setup.md](references/ios_setup.md)

## SDK Usage

Google Analytics for Firebase automatically logs some events and user
properties; you can also define custom events and properties.

*   [Log events (custom or recommended)](https://firebase.google.com/docs/analytics/events)
*   [Set user properties](https://firebase.google.com/docs/analytics/user-properties)
*   Track screens
    *   **Android**:
        [android_screen_views.md](references/android_screen_views.md)
    *   **iOS**: [ios_screen_views.md](references/ios_screen_views.md)
*   [Configure data collection and consent mode](https://firebase.google.com/docs/analytics/configure-data-collection)

To learn how to customize event logging and configure advanced behaviors,
consult the documentation for your platform.

*   **Android**:
    [Get started with Google Analytics for Android](https://firebase.google.com/docs/analytics/android/get-started)
*   **iOS**:
    [Get started with Google Analytics for iOS+](https://firebase.google.com/docs/analytics/ios/get-started)

Referenced files: 4 — file references are metadata, not package contents.

View saved version →

---
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:
  author: Google LLC
  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",
         ".next",
         ".vercel",
         "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. Create the backend if it does not exist (`apphosting:backends:list`; switch
   `--primary-region`, e.g. `us-east4`, if a region hits its 10-backend quota):

   ```bash
   npx -y firebase-tools@latest apphosting:backends:create --backend my-app-id --primary-region us-central1 --root-dir /
   ```

1. If the app needs safe access to sensitive keys, set and grant access after
   creating the backend:

   ```bash
   printf '%s' '<value>' | npx -y firebase-tools@latest apphosting:secrets:set <secret-name> --data-file - --force
   npx -y firebase-tools@latest apphosting:secrets:grantaccess <secret-name> --backend my-app-id
   ```

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
"git push" deployments. For GitHub-connected backends, trigger rollouts with
`npx -y firebase-tools@latest apphosting:rollouts:create <backend-id> --git-branch <branch>`
(do not use `rollouts:create` when deploying from local source with `deploy`).

For other backend or secret flags (`backends:get`, `backends:delete`, etc.), run
`npx -y firebase-tools@latest <command> --help`.

## Emulation

See [Emulation](references/emulation.md) for more information on how to test
your app locally using the Firebase Local Emulator Suite.

Referenced files: 3 — file references are metadata, not package contents.

View saved version →

---
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:
  author: Google LLC
  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": {
    "providers": {
      "anonymous": true,
      "emailPassword": true,
      "googleSignIn": {
        "oAuthBrandDisplayName": "Your Brand Name",
        "supportEmail": "support@example.com",
        "authorizedRedirectUris": [
          "https://my-project-id.firebaseapp.com/__/auth/handler",
          "http://localhost"
        ]
      }
    }
  }
}
```

> [!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, add `http://localhost` to
> `authorizedRedirectUris` in `firebase.json` (or ensure `localhost` is included
> in the **Authorized Domains** list in the Firebase Console under
> Authentication > Settings > Authorized domains). **CRITICAL**: Do NOT include
> the port number in `authorizedRedirectUris` (e.g., use `http://localhost`, NOT
> `http://localhost:9090` or `http://localhost:4000`), and do NOT include the
> protocol or port number in the Console Authorized Domains list (use
> `localhost`). Including a port number in `authorizedRedirectUris` causes
> `firebase deploy --only auth` to fail with `INVALID_AUTHORIZED_DOMAIN`.

**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

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 5 — file references are metadata, not package contents.

View saved version →

---
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:
  author: Google LLC
  category: CloudInfrastructureAndServices
  version: "1.0.0"
---

# 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:list`
   first; if not logged in, 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:** If no Project ID was provided, 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 with `npx -y firebase-tools@latest use` (if
        `firebase.json` is missing at the project root, create `{}` first).

     1. If the command outputs `Active Project: <project-id>`, 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 <PROJECT_ID>
        ```

   - **If creating a new project:** Run the following command to create it:

     ```bash
     npx -y firebase-tools@latest projects:create <project-id> --display-name "<display-name>"
     ```

     *Note: The `<project-id>` 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 ex

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 19 — file references are metadata, not package contents.

View saved version →

---
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:
  author: Google LLC
  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)

Referenced files: 2 — file references are metadata, not package contents.

View saved version →

---
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:
  author: Google LLC
  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 `_u

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 16 — file references are metadata, not package contents.

View saved version →

---
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. For authoring or modifying Firestore Security Rules (firestore.rules), delegate to the firestore-rules-author subagent if subagent delegation is available, or use firestore-rules-creation otherwise. 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:
  author: Google LLC
  category: Databases
---

# Cloud Firestore Database and Operations

> [!IMPORTANT] **Security Rules Authoring (`firestore.rules`)** Whenever your
> task requires creating, authoring, or modifying `firestore.rules`:
>
> - **If subagent delegation AND the `firestore-rules-author` subagent are
>   available**: delegate authoring `firestore.rules` to the
>   `firestore-rules-author` subagent rather than writing `firestore.rules`
>   directly in the main agent.
> - **If subagent delegation is unavailable** (e.g., subagents not enabled in
>   the IDE) **OR `firestore-rules-author` is not installed**: read and follow
>   the `firestore-rules-creation` skill to write `firestore.rules` directly.

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 <database-id>
   ```

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 <database-id> --edition="enterprise" --location="<selected-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**: See the `firestore-rules-creation` skill
- **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**: See t

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 14 — file references are metadata, not package contents.

View saved version →

---
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:
  author: Google LLC
  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.

Referenced files: 2 — file references are metadata, not package contents.

View saved version →

---
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:
  author: Google LLC
  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 <PROJECT_ID>` 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:

- **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 mis

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 2 — file references are metadata, not package contents.

View saved version →

---
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:
  author: Google LLC
  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:

```json
{
  "score": 1,
  "summary": "overall assessment",
  "findings": [
    {
      "check": "checklist item",
      "severity": "critical|major|moderate|minor",
      "issue": "description",
      "recommendation": "fix"
    }
  ]
}
```

View saved version →

---
name: firestore-rules-creation
description: >-
  Designs, authors, refactors, and hardens production-grade Cloud Firestore Security Rules (firestore.rules). IMPORTANT: If subagent delegation AND the firestore-rules-author subagent are available in your environment, delegate authoring firestore.rules to the firestore-rules-author subagent. If subagent delegation is unavailable (e.g. not enabled in the IDE), firestore-rules-author is not installed, or you are running inside firestore-rules-author, follow this skill directly.
metadata:
  author: Google LLC
  category: Databases
---

# Firestore Security Rules Creation

> [!IMPORTANT] **Subagent Delegation vs. Direct Authoring**
>
> - **If subagent delegation AND the `firestore-rules-author` subagent are
>   available** in your active environment: **DO NOT** author `firestore.rules`
>   directly in the main agent. Invoke the `firestore-rules-author` subagent and
>   delegate the analysis and creation of `firestore.rules` to it.
> - **If subagent delegation is unavailable** (e.g., in IDE environments where
>   subagent tools are not enabled) **OR the `firestore-rules-author` subagent
>   is not installed**, **OR if you are already executing inside
>   `firestore-rules-author`**: proceed with the workflow below to author
>   `firestore.rules` directly.

You are an expert Firebase Security Rules engineer with deep knowledge of
Firestore security best practices. Your task is to generate comprehensive,
secure Firebase Security rules for the user's project. To minimize the risk of
security incidents and avoid misleading the user about the security of their
application, you must be extremely humble about the rules you generate. Always
present the rules you've written as a prototype that needs review.

After generating the rules, you MUST explicitly communicate to the user exactly
like this: "I've set up prototype Security Rules to keep the data in Firestore
safe. They are designed to be secure for <explain reasons here>. However, you
should review and verify them before broadly sharing your app. If you'd like, I
can help you harden these rules."

### Workflow

Follow this structured workflow strictly:

#### Phase-1: Codebase Analysis

1. **Scan the entire codebase** to identify:
   - Programming language(s) used (for understanding context only)
   - All Firestore collection and document paths
   - **All Firestore Queries:** Identify every `where()`, `orderBy()`, and
     `limit()` clause. The security rules **MUST** allow these specific queries.
   - Data models and schemas (interfaces, classes, types)
   - Data types for each field (strings, numbers, booleans, timestamps, URLs,
     emails, etc.)
   - Required vs. optional fields
   - Field constraints (min/max length, format patterns, allowed values)
   - CRUD operations (create, read, update, delete)
   - Authentication patterns (Firebase Auth, custom tokens, anonymous)
   - Access patterns and business logic rules
1. **Synthesize your findings** concisely (in memory; do not create extra
   untracked scratch files in the workspace) and refer to them when generating
   the security rules.

#### Phase-2: Security Rules Generation

**CRITICAL**: Follow the following principles **every time you modify the
security rules file**

Generate Firebase Security Rules following these principles:

- **Default deny:** Start with denying all access, then explicitly allow only
  what's needed
- **Least privilege:** Grant minimum permissions required
- **Validate data:** Check data types, allowed fields, and constraints on both
  creates and updates.
  - **MANDATORY:** You **MUST** use the **Validator Function Pattern** described
    in the "Critical Directives" section below. This involves defining a
    specific validation function (e.g., `isValidUser`) and calling it in
    **BOTH** `create` and `update` rules.
  - **MANDATORY:** For **ALL** creates **AND ALL** updates, ensure that after
    the operation, the required fields are still availabl

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
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:
  author: Google LLC
  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

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 4 — file references are metadata, not package contents.