# Google Skills Repository Structure: Complete Guide to File Organization and Skill Architecture

> Explore the google skills repository structure. Understand its modular Markdown skills, domain organization, SKILL.md definitions, and index.json for discoverability.

- Repository: [Google/skills](https://github.com/google/skills)
- Tags: architecture
- Published: 2026-09-05

---

**The google/skills repository is a modular collection of Markdown-based skills organized by domain, with each skill containing a [`SKILL.md`](https://github.com/google/skills/blob/main/SKILL.md) definition file and optional `references/` folder, all discoverable through an [`index.json`](https://github.com/google/skills/blob/main/index.json) consumed by the Skills CLI.**

The **google/skills** repository on GitHub provides a structured, plug-and-play knowledge base for Google Cloud, Ads, Analytics, and Identity workflows. Understanding the google skills repository structure helps developers locate relevant guides, integrate skills programmatically, and contribute new content effectively.

## Root-Level Files and Configuration

The repository root contains standard project files plus a machine-readable index that powers skill discovery:

| File | Purpose |
|------|---------|
| [`README.md`](https://github.com/google/skills/blob/main/README.md) | Human-readable catalog listing every skill with direct links to directories |
| [`index.json`](https://github.com/google/skills/blob/main/index.json) | JSON index parsed by the Skills CLI to resolve skill IDs and metadata |
| `LICENSE` | Apache 2.0 license |
| [`CONTRIBUTING.md`](https://github.com/google/skills/blob/main/CONTRIBUTING.md) | Contribution guidelines |
| `.gitignore`, `.gitmodules` | Git configuration |

The [`README.md`](https://github.com/google/skills/blob/main/README.md) serves as the primary entry point, with entries like:

- **Getting started with Google Cloud** → `skills/cloud/google-cloud-recipe-auth`
- **Agent Platform Alert Configuration** → `skills/cloud/agent-platform-alert-configuration`
- **Google Ads API Quickstart** → `skills/ads/google-ads-api-quickstart`

These links are auto-generated from the catalog structure.

## The `skills/` Directory: Core Content Organization

All skill content lives under `/skills/`, divided into **domain-specific subdirectories**:

```

skills/
├── cloud/          # GKE, BigQuery, IAM, Workload Manager, etc.

├── analytics/      # Google Analytics Data & Admin API guides

├── ads/            # Google Ads and Mobile Ads SDK

├── developers/     # Developer knowledge and skill-search utilities

└── identity/       # Identity-focused skills (DPoP adoption, etc.)

```

### Individual Skill Structure

Each skill occupies its own subfolder and contains:

- **[`SKILL.md`](https://github.com/google/skills/blob/main/SKILL.md)** – Primary definition file with metadata, description, and prompts
- **`references/`** – Optional folder for language-specific or configuration reference files (Python, Java, CLI snippets)

For example, the **Workload Manager Basics** skill at `skills/cloud/workload-manager-basics/` contains:

- [`SKILL.md`](https://github.com/google/skills/blob/main/SKILL.md) – Core skill definition with prompts and metadata
- [`references/core-concepts.md`](https://github.com/google/skills/blob/main/references/core-concepts.md) – Supporting technical reference

Similarly, `skills/cloud/gke-basics/` and `skills/ads/google-ads-api-quickstart/` follow this identical pattern.

## The `plugins/` Directory: Integration Layer

The `plugins/` directory enables the repository to function as a **plug-and-play source for agent harnesses**. It contains plugin manifests such as:

- [`plugin.json`](https://github.com/google/skills/blob/main/plugin.json) – Generic plugin configuration
- [`gemini-extension.json`](https://github.com/google/skills/blob/main/gemini-extension.json) – Gemini-specific extension metadata
- [`marketplace.json`](https://github.com/google/skills/blob/main/marketplace.json) – Marketplace integration for agents like Claude, Codex, and Antigravity CLI

These manifests allow the google skills repository structure to be consumed programmatically by various AI agents and development tools.

## Using the CLI to Navigate the Structure

The **Skills CLI** leverages [`index.json`](https://github.com/google/skills/blob/main/index.json) and the README catalog to provide skill discovery and installation:

```bash

# List all available skills (parses README catalog)

npx skills list

# Install a specific skill by its path

npx skills add google/skills/cloud/gke-basics

```

To inspect a skill's definition directly from the repository:

```bash
curl -L https://github.com/google/skills/raw/main/skills/cloud/gke-basics/SKILL.md

```

## Key File Reference

| Path | Role in Repository Structure |
|------|------------------------------|
| [`skills/cloud/workload-manager-basics/SKILL.md`](https://github.com/google/skills/blob/main/skills/cloud/workload-manager-basics/SKILL.md) | Example skill definition with metadata and prompts |
| [`skills/cloud/workload-manager-basics/references/core-concepts.md`](https://github.com/google/skills/blob/main/skills/cloud/workload-manager-basics/references/core-concepts.md) | Language-agnostic reference supplement |
| [`skills/identity/dpop-adoption/SKILL.md`](https://github.com/google/skills/blob/main/skills/identity/dpop-adoption/SKILL.md) | Identity domain skill example |
| [`plugins/cloud/google-cloud-developer/plugin.json`](https://github.com/google/skills/blob/main/plugins/cloud/google-cloud-developer/plugin.json) | Plugin manifest for agent integration |

## Summary

- The **google skills repository structure** organizes content as **self-contained Markdown skills** under domain folders (`cloud/`, `analytics/`, `ads/`, `developers/`, `identity/`)
- Each skill requires a **[`SKILL.md`](https://github.com/google/skills/blob/main/SKILL.md)** file and optionally includes a **`references/`** subdirectory
- **Root-level files** ([`README.md`](https://github.com/google/skills/blob/main/README.md), [`index.json`](https://github.com/google/skills/blob/main/index.json)) enable both human browsing and CLI-driven discovery
- The **`plugins/`** directory provides integration manifests for agent harnesses
- All paths follow predictable patterns that allow direct HTTP access or CLI installation

## Frequently Asked Questions

### How do I find the correct path for a specific skill?

Skill paths follow the pattern `skills/{domain}/{skill-name}/`. The [`README.md`](https://github.com/google/skills/blob/main/README.md) at the repository root contains a complete catalog with direct links to every skill directory. The Skills CLI also parses this catalog when you run `npx skills list`.

### What is the difference between [`SKILL.md`](https://github.com/google/skills/blob/main/SKILL.md) and files in the `references/` folder?

[`SKILL.md`](https://github.com/google/skills/blob/main/SKILL.md) contains the **skill definition itself**—metadata, description, prompts, and configuration. The `references/` folder holds **supplementary technical content** such as code snippets, core concepts, or implementation guides that support the main skill without cluttering the definition file.

### Can I install individual skills without cloning the entire repository?

Yes. The Skills CLI supports **targeted installation** using the skill path: `npx skills add google/skills/cloud/gke-basics`. The CLI reads [`index.json`](https://github.com/google/skills/blob/main/index.json) to resolve dependencies and fetch only the required files.

### What domains are currently supported in the skills directory?

As implemented in `google/skills`, the repository contains five primary domains: `cloud/` (Google Cloud Platform services), `analytics/` (Google Analytics APIs), `ads/` (Google Ads and mobile advertising), `developers/` (general developer tools and skill search), and `identity/` (authentication and security patterns like DPoP).