# Google Skills Project Structure: How the Repository Organizes Product‑Specific Guides

> Discover the google skills project structure. Learn how this repository organizes product specific guides in a clear, hierarchical format within the skills/ directory.

- Repository: [Google/skills](https://github.com/google/skills)
- Tags: internals
- Published: 2026-08-14

---

**The google/skills repository is a content‑driven codebase that organizes self‑contained Markdown "skills" under a hierarchical `skills/` directory, grouped by product family (cloud, analytics, ads), with each skill defined by a standardized [`SKILL.md`](https://github.com/google/skills/blob/main/SKILL.md) file.**

The **google/skills** project provides ready‑to‑use instructional modules for Google products. Unlike traditional code repositories, it contains no compiled executables—only structured documentation that AI agents and developers can consume programmatically. This guide examines the repository layout, file conventions, and consumption patterns as implemented in `google/skills`.

## Directory Hierarchy: The `/skills/` Root

All content lives beneath the `skills/` directory at the repository root. The top‑level structure separates skills by **product family**, creating intuitive navigation for both human readers and automated tools.

```

google/skills/
├── README.md                     # Master index of all skills

├── LICENSE, CONTRIBUTING.md     # Project metadata

├── .gitmodules, .gitignore      # Version control config

└── skills/
   ├── cloud/                     # GCP‑related skills (≈40+ subfolders)

   ├── analytics/                 # Google Analytics skills

   ├── ads/                       # Advertising platform skills

   └── [future categories…]

```

### Product Family Organization

Each immediate subfolder of `skills/` represents a **product family**. The three established families demonstrate the breadth of coverage:

- **`skills/cloud/`** – Google Cloud Platform services including GKE, BigQuery, BigFrames, Firebase, and workload scaling
- **`skills/analytics/`** – Google Analytics Data API, Admin API, and measurement tools
- **`skills/ads/`** – Google Ads API, IMA SDK, and advertising integrations

## Skill Folder Structure: Self‑Contained Modules

Within each product family, **individual skills** reside in dedicated subfolders. A skill is the atomic unit of the repository—a complete, portable guide for a specific task or product area.

```

skills/cloud/gke-basics/
├── SKILL.md                     # Required: skill definition + guide

└── references/                  # Optional: language‑specific snippets

    └── cli-reference.md         # Shell command reference

```

### Required Files

Every skill folder **must** contain:

| File | Purpose |
|------|---------|
| [`SKILL.md`](https://github.com/google/skills/blob/main/SKILL.md) | The canonical skill definition with YAML front‑matter metadata and Markdown instructional content |

### Optional Supporting Files

Skills may include additional resources:

| Path Pattern | Role |
|------------|------|
| `references/*.md` | Language‑specific setup guides, code samples, or deeper technical explanations |
| `assets/*` | YAML manifests, JSON configurations, or sample data for hands‑on exercises |

## The SKILL.md Format: Machine‑Readable Metadata

The [`SKILL.md`](https://github.com/google/skills/blob/main/SKILL.md) file follows a consistent structure that enables both human readability and programmatic consumption. Each file begins with **YAML front‑matter** enclosed in `---` delimiters, followed by freeform Markdown content.

```yaml
---
name: gke-basics
metadata:
  category: Containers
description: |
  Manages core GKE cluster provisioning, credentials, Autopilot vs Standard selection,
  and workload deployment.
---

# GKE Basics & Critical Gotchas

## Prerequisites

...

```

This pattern appears across all skills. For example, the Google Analytics Data API skill in [`skills/analytics/google-analytics-data-api-basics/SKILL.md`](https://github.com/google/skills/blob/main/skills/analytics/google-analytics-data-api-basics/SKILL.md) similarly opens with structured metadata before proceeding to implementation guidance.

### Front‑Matter Fields

| Field | Description |
|-------|-------------|
| `name` | Machine‑friendly identifier for the skill |
| `metadata.category` | Logical grouping for display purposes |
| `description` | Concise summary of scope and purpose |

## Cross‑References and Language Guides

Complex skills often include **reference documentation** in dedicated subfolders. These files extend the core [`SKILL.md`](https://github.com/google/skills/blob/main/SKILL.md) with implementation‑specific details.

### Example: References Subfolder

```

skills/analytics/google-analytics-data-api-basics/
├── SKILL.md
└── references/
    └── python.md                # Python client library setup

```

This structure allows agents to surface the appropriate language guide based on the developer's environment, without cluttering the main skill definition.

## Asset Files: Executable Examples

Some skills provide **ready‑to‑run configurations** in `assets/` folders. These are particularly common for infrastructure‑as‑code scenarios.

```

skills/cloud/gke-workload-scaling/
├── SKILL.md
└── assets/
    └── vpa-example.yaml         # Vertical Pod Autoscaler manifest

```

These assets enable copy‑paste workflows for Kubernetes deployments, BigQuery schemas, or Firebase configurations.

## Repository Navigation: The Master Index

The root [`README.md`](https://github.com/google/skills/blob/main/README.md) serves as the **canonical catalogue** of all available skills. It enumerates every product family and skill folder with direct links, making the repository browsable without external tooling.

According to the source, this index structure appears at lines 20–46 of [`README.md`](https://github.com/google/skills/blob/main/README.md), providing:

- Alphabetical or categorical listing of skills
- Direct hyperlinks to each [`SKILL.md`](https://github.com/google/skills/blob/main/SKILL.md) file
- Descriptive summaries of repository purpose and contribution guidelines

## Skill Consumption: How Agents Use the Repository

Skills are designed for **programmatic consumption** by AI agents and developer tools. The standard invocation pattern uses the `npx skills` CLI:

```bash
npx skills add google/skills

```

This command:

1. Reads the repository's skill catalogue
2. Presents an interactive selection interface
3. Retrieves the specific [`SKILL.md`](https://github.com/google/skills/blob/main/SKILL.md) and any referenced assets
4. Integrates the skill's guidance into the agent's context window

The content‑only architecture ensures minimal overhead—no build steps, no dependency resolution, and no runtime compatibility concerns.

## Key Source Files for Reference

| Path | Significance |
|------|------------|
| [`README.md`](https://github.com/google/skills/blob/main/README.md) | Master skill index with navigation links |
| [`skills/cloud/gke-basics/SKILL.md`](https://github.com/google/skills/blob/main/skills/cloud/gke-basics/SKILL.md) | Exemplary cloud skill with full metadata |
| [`skills/analytics/google-analytics-data-api-basics/SKILL.md`](https://github.com/google/skills/blob/main/skills/analytics/google-analytics-data-api-basics/SKILL.md) | Analytics skill demonstrating reference patterns |
| `skills/cloud/gke-workload-scaling/assets/` | Sample manifests for hands‑on learning |

## Summary

- **The google/skills repository** organizes instructional content hierarchically under `skills/<product-family>/<skill-name>/`
- **Each skill** is defined by a [`SKILL.md`](https://github.com/google/skills/blob/main/SKILL.md) file combining YAML metadata with Markdown documentation
- **Optional `references/` and `assets/` folders** provide language‑specific guidance and executable examples
- **The root [`README.md`](https://github.com/google/skills/blob/main/README.md)** functions as a navigable catalogue of all available skills
- **No compiled code exists** in the repository—skills are pure content consumed by AI agents via tools like `npx skills add`

## Frequently Asked Questions

### What file defines a skill in the google/skills repository?

The [`SKILL.md`](https://github.com/google/skills/blob/main/SKILL.md) file defines each skill. It contains YAML front‑matter with metadata fields (`name`, `category`, `description`) followed by instructional Markdown content. This file is required in every skill folder.

### How are skills organized by product area?

Skills group under top‑level directories within `skills/`—such as `cloud/`, `analytics/`, and `ads/`—each representing a Google product family. Within these, individual skill folders use descriptive names like `gke-basics` or `google-ads-api-quickstart`.

### Can skills include code samples?

Yes. Skills may include a `references/` subfolder with language‑specific Markdown files (e.g., [`python.md`](https://github.com/google/skills/blob/main/python.md), [`cli-reference.md`](https://github.com/google/skills/blob/main/cli-reference.md)) and an `assets/` folder with executable YAML or JSON configurations for hands‑on exercises.

### How do developers or agents consume skills from this repository?

Agents consume skills through the `npx skills add google/skills` command, which reads the repository structure, presents skill selection, and loads the relevant [`SKILL.md`](https://github.com/google/skills/blob/main/SKILL.md) content into the agent's context. No local installation or build process is required.