Skills in Gemini CLI

Skills in Gemini CLI are modular, on-demand capabilities that give Gemini specialized expertise for particular tasks. Instead of loading every possible instruction into the model at once, Gemini can discover the right skill when needed and activate it only for that request.

This makes Gemini CLI more scalable, cleaner, and more context-efficient. For example, you might have one skill for security audits, another for cloud deployment, and another for code migration.

Official Link:https://geminicli.com/docs/cli/skills/

Skills vs GEMINI.md

A GEMINI.md file is used to provide persistent workspace-wide guidance. It usually contains background information, coding conventions, architecture notes, or instructions that should be available throughout the session.

A Skill is different. A skill is not always active. It acts like a focused toolkit that Gemini can pull in only when a user request matches that skill’s description.

• GEMINI.md = always-available workspace context
• Skills = on-demand expertise loaded only when required
• GEMINI.md keeps background rules
• Skills keep task-specific workflows, scripts, and references

Why Skills Matter

Without skills, the model would need to keep too many instructions in memory, which can clutter the context window. Skills solve this by letting Gemini maintain a large library of specialized capabilities while only loading the relevant one at the moment of use.

• Keeps the prompt context cleaner
• Allows reusable expertise across projects
• Supports task-specific instructions and resources
• Improves maintainability for complex workflows

How Gemini Uses a Skill

Gemini autonomously decides when to use a skill based on the user’s request and the skill’s description. When Gemini identifies a matching skill, it uses the activate_skill tool to pull in the full instructions and related resources.

Typical workflow:

1. The user asks for a task
2. Gemini scans available skill descriptions
3. Gemini finds the most relevant skill
4. Gemini activates the skill
5. Gemini follows the skill instructions to complete the task

Skill Directory Precedence

Within the same tier (user or workspace), the .agents/skills/ alias takes precedence over the .gemini/skills/ directory. This makes .agents/skills/ the preferred generic path when you want compatibility with multiple AI agent tools.

• .agents/skills/ = preferred generic alias
• .gemini/skills/ = Gemini-specific location
• If both exist in the same tier, .agents/skills/ wins

Managing Skills in an Interactive Session

Gemini CLI provides the /skills slash command to list and manage available skills.

• /skills list: Shows all discovered skills and their status
• /skills link <path>: Links skills from a local directory using a symlink
• /skills disable <name>: Disables a skill
• /skills enable <name>: Re-enables a skill
• /skills reload: Refreshes discovered skills from all tiers

By default, /skills disable and /skills enable operate in the user scope. Use --scope workspace if you want to manage workspace-level settings.

Skill Structure

A skill is simply a directory that contains a SKILL.md file at its root.

Recommended folder structure:

Folder Structure

📁 my-skill/
├── 📄 SKILL.md       (Required) Instructions and metadata
├── 📁 scripts/       (Optional) Executable scripts
├── 📁 references/    (Optional) Static documentation
└── 📁 assets/        (Optional) Templates and other resources

Understanding SKILL.md

The SKILL.md file is the core of a skill. It uses YAML frontmatter for metadata and Markdown for the instructional body.

SKILL.md Example

---
name: code-reviewer
description:
  Use this skill to review code. It supports both local changes and remote Pull Requests.
---

# Code Reviewer

This skill guides the agent in conducting thorough code reviews.    

Important parts of SKILL.md:

• name: unique identifier for the skill. This should match the directory name.
• description: explains what the skill does and when Gemini should use it
• body: the Markdown instructions that guide Gemini when the skill is active

Best Practices for Writing Skills

• Keep the description specific so Gemini can match it correctly
• Use the body to define a clear workflow
• Store reusable scripts in the scripts folder
• Keep static references in the references folder
• Add templates or sample assets in the assets folder
• Name the skill directory to match the skill name

Example Use Cases

• Security auditing skill
• Cloud deployment skill
• Database migration skill
• Documentation generator skill
• Code reviewer skill
• Testing and QA automation skill

Final Takeaway

Skills in Gemini CLI make the system more powerful by adding modular expertise on demand. They help Gemini stay efficient, avoid unnecessary context overload, and perform specialized tasks with better structure and consistency.