agentleFS
takeshytakeshy/obsidian-gemini-helper/.claude/skills/gemini-best-practices/SKILL.md

gemini-best-practices

Skill117 starsChanged 5 months agoMITView on GitHub

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.

2 other projects use a version of this.

Adopted by

Most recently taken up by

  • Other versions2 projects use a version of this.

    Word for word · 1

    1. takeshy/obsidian-llm-hub★ 41100% same

    Edited · 0

    None found.

    Wrote their own version · 1

    1. FutureAtoms/claude-skills-backup★ 1same name

    How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.

  • In this repository7 other files it gives its agents.

The file

We split this skill into the rules it gives an agent

9 rules. About 0 are common, 1 is distinctive, and 8 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 8

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    When reviewing or modifying Gemini API integration code, ensure compliance with Google's official best practices from …

    line 14
  2. Distinctive:

    Prefer environment variables for API keys over hard-coding

    line 20
  3. Very specific:

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

    line 24
  4. Very specific:

    Always check finishReason on response candidates:

    line 39
  5. Very specific:

    Use proper SDK types (Tool, FunctionDeclaration) without forced as casts

    line 66
  6. Very specific:

    Use generateContentStream or chat.sendMessageStream for streaming

    line 73
  7. Very specific:

    Use SDK Chat (ai.chats.create()) for automatic thought signature handling

    line 74
  8. Very specific:

    Use proper SDK types from @google/genai instead of as casts

    line 98
  9. Very specific:

    Import enums (FinishReason, HarmCategory, HarmBlockThreshold) as values, not just types

    line 100

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.