Agent Skills

Agent Skills allow you to extend Gemini CLI with specialized expertise, procedural workflows, and task-specific resources. Based on the Agent Skills open standard, a "skill" is a self-contained directory that packages instructions and assets into a discoverable capability.

Overview

Unlike general context files (GEMINI.md), which provide persistent workspace-wide background, Skills represent on-demand expertise. This allows Gemini to maintain a vast library of specialized capabilities—such as security auditing, cloud deployments, or codebase migrations—without cluttering the model's immediate context window.

Gemini autonomously decides when to employ a skill based on your request and the skill's description. When a relevant skill is identified, the model "pulls in" the full instructions and resources required to complete the task using the activate_skill tool.

Key Benefits

• Shared Expertise: Package complex workflows (like a specific team's PR review process) into a folder that anyone can use.
• Repeatable Workflows: Ensure complex multi-step tasks are performed consistently by providing a procedural framework.
• Resource Bundling: Include scripts, templates, or example data alongside instructions so the agent has everything it needs.
• Progressive Disclosure: Only skill metadata (name and description) is loaded initially. Detailed instructions and resources are only disclosed when the model explicitly activates the skill, saving context tokens.

Skill Discovery Tiers

Gemini CLI discovers skills from three primary locations:

1. Workspace Skills: Located in .gemini/skills/ or the .agents/skills/ alias. Workspace skills are typically committed to version control and shared with the team.
2. User Skills: Located in ~/.gemini/skills/ or the ~/.agents/skills/ alias. These are personal skills available across all your workspaces.
3. Extension Skills: Skills bundled within installed extensions.

Precedence: If multiple skills share the same name, higher-precedence locations override lower ones: Workspace > User > Extension.

Within the same tier (user or workspace), the .agents/skills/ alias takes precedence over the .gemini/skills/ directory. This generic alias provides an intuitive path for managing agent-specific expertise that remains compatible across different AI agent tools.

Managing Skills

In an Interactive Session

Use the /skills slash command to view and manage available expertise:

• /skills list (default): Shows all discovered skills and their status.
• /skills link <path>: Links agent skills from a local directory via symlink.
• /skills disable <name>: Prevents a specific skill from being used.
• /skills enable <name>: Re-enables a disabled skill.
• /skills reload: Refreshes the list of discovered skills from all tiers.

[!NOTE] /skills disable and /skills enable default to the user scope. Use --scope workspace to manage workspace-specific settings.

From the Terminal

The gemini skills command provides management utilities:

# List all discovered skills
gemini skills list

# Link agent skills from a local directory via symlink
# Discovers skills (SKILL.md or */SKILL.md) and creates symlinks in ~/.gemini/skills
# (or ~/.agents/skills)
gemini skills link /path/to/my-skills-repo

# Link to the workspace scope (.gemini/skills or .agents/skills)
gemini skills link /path/to/my-skills-repo --scope workspace

# Install a skill from a Git repository, local directory, or zipped skill file (.skill)
# Uses the user scope by default (~/.gemini/skills or ~/.agents/skills)
gemini skills install https://github.com/user/repo.git
gemini skills install /path/to/local/skill
gemini skills install /path/to/local/my-expertise.skill

# Install a specific skill from a monorepo or subdirectory using --path
gemini skills install https://github.com/my-org/my-skills.git --path skills/frontend-design

# Install to the workspace scope (.gemini/skills or .agents/skills)
gemini skills install /path/to/skill --scope workspace

# Uninstall a skill by name
gemini skills uninstall my-expertise --scope workspace

# Enable a skill (globally)
gemini skills enable my-expertise

# Disable a skill. Can use --scope to specify workspace or user (defaults to workspace)
gemini skills disable my-expertise --scope workspace

How it Works

1. Discovery: At the start of a session, Gemini CLI scans the discovery tiers and injects the name and description of all enabled skills into the system prompt.
2. Activation: When Gemini identifies a task matching a skill's description, it calls the activate_skill tool.
3. Consent: You will see a confirmation prompt in the UI detailing the skill's name, purpose, and the directory path it will gain access to.
4. Injection: Upon your approval:
   • The SKILL.md body and folder structure is added to the conversation history.
   • The skill's directory is added to the agent's allowed file paths, granting it permission to read any bundled assets.
5. Execution: The model proceeds with the specialized expertise active. It is instructed to prioritize the skill's procedural guidance within reason.

Skill activation

Once a skill is activated (typically by Gemini identifying a task that matches the skill's description and your approval), its specialized instructions and resources are loaded into the agent's context. A skill remains active and its guidance is prioritized for the duration of the session.

Creating your own skills

To create your own skills, see the Create Agent Skills guide.