Mastering Gemini CLI Agent Skills: A Guide to Using and Building Custom Extensions

A comprehensive guide on using and creating Agent Skills to extend the capabilities of the Gemini CLI.

Posted on: 2026-03-11 by AI Assistant

The Gemini CLI is a powerful interactive command-line AI agent that excels at software engineering tasks. While it comes with a robust set of default capabilities, one of its most powerful features is its extensibility through Agent Skills. In this post, we’ll explore how to use existing Agent Skills and how to build your own to tailor the Gemini CLI to your specific workflows.

What are Agent Skills?

Agent Skills are modular extensions that provide the Gemini CLI with specialized instructions, workflows, and access to specific resources. By activating a skill, you essentially load a tailored set of expert procedural guidance into the agent’s context. This allows the agent to perform complex, domain-specific tasks with higher accuracy and efficiency than it could with its general-purpose knowledge alone.

Using Existing Agent Skills

Using an Agent Skill in the Gemini CLI is straightforward. When you give the CLI a task that aligns with an available skill, it can autonomously activate that skill. You can also explicitly instruct it to use a particular skill.

For example, if you want to create a new blog post in an Astro project, you can simply ask:

> Create a new blog post about the future of web development

If a skill like create-blog-post is available, the Gemini CLI will recognize the intent, activate the skill using its internal activate_skill tool, and follow the specialized instructions provided by that skill (e.g., downloading a cover image, formatting the frontmatter, and saving the file to the correct directory).

You can also ask the CLI about what skills are available using queries like “how do I do X” or “find a skill for X”. The CLI uses its find-skills capability to help you discover and install new skills.

Building Your Own Agent Skills

Building your own Agent Skills allows you to codify your team’s best practices, automate repetitive project-specific workflows, or integrate the CLI with proprietary tools.

A skill is defined by a markdown file, typically named SKILL.md. This file contains the instructions, rules, and context the agent needs.

Step 1: Create the SKILL.md File

Create a directory for your skill (e.g., my-custom-skill) and add a SKILL.md file inside it.

# My Custom Skill

This skill automates the process of [your specific task].

## Workflow

1.  **Analyze**: Look at the provided [input/context].
2.  **Process**: Perform the following steps:
    *   Step A...
    *   Step B...
3.  **Output**: Generate a file named `output.txt` with the results.

## Rules

*   Always format the output as JSON.
*   Do not modify any existing configuration files.

Step 2: Define the Instructions Clearly

The key to a good skill is clear, unambiguous instructions. The Gemini CLI will read your SKILL.md file and treat the content within it as expert procedural guidance.

• Be Specific: Use imperative language (“Do this,” “Create that”).
• Provide Examples: Show the agent exactly what the input and expected output look like.
• Define Constraints: Tell the agent what it should not do (e.g., “Never commit changes,” “Only use vanilla CSS”).
• Reference Local Files: You can point the agent to other files in the workspace (e.g., a style guide or an API specification) to provide additional context.

Step 3: Integrating the Skill

To make your skill available to the Gemini CLI, you typically need to place it in a location where the CLI knows to look for it, such as a .gemini/skills/ directory within your project workspace, or globally in ~/.agents/skills/.

Once the skill is in place, the Gemini CLI will be aware of it and can activate it when a user request matches the skill’s description. The description is usually provided to the CLI’s configuration when registering the skill.

Pro-Tip: The Skill Creator Skill

The Gemini CLI itself has a built-in skill called skill-creator. You can ask the CLI to help you create a new skill!

> Help me create a new skill that automates updating our changelog based on recent git commits.

The CLI will activate the skill-creator and guide you through the process of writing effective instructions and setting up the necessary files.

Conclusion

Agent Skills transform the Gemini CLI from a generic assistant into a highly specialized expert tailored to your exact needs. By leveraging existing skills and building your own, you can significantly enhance your productivity, ensure consistency across your projects, and automate complex workflows with ease. Start exploring the possibilities today!