Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Security

gemini-best-practices

Review and fix Gemini API usage against Google's official best practices. Use when modifying src/core/gemini.ts, adding new API calls, or auditing Gemini integration quality.

takeshy · Static checks on file

Installation

Read the source and dependencies before running a command. Copying does not install or execute anything.

npx skills add takeshy/obsidian-llm-hub --skill gemini-best-practices

About this skill


name: gemini-best-practices description: Review and fix Gemini API usage against Google's official best practices. Use when modifying src/core/gemini.ts, adding new API calls, or auditing Gemini integration quality. user-invocable: true disable-model-invocation: false paths:

  • src/core/gemini.ts
  • src/core/fileSearch.ts
  • src/core/tools.ts

Gemini API Best Practices

When reviewing or modifying Gemini API integration code, ensure compliance with Google's official best practices from google-gemini/gemini-skills.

SDK and Package

  • Correct SDK: @google/genai (npm)
  • NEVER use deprecated: @google/generative-ai (old package)
  • Prefer environment variables for API keys over hard-coding

Safety Settings

All API calls (generateContent, generateContentStream, chats.create) MUST include safetySettings in the config:

import { HarmCategory, HarmBlockThreshold, type SafetySetting } from "@google/genai";

const DEFAULT_SAFETY_SETTINGS: SafetySetting[] = [
  { category: HarmCategory.HARM_CATEGORY_HARASSMENT, threshold: HarmBlockThreshold.BLOCK_MEDIUM_AND_ABOVE },
  { category: HarmCategory.HARM_CATEGORY_HATE_SPEECH, threshold: HarmBlockThreshold.BLOCK_MEDIUM_AND_ABOVE },
  { category: HarmCategory.HARM_CATEGORY_SEXUALLY_EXPLICIT, threshold: HarmBlockThreshold.BLOCK_MEDIUM_AND_ABOVE },
  { category: HarmCategory.HARM_CATEGORY_DANGEROUS_CONTENT, threshold: HarmBlockThreshold.BLOCK_MEDIUM_AND_ABOVE },
];

Response Validation (finishReason)

Always check finishReason on response candidates:

  • SAFETY - Response blocked by safety filters; inform user to rephrase
  • RECITATION - Blocked due to potential copyrighted content recitation
  • MAX_TOKENS - Output truncated; consider informing user
  • STOP - Normal completion
import { FinishReason } from "@google/genai";

// Check candidates[0].finishReason after each response
if (candidate.finishReason === FinishReason.SAFETY) {
  // Handle blocked response
}

For non-streaming: check response.candidates[0].finishReason before using response.text. For streaming: check finishReason in chunk candidates.

System Instructions

  • Pass via systemInstruction in config (not as a chat message)
  • System instructions are interaction-scoped; re-specify on each chat session creation

Tool / Function Calling

  • Pass tools via config.tools array
  • Use proper SDK types (Tool, FunctionDeclaration) without forced as casts
  • googleSearch and fileSearch are first-class Tool properties
  • fileSearch CANNOT be combined with functionDeclarations in the same request
  • googleSearch CANNOT be combined with functionDeclarations

Streaming

  • Use generateContentStream or chat.sendMessageStream for streaming
  • Use SDK Chat (ai.chats.create()) for automatic thought signature handling
  • Process ALL parts in each chunk (text, thought, functionCall can coexist)

Thinking / Reasoning

  • Thinking is ON by default for Gemini 2.5+ and 3.x models
  • thinkingBudget: 0 disables thinking (except models that require it)
  • Gemini 3.1 Flash Lite uses thinkingLevel instead of thinkingBudget
  • Gemini 3 Pro / 3.1 Pro require thinking (cannot be disabled)
  • Access thought parts via part.thought boolean on content parts

Model Names

Current models (use these):

  • gemini-3.1-pro-preview - Flagship, 1M context
  • gemini-3-flash-preview - Fast, balanced
  • gemini-3.1-flash-lite-preview - Cost-efficient
  • gemini-2.5-pro / gemini-2.5-flash - Still available

Deprecated models (NEVER use):

  • All gemini-2.0-*, gemini-1.5-*, gemini-1.0-*, gemini-pro

Type Safety

  • Use proper SDK types from @google/genai instead of as casts
  • Tool interface supports googleSearch, fileSearch, functionDeclarations, codeExecution, urlContext
  • Import enums (FinishReason, HarmCategory, HarmBlockThreshold) as values, not just types

Checklist for New API Calls

  • safetySettings: DEFAULT_SAFETY_SETTINGS included in config
  • finishReason checked on response candidates
  • systemInstruction passed in config (not as message)
  • No forced as Tool type assertions
  • Proper error handling with formatError()
  • Usage metadata extracted for cost tracking