New: 98,000+ skills indexed from GitHub repos with 100+ stars · every skill safety-checkedBrowse top skillsTop skills
Esc to closeBrowse all skills
Submit a skillBrowse skills
Submit a skillBrowse skills

Agent skill

Gemini API Best Practices

by takeshy in takeshy/obsidian-gemini-helper

Reviews and corrects Gemini API integration code against Google's published practices, covering SDK choice, safety settings, finishReason checks, tools, streaming and thinking.

MITAuto-check passedAI & LLM Engineering

Install Gemini API Best Practices

skills CLI
$ npx skills add takeshy/obsidian-gemini-helper --skill gemini-best-practices -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install takeshy/obsidian-gemini-helper gemini-best-practices --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/takeshy/obsidian-gemini-helper.git skills-src && mkdir -p .claude/skills && cp -r skills-src/.agents/skills/gemini-best-practices .claude/skills/gemini-best-practices && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
gemini-best-practices
GitHub stars
117
Token cost
~1.1k tokens
SKILL.md length
343 words
Files
1
Skills in repo
3
Repo updated
First seen
Licence
MIT

At a glance

Reviews and corrects Gemini API integration code against Google's published practices, covering SDK choice, safety settings, finishReason checks, tools, streaming and thinking.

  • Auditing a project's Gemini calls for missing safety settings or finishReason handling
  • SKILL.md covers SDK and Package, Safety Settings, Response Validation… and System Instructions, plus 6 more sections
  • Instructions only: no scripts, shell commands, URLs or credentials in SKILL.md
  • Adding a new Gemini API call to the core client module

What it does

The checklist starts with the right package: `@google/genai` from npm, never the deprecated `@google/generative-ai`, with API keys read from environment variables. Every `generateContent`, `generateContentStream` and `chats.create` call must carry `safetySettings`, and the code must inspect `finishReason` on response candidates, handling SAFETY, RECITATION and MAX_TOKENS differently from a normal STOP, for both streaming and non-streaming responses.

Other sections cover passing `systemInstruction` in config and re-specifying it per chat session, passing tools through `config.tools` with proper SDK types, and the rule that `googleSearch` and `fileSearch` cannot be combined with function declarations in one request. For streaming it favors the SDK Chat for thought signatures and processing every part of each chunk. Thinking is on by default for recent Gemini models, with notes on `thinkingBudget`, `thinkingLevel` and Pro models that require it. It is aimed at a specific file, `src/core/gemini.ts`, and new API calls.

When your agent uses it

  • Auditing a project's Gemini calls for missing safety settings or finishReason handling
  • Adding a new Gemini API call to the core client module
  • Migrating code off the deprecated Gemini SDK package

Example prompts

  • “Review src/core/gemini.ts against the Gemini best practices and fix what is missing.”
  • “Add a streaming call with function declarations, and make sure googleSearch is not combined with them.”
  • “Does our chat code handle MAX_TOKENS and SAFETY finish reasons correctly?”

Requirements

  • A project that calls the Gemini API with the `@google/genai` SDK
  • A Gemini API key held in an environment variable

What it can do on your machine

Read from SKILL.md and the folder at commit 0e2b8d0. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    No scripts in the folder and no shell commands in SKILL.md (its code samples are typescript).

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Gemini API Best Practices loads about 1.1k tokens when it runs. Until then it costs about 49 tokens; SKILL.md has 343 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~49
When it runs · the whole SKILL.md, loaded when a task matches
~1.1k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from takeshy/obsidian-gemini-helper at commit 0e2b8d0, republished under its MIT licence (© takeshy). 343 words, ~1,073 tokens.

