Gemini Gems & Skills Guide

1. You create a Gem in the Gemini app
2. Define its name, instructions, and optional files
3. Gemini saves the configuration as a reusable expert
4. Start a new chat with the Gem anytime
5. The Gem applies your instructions to every message
6. Responses follow the style, tone, and rules you set

- Persona: Who the Gem pretends to be (coach, editor, reviewer)
- Tone: Formal, casual, technical, friendly
- Expertise: Niche domain knowledge and specializations
- Output format: Bullet points, paragraphs, code, tables
- Constraints: What the Gem should avoid or always include
- Context files: Upload documents to give the Gem background knowledge

- Learning Coach: Helps you understand complex topics step-by-step
- Brainstormer: Generates creative ideas and explores concepts
- Career Guide: Advises on professional development and job search
- Writing Editor: Refines your writing for clarity and style
- Coding Partner: Assists with programming tasks and debugging

┌──────────────────┬──────────────────────────────────────┐
│ Gemini Gems      │ GEMINI.md                            │
├──────────────────┼──────────────────────────────────────┤
│ Consumer product │ Developer configuration              │
│ Gemini web/app   │ Code editors (Copilot, IDEs)         │
│ GUI-based setup  │ Markdown file in repo root           │
│ Personal use     │ Shared with team via version control  │
│ Chat interface   │ Agent instructions for code tasks     │
│ Upload files     │ References project files/structure    │
│ Google account   │ Any editor supporting GEMINI.md       │
└──────────────────┴──────────────────────────────────────┘

Use Gemini Gems when you want to:
- Create a personal AI expert for everyday tasks
- Save prompt instructions you reuse in chat
- Build a writing coach, research assistant, or tutor
- Share a Gem with friends or colleagues via link
- Work in the Gemini app (web, Android, iOS)

Use GEMINI.md when you want to:
- Configure AI agent behavior for a code repository
- Share coding conventions with your team via Git
- Define project-specific instructions for Gemini in editors
- Set up coding standards, architecture rules, and patterns
- Give AI context about your codebase structure

# AI agent configuration files by tool
project-root/
├── GEMINI.md          # Google Gemini agent instructions
├── CLAUDE.md          # Anthropic Claude agent instructions
├── AGENTS.md          # GitHub Copilot agent instructions
├── COPILOT.md         # GitHub Copilot (alternative)
├── .cursorrules       # Cursor IDE rules
├── .cursor/
│   └── rules/         # Cursor IDE rules (directory)
├── .windsurfrules     # Windsurf editor rules
└── .github/
    └── copilot-instructions.md  # Copilot repo-level config

1. Go to gemini.google.com (or open the Gemini mobile app)
2. Click the "Gem manager" option in the left sidebar
3. Click "New Gem" (or "Create" on mobile)
4. You'll see the Gem creation interface with fields for:
   - Name
   - Custom instructions
   - File uploads

# Good Gem names
- "TypeScript Code Reviewer"
- "Blog Post Editor"
- "SQL Query Helper"
- "React Component Designer"
- "API Documentation Writer"

# Bad Gem names (too vague)
- "Helper"
- "My Gem"
- "Coding"
- "Work Stuff"

You are a senior TypeScript code reviewer. When I share code:

1. Check for type safety issues and suggest stricter types
2. Identify potential runtime errors
3. Suggest performance improvements
4. Flag any security concerns
5. Recommend modern TypeScript patterns (5.x features)

Always format your review as:
- 🔴 Critical: Must-fix issues
- 🟡 Warning: Should-fix improvements
- 🟢 Suggestion: Nice-to-have enhancements

Be direct and specific. Show corrected code examples for
every issue you find. Use TypeScript code blocks.

Supported file types:
- Documents: PDF, TXT, Markdown, DOCX
- Code files: JS, TS, Python, and more
- Data: CSV, JSON
- Images: JPG, PNG (for visual context)

Use cases for file uploads:
- Style guides and coding standards
- API documentation or schemas
- Example outputs you want the Gem to emulate
- Reference materials for niche domains
- Project architecture documents

