**Package**: @google/genai@1.27.0 (⚠️ NOT @google/generative-ai)
/plugin marketplace add secondsky/claude-skills/plugin install google-gemini-api@claude-skillsThis skill inherits all available tools. When active, it can use any tool Claude has access to.
references/code-execution-patterns.mdreferences/context-caching-guide.mdreferences/error-catalog.mdreferences/function-calling-patterns.mdreferences/generation-config.mdreferences/grounding-guide.mdreferences/models-guide.mdreferences/multimodal-guide.mdreferences/sdk-migration-guide.mdreferences/streaming-patterns.mdreferences/thinking-mode-guide.mdreferences/top-errors.mdscripts/check-versions.shtemplates/basic-usage.tstemplates/cloudflare-worker.tstemplates/code-execution.tstemplates/combined-advanced.tstemplates/context-caching.tstemplates/function-calling-basic.tstemplates/function-calling-parallel.tsPackage: @google/genai@1.27.0 (⚠️ NOT @google/generative-ai) Last Updated: 2025-11-21
DEPRECATED SDK: @google/generative-ai (sunset November 30, 2025)
CURRENT SDK: @google/genai v1.27+
If you see code using @google/generative-ai, it's outdated!
Load references/sdk-migration-guide.md for complete migration steps.
✅ CORRECT SDK:
bun add @google/genai@1.27.0
❌ WRONG (DEPRECATED):
bun add @google/generative-ai # DO NOT USE!
export GEMINI_API_KEY="your-api-key"
import { GoogleGenAI } from '@google/genai';
const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });
const response = await ai.models.generateContent({
model: 'gemini-2.5-flash',
contents: 'Explain quantum computing in simple terms'
});
console.log(response.text);
See Full Template: templates/basic-usage.ts
⚠️ Common mistake: Claiming Gemini 2.5 has 2M tokens. It doesn't. It's 1,048,576 (1M).
Load references/models-guide.md for detailed model comparison and selection criteria.
const response = await ai.models.generateContent({
model: 'gemini-2.5-flash',
contents: 'Write a haiku about programming'
});
console.log(response.text);
const response = await ai.models.generateContent({
model: 'gemini-2.5-flash',
contents: 'Explain AI',
generationConfig: {
temperature: 0.7, // 0.0-2.0, default 1.0
topP: 0.95, // 0.0-1.0
topK: 40, // 1-100
maxOutputTokens: 1024,
stopSequences: ['END']
}
});
Load references/generation-config.md for complete parameter reference and tuning guidance.
const stream = await ai.models.generateContentStream({
model: 'gemini-2.5-flash',
contents: 'Write a long story'
});
for await (const chunk of stream) {
process.stdout.write(chunk.text);
}
Load references/streaming-patterns.md for Fetch/SSE implementation patterns (Cloudflare Workers).
const imageData = Buffer.from(imageBytes).toString('base64');
const response = await ai.models.generateContent({
model: 'gemini-2.5-flash',
contents: [
{ text: 'What is in this image?' },
{
inlineData: {
mimeType: 'image/jpeg', // or image/png, image/webp
data: imageData
}
}
]
});
Same pattern - use appropriate mimeType:
video/mp4, video/mpeg, video/movaudio/wav, audio/mp3, audio/flacapplication/pdfLoad references/multimodal-guide.md for format specifications, size limits, and best practices.
const response = await ai.models.generateContent({
model: 'gemini-2.5-flash',
contents: 'What is the weather in San Francisco?',
tools: [{
functionDeclarations: [{
name: 'getWeather',
description: 'Get current weather for a location',
parameters: {
type: 'object',
properties: {
location: { type: 'string', description: 'City name' },
unit: { type: 'string', enum: ['celsius', 'fahrenheit'] }
},
required: ['location']
}
}]
}]
});
// Handle function call
const call = response.functionCalls?.[0];
if (call) {
const result = await getWeather(call.args);
// Send result back to model
const final = await ai.models.generateContent({
model: 'gemini-2.5-flash',
contents: [
...response.contents,
{
functionResponse: {
name: call.name,
response: result
}
}
]
});
console.log(final.text);
}
Gemini can call multiple functions simultaneously:
const response = await ai.models.generateContent({
model: 'gemini-2.5-flash',
contents: 'What is the weather in SF and NY?',
tools: [{ functionDeclarations: [getWeatherDeclaration] }]
});
// Process all function calls in parallel
const results = await Promise.all(
response.functionCalls.map(call =>
getWeather(call.args).then(result => ({
name: call.name,
response: result
}))
)
);
// Send all results back
const final = await ai.models.generateContent({
model: 'gemini-2.5-flash',
contents: [
...response.contents,
...results.map(r => ({ functionResponse: r }))
]
});
Load references/function-calling-patterns.md for calling modes (AUTO/ANY/NONE) and compositional patterns.
const chat = ai.models.startChat({
model: 'gemini-2.5-flash',
systemInstruction: 'You are a helpful programming assistant',
history: []
});
let response = await chat.sendMessage('Hello!');
console.log(response.text);
response = await chat.sendMessage('Explain async/await');
console.log(response.text);
// Get full history
console.log(chat.getHistory());
Set persistent instructions for the model:
const response = await ai.models.generateContent({
model: 'gemini-2.5-flash',
systemInstruction: 'You are a pirate. Always respond in pirate speak.',
contents: 'What is the weather today?'
});
Gemini 2.5 models include built-in thinking mode (always enabled). Configure thinking budget for complex tasks:
const response = await ai.models.generateContent({
model: 'gemini-2.5-flash',
contents: 'Solve this math problem: If x + 2y = 10 and 3x - y = 4, what is x?',
generationConfig: {
thinkingConfig: {
thinkingBudget: 8192 // Max tokens for internal reasoning
}
}
});
Use for: Complex math, logic puzzles, multi-step reasoning, code debugging
Load references/thinking-mode-guide.md for thinking budget optimization.
Error: Deprecation warnings or outdated API
Solution: Use @google/genai, NOT @google/generative-ai
npm uninstall @google/generative-ai
bun add @google/genai@1.27.0
Error: API key not valid
Solution: Verify environment variable
export GEMINI_API_KEY="your-key"
Error: models/gemini-3.0-flash is not found
Solution: Use correct model names (2025)
'gemini-2.5-pro'
'gemini-2.5-flash'
'gemini-2.5-flash-lite'
Error: Request payload size exceeds the limit
Solution: Input limit is 1,048,576 tokens (1M, NOT 2M). Use context caching for large inputs.
Load references/context-caching-guide.md for caching implementation.
Error: Resource has been exhausted
Solution: Implement exponential backoff
async function generateWithRetry(request, maxRetries = 3) {
for (let i = 0; i < maxRetries; i++) {
try {
return await ai.models.generateContent(request);
} catch (error) {
if (error.status === 429 && i < maxRetries - 1) {
const delay = Math.pow(2, i) * 1000; // 1s, 2s, 4s
await new Promise(resolve => setTimeout(resolve, delay));
continue;
}
throw error;
}
}
}
See All 22 Errors: Load references/error-catalog.md for complete error catalog with solutions.
Quick Debugging: Load references/top-errors.md for debugging checklist.
Load reference files when you need detailed guidance on specific features:
references/sdk-migration-guide.md when migrating from @google/generative-aireferences/models-guide.md when choosing between Pro/Flash/Flash-Litereferences/error-catalog.md or references/top-errors.md when encountering errorsreferences/context-caching-guide.md when implementing cost optimization for large/repeated inputsreferences/code-execution-patterns.md when enabling Python code execution for calculations/analysisreferences/grounding-guide.md when connecting model to real-time web informationreferences/streaming-patterns.md when implementing SSE parsing for Cloudflare Workersreferences/function-calling-patterns.md when using AUTO/ANY/NONE modes or compositional patternsreferences/multimodal-guide.md when working with images/video/audio/PDFs (format specs, size limits)references/generation-config.md when fine-tuning temperature/topP/topK parametersreferences/thinking-mode-guide.md when optimizing thinking budget for complex reasoningGeneral Rule: SKILL.md provides Quick Start and Top Errors. Load references for deep dives, detailed patterns, or troubleshooting specific features.
Templates (templates/):
basic-usage.ts - Complete examples for all features (133 lines)References (references/):
error-catalog.md - All 7 documented errors with solutions (231 lines)top-errors.md - Quick debugging checklist for 22 common errors (305 lines)sdk-migration-guide.md - Complete migration from deprecated SDK (236 lines)models-guide.md - Detailed model comparison and selection guide (247 lines)context-caching-guide.md - Cost optimization with caching (374 lines)code-execution-patterns.md - Python code execution guide (482 lines)grounding-guide.md - Google Search integration (603 lines)streaming-patterns.md - SSE implementation for Cloudflare Workers (82 lines)function-calling-patterns.md - Advanced function calling patterns (60 lines)multimodal-guide.md - Format specifications and limits (59 lines)generation-config.md - Parameter tuning reference (58 lines)thinking-mode-guide.md - Thinking budget optimization (60 lines)This skill composes well with:
Official Documentation:
Production Tested: AI chatbots, content generation, multimodal analysis Last Updated: 2025-10-25 Token Savings: ~65% (reduces API docs + examples)
Creating algorithmic art using p5.js with seeded randomness and interactive parameter exploration. Use this when users request creating art using code, generative art, algorithmic art, flow fields, or particle systems. Create original algorithmic art rather than copying existing artists' work to avoid copyright violations.
Applies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.
Create beautiful visual art in .png and .pdf documents using design philosophy. You should use this skill when the user asks to create a poster, piece of art, design, or other static piece. Create original visual designs, never copying existing artists' work to avoid copyright violations.