Gemini CLI Skills: Installing and Using Agent Skills

Gemini CLI skills are folders with a SKILL.md file that Gemini loads on demand, after it asks you to approve them. You install one with gemini skills install, or by copying a folder into .gemini/skills or .agents/skills. Before you do, it helps to know which of Gemini CLI's three extension points fits the job, because skills, custom commands and extensions solve different problems.

This guide compares them, lists where Gemini CLI looks for skills, walks through each install method and the approval prompt, and shows a minimal skill you can write yourself.

Gemini CLI skills vs extensions vs custom commands

Google's documentation separates these on purpose, and a quick comparison saves a lot of confusion.

The skills documentation puts the last column plainly: skills are on-demand expertise, while GEMINI.md carries persistent workspace-wide background. Custom commands live in ~/.gemini/commands/ or a project's .gemini/commands/, use a prompt field in TOML, and are namespaced by subdirectory, so git/commit.toml becomes /git:commit. An extension, per the extensions documentation, can package prompts, MCP servers, custom commands, themes, hooks, sub-agents and agent skills, and is installed with gemini extensions install and a GitHub URL.

So a skill you want to share widely can ship on its own, or ride inside an extension. For the instruction-file side of that comparison, see CLAUDE.md vs AGENTS.md vs skills.

How do Gemini CLI skills load?

At the start of a session the CLI scans its skill locations and puts the name and description of each enabled skill into the system prompt. Nothing else from the skill is loaded yet. When a task matches a description, Gemini calls an activate_skill tool, and you see a confirmation prompt naming the skill and the directory it will be allowed to read. After you approve, the full SKILL.md and the skill's folder are added to the conversation.

This design has two consequences. First, a description is the only thing deciding whether a skill is ever offered, so a vague one means the skill rarely triggers. Second, the prompt is a real checkpoint. Reading it, rather than approving by reflex, is the main safety control the CLI gives you.

A skill is a directory containing SKILL.md with name and description frontmatter, and optionally scripts/, references/ and assets/. Gemini takes the skill's name from the name: field, not from the folder name. The SKILL.md format reference lists every field and limit in the open specification.

Where does Gemini CLI look for skills?

Locations are listed here from lowest to highest precedence.

1. Built-in skills that ship with the CLI.
2. Extension skills, bundled inside installed extensions.
3. User skills in ~/.gemini/skills/ or the alias ~/.agents/skills/.
4. Workspace skills in .gemini/skills/ or the alias .agents/skills/ in your project.

When two skills share a name, the higher tier wins. Within a tier, the .agents/skills/ folder beats .gemini/skills/. Workspace skills load only when the folder is trusted. SKILL.md must sit at the root of a skills folder or one directory below it, and deeper nesting is not discovered.

Using .agents/skills/ has a practical benefit: the same folder is read by several other agents, so one copy of a skill can serve more than one tool. The Gemini CLI page in this directory carries the full, verified list.

How do you install a Gemini CLI skill?

The examples use frontend-design from anthropics/skills, located at skills/frontend-design in that repository.

Option 1: gemini skills install

gemini skills install https://github.com/anthropics/skills.git --path skills/frontend-design

--path names the sub-directory of the repository that holds the skill. The default scope is user, and --scope workspace installs into the current project. The CLI asks you to confirm the security risks first. The --consent flag skips that prompt, so use it only for sources you have already reviewed. The command also accepts a local directory.

Option 2: the skills CLI

npx skills add anthropics/skills --skill frontend-design -a gemini-cli

This installs into .agents/skills/ in the current project. Add -g for ~/.gemini/skills/. The tool comes from the vercel-labs/skills repository.

Option 3: GitHub CLI

gh skill install anthropics/skills frontend-design --agent gemini-cli
gh skill install anthropics/skills frontend-design --agent gemini-cli --scope user

This needs GitHub CLI 2.90.0 or later, where gh skill is a public preview. The gh skill install manual lists the full flags, including --pin.

Option 4: copy the folder

git clone --depth 1 https://github.com/anthropics/skills.git skills-src
mkdir -p .gemini/skills
cp -r skills-src/skills/frontend-design .gemini/skills/frontend-design
rm -rf skills-src

Use ~/.gemini/skills/ for a personal install. If Gemini CLI is already running, refresh with /skills reload.

Manage skills from the shell and inside a session

Inside a session, /skills list shows what Gemini found. Add all to include built-in skills, or nodesc to hide descriptions. From the shell, gemini skills list --all prints the same information. After adding files, /skills reload rescans every tier without a restart.

Disable and enable default to user scope, and --scope workspace targets project settings. The documentation lists install, uninstall and link but no separate update command, so to pick up a newer version, uninstall the skill and install it again. If you used npx skills or gh skill, their own update commands apply to what they installed.

What does a minimal Gemini CLI skill look like?

This example is our own illustration of the format, not a skill from the directory. Save it as .gemini/skills/changelog-entry/SKILL.md:

---
name: changelog-entry
description: Writes a changelog entry from the staged git diff. Use when the user asks for a changelog line, release note or "what changed".
---

1. Run `git diff --staged` and read the result.
2. Write one line in the past tense that names the user-visible change.
3. If the diff touches only tests or comments, say so instead of inventing a change.

The first line of the file must be the opening ---, with no heading or blank line before it, or Gemini skips the skill. Run /skills reload, then ask for a changelog entry and watch for the approval prompt. For help drafting and testing larger skills, the skill authoring topic lists several, including Skill Creator, which drafts a skill, tests it on sample prompts and tunes its description. It is Apache-2.0 licensed.

Which directory skills fit Gemini CLI?

Any skill that follows the open format can be installed, and you should still read each one first. These are described from the directory's listings. We have not run them inside Gemini CLI, so confirm that a skill does not depend on features of a different agent.

• MCP Server Builder guides designing MCP servers in TypeScript or Python, which matters if you plan to bundle one in an extension. Apache-2.0. See also the MCP topic.
• Writing Implementation Plans turns a spec into a step-by-step plan of small tasks before code is touched. MIT.
• PR Babysitter watches a GitHub pull request, handles review comments and diagnoses CI failures. Apache-2.0.
• Find Skills helps discover and install skills with the npx skills CLI. MIT.

The most-used skills list and the agent workflows category have more.

Troubleshooting

• A workspace skill does not show up. The folder may not be trusted. Run /trust and restart the session. User-level skills are not affected by trust.
• A skill is silently skipped. It needs both name: and description:, the file must be named exactly SKILL.md, and the opening --- must be the first line.
• The skill appears under a different name. Gemini uses the name: field, not the folder name.
• It was nested too deep. Only the skills root and one folder below it are scanned.

Safety

Activating a skill gives Gemini access to its whole directory, and bundled scripts run through the shell tool with your permissions. Read SKILL.md and scripts/ before you approve installation or activation, and avoid --consent for repositories you have not reviewed.