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

The google/skills repository is a modular collection of Markdown-based skills organized by domain, with each skill containing a SKILL.md definition file and optional references/ folder, all discoverable through an 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	Human-readable catalog listing every skill with direct links to directories
index.json	JSON index parsed by the Skills CLI to resolve skill IDs and metadata
LICENSE	Apache 2.0 license
CONTRIBUTING.md	Contribution guidelines
.gitignore, .gitmodules	Git configuration

The 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 – 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 – Core skill definition with prompts and metadata
• 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 – Generic plugin configuration
• gemini-extension.json – Gemini-specific extension metadata
• 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 and the README catalog to provide skill discovery and installation:

# 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:

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	Example skill definition with metadata and prompts
skills/cloud/workload-manager-basics/references/core-concepts.md	Language-agnostic reference supplement
skills/identity/dpop-adoption/SKILL.md	Identity domain skill example
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 file and optionally includes a references/ subdirectory
• Root-level files (README.md, 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 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 and files in the references/ folder?

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 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).

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