Google Agent Skills Explained: Reusable Knowledge Modules for AI-Powered Cloud Workflows

Google Agent Skills are declarative, markdown-based knowledge modules stored in the google/skills repository that enable AI agents to understand, explain, and execute Google Cloud tasks with structured guidance and reference materials.

Each skill is a self-contained SKILL.md file that combines machine-readable metadata with human-readable instructions, allowing tools like Claude Code, Codex, and the skills CLI to surface contextual help for Google Cloud products. The repository serves as an open catalog that anyone can install and extend.

What Makes Up a Google Agent Skill

A Google Agent Skill follows a strict, parseable architecture designed for both human authors and automated agents.

Skill Definition and Metadata

Every skill begins with a YAML front-matter block that declares its identity. In skills/cloud/gke-basics/SKILL.md, for example, the metadata specifies:

name: gke-basics
category: Containers
description: Core concepts and operations for Google Kubernetes Engine

This structure allows agent runtimes to discover, filter, and route queries to the appropriate skill without parsing free-form text. The name field becomes the CLI identifier, while category enables grouped browsing in UI surfaces.

Content Sections and Actionable Guidance

After the metadata, the SKILL.md contains standard markdown sections that agents parse to answer user questions. Typical sections include:

• ## Key Selection Rules — Decision criteria for choosing between product options

• ## Critical Gotchas — Common pitfalls and how to avoid them

• ## Step-by-Step Procedures — Numbered instructions with embedded code snippets

The gke-basics skill specifically includes a references/ directory listing that agents can traverse to fetch deeper documentation based on query context.

Reference Documentation and Execution Support

Each skill ships a references/ subdirectory with implementation-specific guides:

Reference Type	Purpose
CLI usage	gcloud commands with full flag documentation
Terraform IaC	HCL configurations for infrastructure-as-code workflows
Client libraries	Python, Go, Java, and Node.js code samples

These references are explicitly linked in the skill's metadata, enabling agents to retrieve the exact implementation path a user needs—whether they prefer command-line tools, configuration management, or programmatic APIs.

Installing and Using Google Agent Skills

The repository exposes skills through a unified CLI and plugin ecosystem.

Install the Skill Catalog

Add all Google Agent Skills to your local environment with:

npx skills add google/skills

This command, referenced in README.md lines 11-16, fetches the latest skill definitions from the google/skills repository and registers them with your local skills runtime.

List and Discover Skills

After installation, enumerate available capabilities:

skills list

Expected output includes entries like gke-basics: Manages core GKE cluster provisioning and firebase-basics: Firebase setup and best practices, with descriptions drawn directly from each skill's front-matter description field.

Query a Specific Skill

Invoke targeted assistance by skill name:

skills run gke-basics --query "How do I create a private Autopilot cluster?"

The runtime parses skills/cloud/gke-basics/SKILL.md, matches your query against section headers and content, and returns the relevant instructions, code blocks, and reference links.

Programmatic Usage from Client Library References

Skills often include executable examples in their reference documentation. Derived from the client-library references in gke-basics, a Python implementation looks like:

from google.cloud import container_v1

client = container_v1.ClusterManagerClient()
cluster = client.create_cluster(
    request={
        "project_id": "my-project",
        "region": "us-central1",
        "cluster": {
            "name": "my-cluster",
            "location": "us-central1",
            "autopilot": {}
        }
    }
)
print(f"Cluster {cluster.name} created.")

The skill's reference directory contains variations of this pattern for Terraform, gcloud CLI, and other languages—ensuring consistent guidance regardless of your preferred toolchain.

Agent Runtime Integration

Google Agent Skills extend beyond static documentation through plugin bundles.

MCP Server Packaging

The plugins/ directory, documented in README.md lines 58-66, packages skills with Model-Controlled-Process (MCP) servers. These bundles enable agents to:

• Execute actions on behalf of users (create clusters, deploy functions, configure IAM)
• Maintain state across multi-step workflows
• Validate outcomes against declared success criteria

Supported runtimes include Claude Code, Codex, and the Antigravity CLI—each consuming the same underlying SKILL.md definitions but surfacing them through their respective interaction models.

Repository Structure and Key Files

File Path	Purpose
README.md	Repository overview, installation instructions, catalog listing
CONTRIBUTING.md	Guidelines for authoring new skills or updating existing ones
skills/<category>/<skill-name>/SKILL.md	Canonical skill definition with metadata and content
skills/<category>/<skill-name>/references/	Implementation-specific documentation (CLI, Terraform, SDKs)
plugins/<runtime>/	Bundled skill-MCP server packages for specific agent platforms

This structure, implemented in the google/skills repository, ensures that skills remain portable across tools while allowing runtime-specific optimizations for execution and UI presentation.

Summary

• Google Agent Skills are markdown-based knowledge modules with structured YAML front-matter and human-readable content sections
• Each skill resides in a SKILL.md file within google/skills, accompanied by a references/ directory for deep-dive documentation
• The skills CLI enables installation (npx skills add google/skills), discovery (skills list), and invocation (skills run <skill-name>)
• Plugin bundles in the plugins/ directory combine skills with MCP servers for execution-capable agent integrations
• Skills support multiple implementation paths—CLI, Terraform IaC, and client libraries—through structured reference documentation

Frequently Asked Questions

How do I contribute a new Google Agent Skill?

Follow the guidelines in CONTRIBUTING.md at the repository root. Create a new directory under skills/<category>/<your-skill>/, add a SKILL.md with required front-matter fields (name, category, description), and populate the references/ directory with implementation examples. Submit via pull request for review.

What is the difference between a skill and a plugin?

A skill is the declarative knowledge module—the SKILL.md and its references/—describing how to perform a task. A plugin is a runtime-specific bundle that packages one or more skills with an MCP server, enabling an agent to execute actions rather than just provide guidance. Plugins live in plugins/; skills live in skills/.

Can I use Google Agent Skills without the skills CLI?

Yes. The SKILL.md files are standard markdown with YAML front-matter. Any tool that can parse markdown and YAML can consume skill definitions directly. However, the CLI and plugins provide discovery, query routing, and execution capabilities that would otherwise require custom implementation.

Which agent runtimes support Google Agent Skills?

According to README.md lines 58-66, officially supported runtimes include Claude Code, Codex, and Antigravity CLI. The MCP-based plugin architecture allows additional runtimes to integrate by implementing the Model-Controlled-Process protocol and consuming skill definitions from the catalog.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}