google-gemini-file-search
Build document Q&A with Gemini File Search - fully managed RAG with automatic chunking, embeddings, and citations. Upload 100+ file formats, query with natural language. Use when: document Q&A, searchable knowledge bases, semantic search. Troubleshoot: document immutability, storage quota (3x), chunking config, metadata limits (20 max), polling timeouts, displayName dropped (Blob uploads), grounding lost (JSON mode), tool conflicts (googleSearch + fileSearch).
npx skills add majiayu000/claude-skill-registry --skill google-gemini-file-search-brendadeeznuts1111-tier-1380-omega --agent claude-code
Same command for any agent — swap --agent for codex, cursor, copilot.
Weekly change comes from our own snapshots, not the repository page — it measures attention, not adoption.
What it does
Instructs the agent to establish a Google Gemini File Search workflow that supports document Q&A over a variety of file formats, with automatic chunking, embeddings, and citations. It enables querying via natural language and includes setup for API access, environment, and SDK version requirements. It lists common errors with prevention strategies and cost considerations, providing code examples for uploading, chunking, metadata handling, polling, deletion, model compatibility, displayName behavior, grounding metadata when using JSON responses, and tool usage constraints.
How it works
The skill guides the agent through: (1) prerequisites including a Google AI API key, Node.js environment, and installing @google/genai with a minimum version that supports File Search; (2) using the File Search API to upload documents in 100+ formats with automatic chunking and embeddings; (3) configuring chunking per content type (examples show token-based chunk sizes and overlaps); (4) managing metadata with a 20-field limit and strategies for compactness; (5) estimating and monitoring indexing costs and storage, with token-based cost calculations; (6) polling the upload operation status until done, with timeout handling; (7) forcing deletion of stores with documents to prevent accidental loss; (8) ensuring compatibility with Gemini 3 Pro/Flash models and avoiding unsupported models; (9) preserving displayName and metadata for blob uploads by upgrading to v1.34.0+ (or using resumable uploads as a workaround); (10) handling grounding metadata when using JSON structured output and avoiding responseMimeType conflicts; (11) keeping tools usage distinct when using googleSearch and fileSearch tools.
When to use it
Use when performing document Q&A, building searchable knowledge bases, or enabling semantic search with a large set of documents via Gemini File Search. It also serves as a troubleshooting reference for issues like document immutability, quota, chunking, metadata limits, polling timeouts, displayName behavior, grounding, and tool conflicts.
What it can touch
- Documentation references to the File Search API and SDK usage (e.g., ai.fileSearchStores, ai.operations, ai.models.generateContent).
- Tools explicitly listed: Bash, Read, Write, Glob, Grep, WebFetch. The skill frontmatter notes allowed tools as Bash, Read, Write, Glob, Grep, WebFetch; these are the actionable interfaces the agent may invoke.
Caveats
- Requires Gemini 3 Pro or Gemini 3 Flash models for File Search support; older Gemini models are not supported.
- Blob uploads prior to v1.34.0 may drop displayName and customMetadata; upgrade recommended or use resumable uploads as a workaround.
- File Search stores with documents require force deletion to remove; non-force deletes fail.
- Grounding metadata may be ignored if using responseMimeType: application/json in structured outputs; use a two-step approach to obtain grounding metadata and then convert to JSON.
- Storage quota is approximately 3x the input size due to embeddings and metadata; plan accordingly.
# Google Gemini File Search Setup ## Overview Google Gemini File Search is a fully managed RAG system. Upload documents (100+ formats: PDF, Word, Excel, code) and query with natural language—automatic chunking, embeddings, semantic search, and citations. **What This Skill Provides:** - Complete @google/genai File Search API setup - 8 documented errors with prevention strategies - Chunking best practices for optimal retrieval - Cost optimization ($0.15/1M tokens indexing, 3x storage multiplier) - Cloudflare Workers + Next.js integration templates ## Prerequisites ### 1. Google AI API Key Create an API key at https://aistudio.google.com/apikey **Free Tier Limits:** - 1 GB storage (total across all file search stores) - 1,500 requests per day - 1 million tokens per minute **Paid Tier Pricing:** - Indexing: $0.15 per 1M input tokens (one-time) - Storage: Free (Tier 1: 10 GB, Tier 2: 100 GB, Tier 3: 1 TB) - Query-time embeddings: Free (retrieved context counts as input tokens) ### 2. Node.js Environment **Minimum Version:** Node.js 18+ (v20+ recommended) ```bash node --version # Should be >=18.0.0 ``` ### 3. Install @google/genai SDK ```bash npm install @google/genai # or pnpm add @goog
- Overview
- Prerequisites
- 1. Google AI API Key
- 2. Node.js Environment
- 3. Install @google/genai SDK
- 4. TypeScript Configuration (Optional but Recommended)
- Common Errors Prevented
- Error 1: Document Immutability
- Error 2: Storage Quota Exceeded
- Error 3: Incorrect Chunking Configuration
- Error 4: Metadata Limits Exceeded
- Error 5: Indexing Cost Surprises
- Error 6: Not Polling Operation Status
- Error 7: Forgetting Force Delete
node --version # Should be >=18.0.0 npm install @google/genai or pnpm add @google/genai yarn add @google/genai cd templates/basic-node-rag npm install npm run dev cd templates/cloudflare-worker-rag npx wrangler deploy
What does the google-gemini-file-search skill do?
Build document Q&A with Gemini File Search - fully managed RAG with automatic chunking, embeddings, and citations. Upload 100+ file formats, query with natural language. Use when: document Q&A, searchable knowledge bases, semantic search. Troubleshoot: document immutability, storage quota (3x), chunking config, metadata limits (20 max), polling timeouts, displayName dropped (Blob uploads), grounding lost (JSON mode), tool conflicts (googleSearch + fileSearch).
How do I install it?
Run `npx skills add majiayu000/claude-skill-registry --skill google-gemini-file-search-brendadeeznuts1111-tier-1380-omega --agent claude-code` — it drops the skill into your project so the agent can pick it up. Swap the --agent value for codex, cursor or copilot if you use one of those.
Where does this skill come from?
From majiayu000/claude-skill-registry, a repository with 534 stars. We read it straight from the repository tree rather than a submitted listing, so what you see here is what is actually published.
Is a popular skill a good skill?
Not necessarily. Stars measure attention, not adoption — a repository can trend for a week and be abandoned. That is why we show the weekly change from our own snapshots next to the total, instead of a single flattering number.