GEMINI.md System Instructions: Setup & Context Rules Guide

How Do GEMINI.md System Instructions Steer Google Gemini CLI?

GEMINI.md system instructions are persistent, repository-level markdown context files that automatically steer the model persona, architectural conventions, coding style, and verification constraints for every Google Gemini CLI session within a workspace. Rather than requiring developers to manually pass repetitive --system-instruction flags on every command, placing a GEMINI.md file in your repository root injects authoritative project guidance directly into Gemini CLI's multi-million token context window.

According to the official Google Gemini API & CLI Documentation: “System instructions allow users to steer the behavior of the model based on their specific needs and use cases, providing persistent context across the conversation.” In the Gemini CLI environment, these instructions can be passed as CLI arguments via --system-instruction, declared in user configuration files like ~/.gemini/settings.json, or loaded automatically from a repository root file named GEMINI.md.

As detailed in the Anthropic Claude Code Documentation: “Skills are modular packages containing a SKILL.md file and optional supporting files that provide reusable instructions, scripts, and context to Claude Code.” While Gemini CLI loads the entire instruction block into the model preamble at session startup, Claude Code indexes only a compact 35-to-50 token YAML frontmatter header at launch, loading full execution instructions into memory only when the specific skill is invoked.

Where Does Gemini CLI Store System Instructions and Context Files?

Gemini CLI resolves system instructions, model settings, and context files across three distinct configuration layers: user-level global configuration, repository-level markdown context, and per-execution CLI flags. Understanding this hierarchy prevents configuration collisions when moving between different repositories and development environments.

The standard discovery paths and configuration locations for Gemini CLI include:

# 1. User Global Configuration (Applies across all terminal sessions)
~/.gemini/settings.json
~/.gemini/config.json

# 2. Repository-Level Context (Project-specific instructions)
<workspace-root>/GEMINI.md
<workspace-root>/.gemini/instructions.md

# 3. Direct CLI Command Invocation (Session override)
gemini --system-instruction "Always output strict TypeScript with Zod schemas." --prompt "Build user schema"
gemini --context-file ./GEMINI.md "Refactor auth handler"

When both a global ~/.gemini/settings.json and a local GEMINI.md exist, the local workspace configuration takes precedence, allowing teams to enforce repository-specific code review standards, linter rules, and testing requirements without polluting other projects.

How Do You Convert GEMINI.md Instructions into Claude Code SKILL.md?

Converting static GEMINI.md instructions into reusable Claude Code SKILL.md files requires wrapping the instructional body with structured YAML frontmatter, defining explicit task trigger descriptions, and decomposing monolithic guideline documents into modular workflow units.

Because Gemini CLI models like Gemini 1.5 Pro support an expansive 1,000,000-token context window, developers frequently paste massive styleguides into GEMINI.md. However, when porting these instructions to Claude Code's 200,000-token context window, monolithic context files waste token budget. Modularizing instructions into discrete skills preserves reasoning bandwidth.

The following blueprint illustrates how a monolithic Gemini CLI system instruction translates into a structured, modular SKILL.md package:

# Step 1: Legacy Gemini CLI System Instruction (GEMINI.md)
# Monolithic guideline loaded on every prompt turn:
You are an expert backend engineer. When asked to create database migrations:
1. Verify existing schema in /prisma/schema.prisma
2. Generate migration SQL with descriptive naming conventions
3. Write idempotency test fixtures in /tests/migrations/

# Step 2: Converted Claude Code Skill (skills/db-migrate/SKILL.md)
---
name: db-migrate
description: Generates, validates, and tests idempotent PostgreSQL database migrations. Use when modifying schema models or creating SQL migrations.
---

# Database Migration Workflow

## Execution Steps
1. Inspect the active schema models in `prisma/schema.prisma`.
2. Generate a new migration script using `npx prisma migrate dev --create-only`.
3. Verify that all column modifications contain backward-compatible fallback values.
4. Execute validation tests via `npm test tests/migrations/`.

## Output Contract
- Path to generated migration file
- Summary of schema alterations
- Validation test run status

By extracting the database migration process into a standalone skill directory (~/.claude/skills/db-migrate/SKILL.md), the agent loads this instruction only when handling database tasks, rather than consuming context overhead on unrelated bugfixes or frontend styling tasks.

