Skill: felipe0liveira/firestore (version 1.0.4)

--- name: firestore description: Manage Google Cloud Firestore databases using the Firestore REST API via curl commands. Authenticate using gcloud CLI tokens to perform CRUD operations on documents and collections. user-invocable: true disable-model-invocation: true metadata: {"clawdbot":{"emoji":"🔥","requires":{"bins":["curl","gcloud"]},"install":[{"id":"gcloud-sdk","kind":"manual","url":"https://docs.cloud.google.com/sdk/docs/install-sdk","bins":["gcloud"],"label":"Install Google Cloud CLI (official)"}]}} --- # Firestore Manage Google Cloud Firestore databases via REST API This skill is built on top of the official Firebase Firestore REST API reference documentation: https://firebase.google.com/docs/firestore/reference/rest It enables you to interact with Google Cloud Firestore using the [Firestore REST API](https://firebase.google.com/docs/firestore/reference/rest) through `curl` commands. It uses `gcloud auth print-access-token` to obtain authentication tokens, allowing you to perform Create, Read, Update, and Delete (CRUD) operations on Firestore documents and collections. For related documentation: - Installation and setup: [installation.md](installation.md) - Few-shot prompts and command examples: [examples.md](examples.md) - Error handling and diagnostics: [troubleshooting.md](troubleshooting.md) ## Requirements This skill requires `curl` and `gcloud` CLI. For full installation and setup instructions, see [installation.md](installation.md). ## Credentials & Environment This skill uses OAuth 2.0 access tokens generated by `gcloud auth print-access-token`. The token is valid for a limited time (typically 1 hour) and inherits the permissions of the authenticated Google Cloud account. This skill must run only with a dedicated service account context. Do not use personal user credentials or broad admin identities. **Before any operation, generate a fresh access token:** ```bash ACCESS_TOKEN=$(gcloud auth print-access-token) ``` **Before any operation, verify the active identity is a service account:** ```bash gcloud config list --format='text(core.account,core.project)' ``` If the active account is not a service account (for example, it does not end with `gserviceaccount.com`), stop and ask the user to switch credentials before proceeding. **Security Recommendations:** - **Use a dedicated, least-privilege service account** for automation tasks. Never use your personal or admin account. - **Test in a sandbox or development project** before running commands against production. - **Verify your active project** with `gcloud config list` before executing commands. - **Tokens expire after approximately 1 hour** — regenerate if you encounter 401 Unauthorized errors. - **The token inherits ALL permissions** of the authenticated account, including read access to sensitive data. - **Revoke tokens immediately** if you suspect unauthorized access: `gcloud auth revoke` - **Audit activity regularly** by reviewing Cloud Audit Logs for the project. ## Security Considerations **Important:** This skill can access Firestore data with the same permissions as the authenticated Google Cloud account. For safety, this skill requires explicit user approval before executing any operation, including read-only operations. **To minimize risk:** 1. Only use this skill with service accounts that have the minimum required Firestore permissions 2. Use separate projects for development/testing and production environments 3. Review the `gcloud config list` output before allowing any operations 4. Grant only `roles/datastore.viewer` for read-only access or `roles/datastore.user` for limited read/write 5. Never use `roles/datastore.owner` or `roles/owner` with this skill 6. Monitor Cloud Audit Logs for unexpected Firestore API calls ## What You Can Do You can perform the following operations on Firestore databases: - **Create** — Insert new documents into collections - **Read** — Query documents with filters and conditions - **Update** — Modify specific fields in existing documents using updateMask - **Delete** — Remove documents from collections - **List** — Retrieve all documents in a collection - **Batch operations** — Perform multiple writes in a single atomic transaction All operations use the Firestore REST API endpoint: ``` https://firestore.googleapis.com/v1/projects/{PROJECT_ID}/databases/{DATABASE_ID}/documents ``` ## Workflow Before executing any Firestore operation, you **MUST** follow this workflow: 1. **Check active context** — Run `gcloud config list --format='text(core.account,core.project)'` to display the active account and project. Present this to the user so they are aware of which credentials and project will be used. 2. **Generate access token** — Always start by obtaining a fresh access token: ```bash ACCESS_TOKEN=$(gcloud auth print-access-token) ``` 3. **Construct the curl command** — Build the appropriate curl command based on the operation: - Use the correct HTTP method (POST for create/query, GET for read, PATCH for update, DELETE for delete) - Include the `Authorization: Bearer $ACCESS_TOKEN` header - Set `Content-Type: application/json` for requests with body - Use the correct API endpoint for the project and collection 4. **For all operations (read and write)** — Present the full curl command to the user and **wait for explicit approval** before executing. See the Approval Policy section below. 5. **Execute the command** and parse the JSON response. ## Important Rules - **Always generate a fresh token first** — Run `ACCESS_TOKEN=$(gcloud auth print-access-token)` before any operation. - **Use proper JSON formatting** — Firestore requires specific field value types (stringValue, booleanValue, integerValue, etc.). - **Document ID generation** — When creating documents, if you don't specify `?documentId=YOUR_ID` in the URL, Firestore will automatically generate a unique document ID. - **Include field paths in updateMask** — When updating, use `updateMask.fieldPaths` to specify which fields to update. - **Never execute any command autonomously** — always present the full curl command to the user and wait for explicit approval before running it, including read-only operations. - **Parse responses carefully** — Firestore returns data in a nested format with typed values. - **Verify project ID** — Always confirm you're targeting the correct project before executing commands. ## Approval Policy All operations require explicit user confirmation before execution. This includes: - **Create** — Creating new documents in collections - **Read / Query / Get / List** — Retrieving documents or query results - **Update / Patch** — Modifying existing document fields - **Delete** — Removing documents permanently - **Batch writes** — Any batch operation that modifies data For every operation, the agent must: 1. Show the full curl command that will be executed. 2. Display the active account and project context. 3. Wait for the user to explicitly approve before running the command. ## Firestore Data Types Firestore uses typed field values in JSON. Common types: - `stringValue` — Text strings - `integerValue` — Integer numbers (as strings) - `doubleValue` — Floating-point numbers - `booleanValue` — true/false - `timestampValue` — ISO 8601 timestamps - `arrayValue` — Arrays of values - `mapValue` — Nested objects Example document structure: ```json { "fields": { "name": { "stringValue": "John Doe" }, "age": { "integerValue": "30" }, "active": { "booleanValue": true } } } ``` ## Few-Shot Prompting Examples Few-shot prompts and full command examples are available in [examples.md](examples.md). ## Common Query Operators When constructing queries, use these operators in the `fieldFilter.op` field: - `EQUAL` — Field equals value - `NOT_EQUAL` — Field does not equal value - `LESS_THAN` — Field is less than value - `LESS_THAN_OR_EQUAL` — Field is less than or equal to value - `GREATER_THAN` — Field is greater than value - `GREATER_THAN_OR_EQUAL` — Field is greater than or equal to value - `ARRAY_CONTAINS` — Array field contains value - `IN` — Field value is in the provided array - `ARRAY_CONTAINS_ANY` — Array field contains any of the provided values ## Troubleshooting For dedicated troubleshooting guidance, see [troubleshooting.md](troubleshooting.md).


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)