Where Are Gemini CLI Skills Stored?
Gemini CLI looks for skills in three distinct locations, following a specific search order that determines which version loads when duplicates exist. Understanding these file paths explains how the tool discovers and prioritizes your SKILL.md spec files.
The search happens every time you run a command. First, Gemini checks your current project directory. Then it scans your user-level skills folder. Finally, it loads any plugin-installed skills from the global directory.
Project-local skills directory
Your current working directory gets checked first for a .gemini/skills/ folder:
./gemini/skills/
├── data-analysis.md
├── code-review.md
└── custom-parser.md
Project-local skills take precedence over everything else. If you have a skill called "debug" in both your project folder and your user directory, the project version wins. This design lets you override global skills for specific codebases.
The dot-prefix keeps the folder hidden from most file browsers, similar to .git or .env files. You can create this directory manually or let Gemini CLI generate it when you first install skills locally.
Most developers use project-local skills for codebase-specific workflows. Database migration skills, deployment scripts, or custom linting rules work well here since they need access to project files and configuration.
User-level skills storage
Your personal skills live in the OS-appropriate config directory. On macOS and Linux, that's ~/.config/gemini-cli/skills/. Windows uses %APPDATA%\gemini-cli\skills\.
~/.config/gemini-cli/skills/
├── git-workflow.md
├── api-testing.md
├── documentation.md
└── personal-templates.md
Skills stored here work across all your projects. They're perfect for general-purpose workflows you use daily. Code formatting, commit message generation, or API documentation skills make sense at the user level.
The CLI creates this directory automatically on first run. You don't need to set it up manually, but you can browse it directly to see what's installed.
User-level skills get loaded after project-local ones but before global plugins. This means you can still override a user skill with a project-specific version when needed.
Plugin-installed global skills
The global skills directory contains skills installed through the plugin system. Location varies by platform but typically lives alongside the CLI installation:
/usr/local/lib/gemini-cli/skills/
├── markdown-processor.md
├── json-validator.md
└── text-summarizer.md
These skills come from the browse skills marketplace or third-party repositories. They're read-only from your perspective since the plugin manager handles installation and updates.
Global skills load last in the priority chain. They provide baseline functionality that works everywhere but can be superseded by your personal or project versions.
The plugin system handles version management, dependency resolution, and automatic updates for global skills. You interact with them through commands like gemini install skill-name rather than direct file manipulation.
Search order and conflicts
When multiple skills share the same name, Gemini CLI follows a clear precedence:
- Project-local (
.gemini/skills/filename.md) - User-level (
~/.config/gemini-cli/skills/filename.md) - Global plugins (
/usr/local/lib/gemini-cli/skills/filename.md)
This hierarchy lets you progressively specialize. Start with a global skill from the marketplace, customize it in your user directory, then create project-specific versions when needed.
The CLI doesn't merge skills with identical names. The highest-priority version completely shadows lower ones. If you want to combine functionality, you need different filenames or explicit skill composition.
Skill discovery process
Gemini CLI scans these directories on every command execution. It builds an in-memory index of available skills, checking file modification times to detect changes.
The discovery process reads the skill name from each file's metadata header, not the filename. A file called my-awesome-tool.md might register a skill named "debug" or "format". This separation lets you organize files however makes sense locally.
# Skill: debug-api
# Description: Debug REST API responses with structured logging
Files without proper headers get ignored silently. Malformed SKILL.md spec files don't break the loading process, but they won't be available for use.
Working with skill locations
You can check which skills Gemini CLI found and where they loaded from:
gemini skills list --verbose
This command shows the full file path for each discovered skill, making it easy to trace which version you're actually using.
To override a global skill temporarily, copy it to your user directory and modify as needed. For permanent project-specific changes, place the customized version in .gemini/skills/.
The modular approach means you can mix sources freely. Use marketplace skills for common tasks, user-level skills for personal workflows, and project skills for codebase-specific automation.
Understanding where Gemini CLI skills are stored helps you organize workflows effectively. Project isolation, user customization, and global sharing each serve different needs in a typical development environment.
The three-tier system balances convenience with control. You get curated skills from the browse skills marketplace, room for personal customization, and project-specific overrides when standard approaches don't fit your codebase.
