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

> Understand Google Agent Skills reusable markdown modules for AI agents. Learn how they enable AI to execute Google Cloud tasks with structured guidance.

- Repository: [Google/skills](https://github.com/google/skills)
- Tags: deep-dive
- Published: 2026-08-15

---

**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`](https://github.com/google/skills/blob/main/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`](https://github.com/google/skills/blob/main/skills/cloud/gke-basics/SKILL.md), for example, the metadata specifies:

```yaml
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`](https://github.com/google/skills/blob/main/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:

```bash
npx skills add google/skills

```

This command, referenced in [`README.md`](https://github.com/google/skills/blob/main/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:

```bash
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:

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

```

The runtime parses [`skills/cloud/gke-basics/SKILL.md`](https://github.com/google/skills/blob/main/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:

```python
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`](https://github.com/google/skills/blob/main/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`](https://github.com/google/skills/blob/main/SKILL.md) definitions but surfacing them through their respective interaction models.

## Repository Structure and Key Files

| File Path | Purpose |
|-----------|---------|
| [`README.md`](https://github.com/google/skills/blob/main/README.md) | Repository overview, installation instructions, catalog listing |
| [`CONTRIBUTING.md`](https://github.com/google/skills/blob/main/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`](https://github.com/google/skills/blob/main/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`](https://github.com/google/skills/blob/main/CONTRIBUTING.md) at the repository root. Create a new directory under `skills/<category>/<your-skill>/`, add a [`SKILL.md`](https://github.com/google/skills/blob/main/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`](https://github.com/google/skills/blob/main/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`](https://github.com/google/skills/blob/main/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`](https://github.com/google/skills/blob/main/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.