Gemini CLI skills: where SKILL.md folders go and how to share them

Does Gemini CLI support Agent Skills?

Yes. Gemini CLI supports Agent Skills, the open SKILL.md folder format also used by Claude Code and Codex, and discovers skills from your home folder, your project, installed extensions and its own built-in set. The Gemini CLI skills docs describe skills as "on-demand expertise," in contrast to GEMINI.md, which is loaded into every prompt.

The practical upshot: a skill you write once works across all three tools with no changes to the file. Only the folder it lives in differs, and Gemini CLI happens to read the same .agents/skills/ folder as Codex.

How do skills work in Gemini CLI?

The docs lay out five steps:

1. Discovery. At session start, Gemini CLI scans the skill folders and adds the name and description of every enabled skill to the system prompt.
2. Activation. When your request matches a description, the model calls the activate_skill tool.
3. Consent. You see a prompt with the skill's name, purpose and the folder it will gain access to.
4. Injection. After you approve, the SKILL.md body and folder structure go into the conversation, and the skill's folder is added to the paths the agent may read.
5. Execution. The model follows the skill's instructions, and can run bundled scripts with its shell tool.

This is progressive disclosure: only a short description costs context until a skill is actually needed. Built-in skills are pre-approved; skills you add ask for consent every time they activate.

Where do Gemini CLI skills go?

Gemini CLI checks four tiers, from lowest to highest precedence:

If two skills share a name, the higher tier wins. Within the user or workspace tier, .agents/skills/ takes precedence over .gemini/skills/. The docs call .agents/skills/ "an interoperable path" that stays compatible with other AI tools.

Three layout rules from the getting started tutorial catch people out:

• SKILL.md must sit at the root of the skills folder or exactly one level down (.agents/skills/<name>/SKILL.md). Deeper files are not discovered.
• The filename must be exactly SKILL.md. On case-sensitive filesystems, skill.md is ignored.
• Workspace skills only load when the folder is trusted. Run /permissions trust and restart if they are missing. User skills are not affected by trust.

What does a Gemini CLI skill look like?

A minimal skill is one folder with one file:

.agents/skills/code-reviewer/
├── SKILL.md
└── scripts/
    └── review.js

---
name: code-reviewer
description: Reviews code changes for correctness, security and style. Use when the user asks to review their code, a diff or a pull request.
---

# Code reviewer

1. Read the changed files.
2. Run `node scripts/review.js <file>` for an automated check.
3. Report critical issues first, then minor suggestions.

Frontmatter must include both name and description and must be the very first thing in the file. Per the tutorial, a SKILL.md "is silently skipped" if either field is missing or if anything, even a blank line, comes before the opening ---. The skill's name comes from the name field, not the folder name, but the Agent Skills specification says the two should match, with name up to 64 lowercase letters, digits and hyphens and description up to 1,024 characters. Keep to the spec and the same folder works in every agent.

The description is what triggers activation. Gemini's best practices list "Define the trigger" as a rule: say when the skill should be used and include the words people will type. For a longer walkthrough, see how to write a SKILL.md.

You can also just ask: "Create a new skill called code-reviewer that checks files for common errors." The built-in skill-creator skill scaffolds the folder, the frontmatter, and scripts/, references/ and assets/ folders for you.

Which commands manage skills?

Inside a session:

From your shell, per the CLI reference:

# list skills, including built-ins
gemini skills list --all

# install from a Git repo or local path (user scope by default)
gemini skills install https://github.com/user/repo.git

# install one skill from a subfolder, for this project only
gemini skills install https://github.com/user/repo.git --path skills/code-reviewer --scope workspace

# link a folder you are developing
gemini skills link ./my-skill

# remove a skill
gemini skills uninstall my-skill

--consent skips the security confirmation on install, which is handy in scripts but means you are accepting the risk without a prompt. In settings.json, skills.enabled turns the feature on or off and skills.disabled lists skills to keep off.

How do skills relate to extensions and custom commands?

Gemini CLI has three ways to package reusable instructions, and they solve different problems.

Custom commands suit prompts you run deliberately. A file at .gemini/commands/git/commit.toml becomes /git:commit; see the custom commands docs for the syntax.

Extensions are how you distribute a bundle. Put skill folders in the extension's skills/ directory and skills/security-audit/SKILL.md becomes a security-audit skill for anyone who runs gemini extensions install <url>. For example, the Superpowers README installs its skills in Gemini CLI with gemini extensions install https://github.com/obra/superpowers.

How do you share skills between Gemini CLI, Claude Code and Codex?

All three read the same SKILL.md format, so sharing is about folders:

Sources: Gemini CLI, Codex, Claude Code.

That gives you two clean options:

1. Use .agents/skills/ for Gemini CLI and Codex, then copy the same folders into .claude/skills/ for Claude Code. In a repo, commit both.
2. Use the open source skills installer to write each skill into every agent's folder at once. Its agent list names Gemini CLI as gemini-cli:

npx skills add <owner>/<repo> -a gemini-cli -a claude-code -a codex

Add -g to install to your personal folders instead of the current project. Keep skill bodies agent-neutral: refer to "run the script" rather than a specific tool name, and avoid agent-only frontmatter you don't need. For the full cross-agent picture, read the Agent Skills guide, plus Codex skills and Claude Code skills.

One more reason to prefer .agents/skills/: Google's Antigravity CLI migration guide moves workspace skills from .gemini/skills/ to .agents/skills/, so skills already there need no move if you switch.

What should you watch out for?

• Skills run code. The docs warn that skills "can execute scripts and access your files." Read the SKILL.md and scripts of any third-party skill before installing it, and think twice before using --consent.
• Trust and restarts. Untrusted workspaces skip project skills, and new folders need /skills reload.
• Name clashes. A workspace skill silently overrides a user skill with the same name. /skills list shows which one won.
• Description overlap. Two skills with similar descriptions compete for the same requests. Make each trigger distinct.
• Keep SKILL.md lean. Gemini's guidance is under about 5k words for the body, with detail moved into references/.

Kipt keeps your Agent Skills and prompts as Markdown in a private GitHub repo you own. You can import skills from a GitHub link, a folder or a .zip, and install every skill into Claude Code or Codex with one npx skills add command.