Testing checklist:
1. Send a typical request — does the Gem follow your format?
2. Send an edge case — does it handle unusual inputs?
3. Send a vague prompt — does it ask for clarification?
4. Check tone and style — does it match your instructions?
5. Verify constraints — does it avoid things you prohibited?

If the Gem isn't behaving as expected:
→ Go back to Gem manager and edit the instructions
→ Add more specific rules or examples
→ Clarify ambiguous instructions

# Root-level configuration (applies to entire repo)
your-project/
├── GEMINI.md          # Agent instructions for this repo
├── package.json
├── tsconfig.json
└── src/

# Subdirectory overrides (optional, for monorepos)
your-monorepo/
├── GEMINI.md          # Base instructions
├── packages/
│   ├── frontend/
│   │   └── GEMINI.md  # Frontend-specific instructions
│   └── backend/
│       └── GEMINI.md  # Backend-specific instructions
└── shared/

# Project Name

Brief description of the project and its purpose.

## Tech Stack

- Framework: Next.js 15 (App Router)
- Language: TypeScript (strict mode)
- Styling: Tailwind CSS v4
- Database: PostgreSQL with Drizzle ORM
- Testing: Vitest + Playwright

## Architecture

Describe the project architecture, folder structure,
and key patterns used throughout the codebase.

## Code Conventions

- Use functional components with TypeScript interfaces
- Prefer named exports over default exports
- Use `async/await` instead of `.then()` chains
- All components must have corresponding test files

## Instructions

When generating or modifying code in this project:

1. Always use TypeScript strict mode
2. Follow the existing folder structure
3. Add JSDoc comments to exported functions
4. Run lint and type-check before completing

Tools that support GEMINI.md:
- GitHub Copilot: Reads GEMINI.md for repo-level context
- Google IDX: Native support for Gemini configuration
- Firebase Studio: Integrates GEMINI.md instructions
- Gemini Code Assist: Uses GEMINI.md in enterprise setups
- VS Code (with Copilot): Picks up GEMINI.md automatically

How tools read GEMINI.md:
1. Tool detects GEMINI.md in the repository root
2. Contents are loaded as system-level context
3. Agent applies the instructions to all code operations
4. Subdirectory overrides are merged when applicable

Strategy 1: Shared core with tool-specific extras
- Keep common conventions in all files
- Add tool-specific features where needed
- Example: Cursor rules reference .cursor/rules/ directory,
  GEMINI.md stays flat in the repo root

Strategy 2: Single source of truth
- Maintain one primary file (e.g., AGENTS.md)
- Other files reference or symlink to it
- Reduces duplication and drift

Strategy 3: Generator tools
- Use tools like the Gemini Skills Generator to create
  consistent configuration across all formats
- Export the same rules to GEMINI.md, CLAUDE.md, etc.

# Clear role definition
You are a senior frontend developer specializing in React
and TypeScript. You have 10+ years of experience building
production web applications. You follow modern best
practices and prioritize type safety and accessibility.

# Vague role definition (avoid this)
You are a helpful coding assistant.

# Good — explicit format requirements
When reviewing code, always respond with:

1. **Summary** (1-2 sentences of overall assessment)
2. **Issues Found** (numbered list with severity labels)
3. **Corrected Code** (full corrected code block)
4. **Explanation** (why each change was made)

# Bad — no format guidance
Review the code and tell me what's wrong.

## Constraints

DO:
- Use TypeScript strict mode for all code examples
- Include error handling in every function
- Add accessibility attributes to HTML elements
- Suggest the simplest solution that meets requirements

DO NOT:
- Use `any` type in TypeScript
- Suggest deprecated APIs or patterns
- Skip input validation on public functions
- Use inline styles in React components

## Example Interaction

User: "Create a custom React hook for local storage"

Expected response format:
- Brief explanation of the hook's purpose
- Full TypeScript implementation with generics
- Usage example showing the hook in a component
- Note about SSR considerations (window check)

import { useState, useEffect } from 'react';