The Sprawl Moment: When Your Multi-Agent Prompt Stack Breaks Down

You spend two full days fine-tuning a meticulous code review workflow in Gemini CLI. You configure custom system instructions, write exact formatting constraints in GEMINI.md, and test edge cases until Gemini produces flawless, production-ready reviews. The next morning, you open Claude Code on your work laptop to refactor a legacy microservice, only to realize none of those instructions exist in Claude Code's environment. You search through shell history, copy fragments of markdown from GEMINI.md, try to manually reformat them into a SKILL.md file in ~/.claude/skills/, and end up with two drifting, desynchronized versions of the same core engineering prompt. By the time you switch to a remote server or a second machine, neither agent has the current version of the workflow, and you find yourself rewriting instructions from memory for the third time this week.

Comparative Architecture Matrix: Gemini CLI, Claude Code, Google Antigravity, and Codex

Modern AI developers rarely operate inside a single CLI agent. Comparing configuration formats, default context windows, discovery paths, and execution models across major terminal agents clarifies where instructions belong and how to make them portable.

As shown in the comparison table, while Gemini CLI and Google Antigravity accommodate large static preambles thanks to multi-million token windows, Claude Code and OpenAI Codex prioritize compact, modular skill execution. Beyond static system preambles, developers frequently wrap recurring tasks into executable Gemini CLI custom commands that chain shell pipes and arguments directly into automated agent reviews. Building workflows around the standardized SKILL.md schema provides the highest degree of cross-tool portability.

Why Do CLI Instructions Fail When Moving Across Repos and Machines?

CLI instructions fail during machine migration because local system prompts and repository context files are tightly coupled to specific file paths, uncommitted git files, and machine-local configurations. When a developer switches laptops or initializes a new microservice repository, local instructions stay behind on the previous machine.

The primary failure modes that disrupt multi-agent CLI workflows include:

• Repository Trapping: Storing custom instructions exclusively in GEMINI.md or CLAUDE.md files traps high-value prompt engineering inside a single git repo. When starting a new project, developers are forced to manually copy and paste files.
• Directory Schema Incompatibilities: Gemini CLI looks for ~/.gemini/settings.json, Claude Code requires ~/.claude/skills/<skill-name>/SKILL.md, and Google Antigravity searches plugin directories. Without an automated sync engine, manual mirroring inevitably causes syntax drift.
• No Version History on CLI Prompts: Ad-hoc edits made directly inside terminal configuration files lack branch tracking and rollback capabilities, making it difficult to revert when an updated instruction causes model regressions.

How Can You Maintain One Portable Skill Library Across Gemini CLI and Claude Code?

The most sustainable strategy for managing AI developer workflows is to maintain a single, version-controlled skill library that compiles and syncs directly into each CLI agent's native filesystem directory. Rather than maintaining disparate markdown files across multiple tools, developers author their capabilities once in a centralized manager.

Prompttly is a skill manager for AI agents — one library for your skills and prompts that syncs into Claude Code, Codex, ChatGPT, and Claude and is one hotkey away on your Mac, so your setup follows you across every machine, repo, and tool.

With Prompttly, every prompt, custom instruction, and agent skill is stored in a unified cloud repository. When you update a code review workflow or database migration prompt:

• Native Two-Way Filesystem Sync: Prompttly automatically writes your skills into ~/.claude/skills/ as valid Claude Code skill folders and provisions your Gemini CLI configuration without manual formatting.
• Sub-200ms Global Mac Hotkey: The Prompttly macOS palette allows you to summon any prompt, workflow, or system instruction with a single keyboard shortcut and insert it directly into your terminal, IDE, or browser.
• Multi-Agent Portability: Workflows created for Gemini CLI remain fully functional when executing in Google Antigravity, Claude Code, and OpenAI Codex.
• Model Context Protocol (MCP) Integration: Connect external tools and database access seamlessly across your entire agent stack via MCP tool connectors.

To structure reproducible developer prompts across your entire team, explore our guide on designing a code prompt library with schemas and Git version control. To refine prompts before exporting them to your CLI agents, use our ChatGPT custom instructions generator, test instructions with our free Custom Instructions Generator tool, or compare architectures in Custom Instructions vs Skills and Cursor Rules vs Claude Skills & AGENTS.md.