Download SKILL.mdSave it as .claude/skills/gemini-best-practices/SKILL.md (or your agent's skills folder).
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:

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

© takeshy, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

Just SKILL.md in .agents/skills/gemini-best-practices of takeshy/obsidian-gemini-helper.

Open the folder on GitHubat commit 0e2b8d0

Compare with similar skills

Gemini API Best Practices next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Gemini API Best Practices compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Gemini API Best Practices this skilltakeshy/obsidian-gemini-helper117—~1.1kAutomated safety check: PassMIT
Gemini API Devgoogle-gemini/gemini-skills4.3k—~5.1kAutomated safety check: PassApache-2.0
Gemini API DevAyuilos/Miffan217—~1.4kAutomated safety check: PassAGPL-3.0
Gemini API DevJetBrains/skills366—~1.6kAutomated safety check: PassNone
Gemini Interactions APIJetBrains/skills366—~2.5kAutomated safety check: PassNone
Gemini Live API Devgoogle-gemini/gemini-skills4.3k—~4.6kAutomated safety check: PassApache-2.0

Similar skills

  • Gemini API Dev

    google-gemini/gemini-skills

    Official

    A skill your agent uses when writing code that calls the Gemini API for text generation, multi-turn chat, multimodal understanding, image generation, video generation, speech generation (TTS), voice…

    4.3k GitHub stars~5.1k tokensUpdated 4 days ago
    AI & LLM EngineeringAuto-check passed

  • Gemini API Dev

    Ayuilos/Miffan

    A skill your agent uses when building applications with Gemini API hosted models, including Gemini and Gemma 4, working with multimodal content (text, images, audio, video), implementing function…

    217 GitHub stars~1.4k tokensUpdated yesterday
    AI & LLM EngineeringAuto-check passed

  • Gemini API Dev

    JetBrains/skills

    Official

    A skill your agent uses when building applications with Gemini models, Gemini API, working with multimodal content (text, images, audio, video), implementing function calling, using structured…

    366 GitHub stars~1.6k tokensUpdated 3 mo ago
    AI & LLM EngineeringAuto-check passed

  • Gemini Interactions API

    JetBrains/skills

    Official

    A skill your agent uses when writing code that calls the Gemini API for text generation, multi-turn chat, multimodal understanding, image generation, streaming responses, background research tasks…

    366 GitHub stars~2.5k tokensUpdated 3 mo ago
    AI & LLM EngineeringAuto-check passed

  • Gemini Live API Dev

    google-gemini/gemini-skills

    Official

    A skill your agent uses when building real-time, bidirectional streaming applications with the Gemini Live API, or migrating legacy Live models (2.0/2.5/3.1) to Gemini 3.8 Live.

    4.3k GitHub stars~4.6k tokensUpdated 4 days ago
    Backend & APIsAuto-check passed

  • Gemini Interactions API

    Ayuilos/Miffan

    A skill your agent uses when writing code that calls the Gemini API for text generation, multi-turn chat, multimodal understanding, image generation, video generation, streaming responses…

    217 GitHub stars~4.6k tokensUpdated yesterday
    Media & CreativeAuto-check passed

More from takeshy/obsidian-gemini-helper

  • Add Tool

    takeshy/obsidian-gemini-helper

    Add a new function calling tool (vault operation) for the Gemini chat.

    117 GitHub stars~468 tokensUpdated 4 days ago
    Auto-check: notes

  • Add Workflow Node Type

    takeshy/obsidian-gemini-helper

    Guides the agent through every file that must change to register a new node type in the Obsidian Gemini Helper workflow engine, then through lint and build checks.

    117 GitHub stars~450 tokensUpdated 4 days ago
    Auto-check: notes

Works with

Categories

Questions about Gemini API Best Practices

What does Gemini API Best Practices do?

Reviews and corrects Gemini API integration code against Google's published practices, covering SDK choice, safety settings, finishReason checks, tools, streaming and thinking. The checklist starts with the right package: `@google/genai` from npm, never the deprecated `@google/generative-ai`, with API keys read from environment variables.create` call must carry `safetySettings`, and the code must inspect `finishReason` on response candidates, handling SAFETY, RECITATION and MAX_TOKENS differently from a normal STOP, for both streaming and non-streaming responses.

When should I use Gemini API Best Practices?

Gemini API Best Practices fits situations like: auditing a project's Gemini calls for missing safety settings or finishReason handling; adding a new Gemini API call to the core client module; migrating code off the deprecated Gemini SDK package.

How do I install Gemini API Best Practices in Claude Code?

Run `npx skills add takeshy/obsidian-gemini-helper --skill gemini-best-practices -a claude-code`. Or copy the skill folder (.agents/skills/gemini-best-practices in takeshy/obsidian-gemini-helper) into .claude/skills/gemini-best-practices in your project. Claude Code loads it when a task matches its description.

How do I install Gemini API Best Practices in Codex?

Run `npx skills add takeshy/obsidian-gemini-helper --skill gemini-best-practices -a codex`. Or copy the skill folder (.agents/skills/gemini-best-practices in takeshy/obsidian-gemini-helper) into .agents/skills/gemini-best-practices in your project. Codex loads it when a task matches its description.

Can I use Gemini API Best Practices in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add takeshy/obsidian-gemini-helper --skill gemini-best-practices -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/gemini-best-practices, .gemini/skills/gemini-best-practices, .github/skills/gemini-best-practices and .opencode/skills/gemini-best-practices in your project.

What does Gemini API Best Practices need to run?

SKILL.md names no scripts, command-line tools or credentials: Gemini API Best Practices is instructions for the agent only. Our summary lists: A project that calls the Gemini API with the `@google/genai` SDK; A Gemini API key held in an environment variable.

Does Gemini API Best Practices access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is Gemini API Best Practices safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Gemini API Best Practices use?

Gemini API Best Practices is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Gemini API Best Practices use?

About 1.1k tokens (SKILL.md is roughly 4.3k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Gemini API Best Practices?

Skills that share tags, products or a category with Gemini API Best Practices: Gemini API Dev (google-gemini/gemini-skills, 4.3k stars), Gemini API Dev (Ayuilos/Miffan, 217 stars), Gemini API Dev (JetBrains/skills, 366 stars) and Gemini Interactions API (JetBrains/skills, 366 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Gemini API Best Practices?

takeshy (a GitHub user) maintains it in takeshy/obsidian-gemini-helper, which has 117 GitHub stars. The repository holds 3 skills in this directory. The repository was last updated on October 6, 2026.

Source: takeshy/obsidian-gemini-helper on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.