function useLocalStorage<T>(
  key: string,
  initialValue: T
): [T, (value: T | ((prev: T) => T)) => void] {
  const [storedValue, setStoredValue] = useState<T>(() => {
    if (typeof window === 'undefined') return initialValue;
    try {
      const item = window.localStorage.getItem(key);
      return item ? (JSON.parse(item) as T) : initialValue;
    } catch {
      return initialValue;
    }
  });

  useEffect(() => {
    try {
      window.localStorage.setItem(key, JSON.stringify(storedValue));
    } catch (error) {
      console.warn(`Error setting localStorage key "${key}":`, error);
    }
  }, [key, storedValue]);

  return [storedValue, setStoredValue];
}

# Project Name

## Tech Stack
(list technologies with versions)

## Architecture
(describe folder structure and patterns)

## Code Conventions
(bullet-point list of rules)

## Testing
(how to write and run tests)

## Deployment
(CI/CD and deployment steps)

## Common Tasks
(step-by-step guides for frequent operations)

# Coding Assistant

You are an expert software developer. When I ask for help:

1. Ask clarifying questions if the request is ambiguous
2. Write clean, well-documented code with TypeScript
3. Include error handling and edge cases
4. Explain your approach before showing code
5. Suggest tests for any function you create

Preferences:
- Use functional programming patterns where appropriate
- Prefer composition over inheritance
- Always handle async errors with try/catch
- Use descriptive variable names (no single letters)
- Add JSDoc comments to exported functions

# Writing Coach

You are a professional writing editor. When I share text:

1. Identify areas for improvement in clarity and flow
2. Suggest more concise alternatives for wordy passages
3. Fix grammar, punctuation, and style issues
4. Preserve my voice and intent — refine, don't rewrite
5. Explain each suggested change briefly

Style guidelines:
- Prefer active voice over passive voice
- Keep sentences under 25 words when possible
- Use parallel structure in lists
- Avoid jargon unless writing for a technical audience
- One idea per paragraph

# Code Reviewer

You are a thorough code reviewer. For every code review:

1. Check for correctness and potential bugs
2. Evaluate type safety (TypeScript strictness)
3. Look for security vulnerabilities
4. Assess performance implications
5. Verify error handling completeness
6. Check code readability and naming

Format your review as:
🔴 Critical — Bugs, security issues, data loss risks
🟡 Warning — Code quality, missing edge cases
🟢 Suggestion — Style improvements, refactoring ideas

Always provide corrected code for critical and warning items.

# Documentation Writer

You are a technical documentation specialist. When I ask
you to document something:

1. Start with a one-line summary
2. Add a "Description" section with context
3. Include a "Parameters" or "Props" table
4. Add at least 2 usage examples (basic and advanced)
5. Note any caveats, edge cases, or gotchas

Formatting rules:
- Use Markdown with proper heading hierarchy
- Code examples use syntax-highlighted fenced blocks
- Tables use Markdown pipe syntax
- Keep explanations concise but complete

# Project Name

A brief description of what this project does.

## Tech Stack

- Runtime: Node.js 22
- Framework: Next.js 15 (App Router)
- Language: TypeScript 5.x (strict mode)
- Styling: Tailwind CSS v4
- State: Zustand
- Database: PostgreSQL + Drizzle ORM
- Testing: Vitest (unit) + Playwright (e2e)

## Folder Structure

src/
├── app/          # Next.js App Router pages
├── components/   # Reusable UI components
├── hooks/        # Custom React hooks
├── lib/          # Utility functions and configs
├── server/       # Server-side code and API logic
├── types/        # Shared TypeScript types
└── test/         # Test utilities and fixtures

## Code Conventions

- Use functional components with arrow functions
- Define props with TypeScript interfaces (not types)
- Use path aliases: `@/` maps to `src/`
- Co-locate tests with source files (*.test.ts)
- Use `async/await` for all asynchronous code
- Handle errors with custom error classes

## Naming

- Components: PascalCase (UserProfile.tsx)
- Hooks: camelCase with "use" prefix (useAuth.ts)
- Utilities: camelCase (formatDate.ts)
- Types: PascalCase with no suffix (User, not UserType)
- Constants: UPPER_SNAKE_CASE

## Testing

- Unit tests: Vitest with React Testing Library
- E2E tests: Playwright in tests/ directory
- Run tests: npm test
- Run e2e: npm run test:e2e

Agent Designer capabilities:
- Build agents from natural language prompts
- Connect agents to Google Workspace data (Gmail, Drive, Docs)
- Integrate with third-party tools (Jira, Slack, etc.)
- Create multi-step automated workflows
- Visual flow builder for complex agent logic
- Test agents before deploying to your organization
- Share agents across your Google Workspace

Method 1: Prompt-Based Creation
1. Describe what you want the agent to do in plain English
2. Agent Designer generates the configuration
3. Review and refine the generated instructions
4. Test the agent with sample queries
5. Deploy to your organization

Method 2: Visual Flow Builder
1. Start with a blank canvas or template
2. Add steps (prompts, conditions, data lookups)
3. Connect steps with flow arrows
4. Configure each step's inputs and outputs
5. Add data source connections
6. Test the complete flow
7. Publish the agent

Agents can connect to:

Google Workspace:
- Gmail (search and read emails)
- Google Drive (access documents and files)
- Google Docs (read and reference content)
- Google Sheets (query structured data)
- Google Calendar (check schedules)

Third-party integrations:
- Jira (issue tracking and project management)
- Confluence (knowledge base articles)
- Slack (messaging and notifications)
- Custom APIs (via webhook connectors)

┌────────────────┬──────────────┬──────────────┬─────────────┐
│                │ Gems         │ GEMINI.md    │ Agent       │
│                │              │              │ Designer    │
├────────────────┼──────────────┼──────────────┼─────────────┤
│ Audience       │ Everyone     │ Developers   │ Enterprise  │
│ Interface      │ Gemini app   │ Text file    │ Visual UI   │
│ Complexity     │ Simple       │ Medium       │ Complex     │
│ Data access    │ Uploaded     │ Repo files   │ Live APIs   │
│ Collaboration  │ Share link   │ Git          │ Workspace   │
│ Workflows      │ Single chat  │ Code tasks   │ Multi-step  │
│ Cost           │ Free/Premium │ Free         │ Enterprise  │
└────────────────┴──────────────┴──────────────┴─────────────┘

# Email Drafting Gem
- Writes professional emails in your voice
- Adjusts tone (formal, friendly, urgent)
- Handles common templates (follow-up, intro, feedback)

# Meeting Summarizer Gem
- Extracts action items from meeting notes
- Highlights key decisions and owners
- Formats output as a shareable summary

# Research Assistant Gem
- Analyzes documents and extracts key findings
- Compares multiple sources for consistency
- Produces structured literature reviews

# Frontend project GEMINI.md use cases

Code generation:
- Generate components following project patterns
- Scaffold API routes with validation
- Create test files matching testing conventions

Code review:
- AI reviews PRs using project-specific rules
- Catches violations of coding standards
- Suggests refactoring based on architecture docs

Documentation:
- Auto-generates JSDoc from function signatures
- Creates README sections for new features
- Updates API documentation when endpoints change

# Customer Support Agent
- Searches knowledge base for relevant articles
- Pulls customer data from CRM integration
- Drafts response following support guidelines
- Escalates complex issues to human agents

# Employee Onboarding Agent
- Guides new hires through setup steps
- Answers policy questions from the handbook
- Schedules onboarding meetings via Calendar
- Tracks completion status in a Sheet

# Sales Research Agent
- Gathers company information from Drive documents
- Summarizes recent email threads with prospects
- Generates personalized outreach drafts
- Logs activity to the CRM

# Language Tutor Gem
- Practices conversation in the target language
- Corrects grammar with explanations
- Adjusts difficulty based on your level
- Teaches vocabulary in context

# Study Buddy Gem
- Creates flashcards from your study material
- Quizzes you on key concepts
- Explains topics using analogies
- Tracks which areas need more review

# Bad — too broad, tries to do everything
"You are a developer who can write any code in any
language, review code, write docs, manage deployments,
handle database migrations, and debug any issue."

# Good — focused on one domain
"You are a TypeScript code reviewer specializing in React
applications. You focus on type safety, performance, and
accessibility. You review code using a structured format
with severity levels."

# Bad — no format guidance
"Help me with code."

# Good — explicit format expectations
"When I share code, respond with:
1. A brief assessment (1-2 sentences)
2. A numbered list of issues, each with:
   - Severity label (Critical/Warning/Suggestion)
   - File and line reference
   - Explanation of the issue
   - Corrected code snippet
3. An overall score out of 10"

# Good GEMINI.md includes architecture context

## Architecture

This is a Next.js App Router project with:
- Server Components by default (use "use client" only when needed)
- Server Actions for mutations (no API routes for form submissions)
- Drizzle ORM with PostgreSQL for data persistence
- Redis for caching and session storage
- S3-compatible storage for file uploads

## Key Patterns

- Data fetching happens in Server Components
- Client components receive data as props
- All database queries go through src/server/db/
- Authentication uses middleware in src/middleware.ts
- Feature flags are in src/lib/flags.ts

# GEMINI.md header example

# My Project

Last updated: 2026-02-06
Maintainer: Team Name

This file provides AI agent instructions for the project.
Update this file when architecture or conventions change.

After creating a Gem or GEMINI.md, test with:

1. Simple request — does it follow basic instructions?
2. Complex request — does it handle multi-step tasks?
3. Ambiguous request — does it ask for clarification?
4. Edge case — does it handle unusual inputs gracefully?
5. Out-of-scope request — does it stay within its domain?
6. Contradictory request — does it flag the conflict?

Improvement cycle:

1. Create initial instructions
2. Test with 5-10 different prompts
3. Note where the output misses expectations
4. Add specific rules to address gaps
5. Remove instructions that cause confusion
6. Re-test and repeat

Common refinements:
- Add explicit "DO NOT" rules for unwanted behaviors
- Include example outputs for ambiguous formats
- Break complex instructions into numbered steps
- Add checkpoints ("Before proceeding, verify...")

Problem: Gem doesn't follow your custom instructions

Solutions:
1. Keep instructions under ~1500 words — very long
   instructions can cause the model to skip sections
2. Put the most important rules at the beginning
3. Use numbered lists instead of long paragraphs
4. Repeat critical constraints at the end ("Remember:
   always use TypeScript strict mode")
5. Test with a fresh chat — previous messages may
   override Gem instructions

Problem: Code editor ignores GEMINI.md

Solutions:
1. Verify the file is in the repository root directory
2. Check the filename is exactly "GEMINI.md" (case-sensitive)
3. Ensure your editor/tool version supports GEMINI.md
4. For GitHub Copilot: check that repo-level instructions
   are enabled in settings
5. Restart the editor after adding the file
6. Verify the file is not in .gitignore

Problem: Same Gem gives different formats/styles

Solutions:
1. Add a strict output template in your instructions:
   "Always respond using exactly this format..."
2. Include an example of the expected output
3. Add constraints: "Never deviate from this format,
   even if asked to"
4. Use numbered sections in the output format so the
   model has a clear structure to follow

Problem: Agent Designer flow fails at a step

Solutions:
1. Check data source connections are authorized
2. Verify API credentials haven't expired
3. Test each step individually before connecting them
4. Check that step outputs match the next step's expected
   input format
5. Review the error logs in the Agent Designer console
6. Simplify the flow — break complex steps into smaller ones

Problem: Gem doesn't reference uploaded files

Solutions:
1. Explicitly mention the files in your instructions:
   "Refer to the uploaded style guide when reviewing"
2. Keep uploaded files under the size limit
3. Use supported file formats (PDF, TXT, MD, DOCX)
4. Re-upload files if they were added after Gem creation
5. Reference specific sections: "Use the 'Naming
   Conventions' section from the uploaded standards doc"