How the Google Skills Repository Architecture Works: Modular Skills and Agent Plugins

The Google Skills repository architecture separates human-readable skill documentation from executable agent harness metadata, enabling a single source of truth for both instructional content and runtime plugins.

The Google Skills repository is organized as a modular collection of skill definitions and agent-harness plugins. This architecture allows developers to install specific capabilities into AI agents like Claude or Codex while maintaining clear boundaries between instructional content and runtime configuration.

Top-Level Directory Structure

The repository root contains two primary directories that enforce a strict separation of concerns.

The skills/ directory houses every skill in its own folder, grouped by product or functional area such as cloud/, ads/, and analytics/. Each skill folder operates as a standalone unit containing instructional content and supporting assets.

The plugins/ directory bundles MCP (Model‑Controlled‑Plugins) and harness-specific metadata required for different agent platforms including Claude, Codex, and the Antigravity CLI. This separation ensures that skill content remains portable while plugin implementations stay platform-specific.

Skill Definitions and SKILL.md Files

Every skill in the repository is defined by a SKILL.md file located within its respective folder under skills/.

These markdown files follow a standard front‑matter schema containing name, metadata, and description fields. The body contains instructional content, clarifying questions, and step‑by‑step guidance for completing specific tasks. For example, the authentication skill at skills/cloud/google-cloud-recipe-auth/SKILL.md demonstrates this structure with practical cloud authentication scenarios.

Supporting reference documents—such as code snippets, tables, and external links—are stored under a references/ sub‑directory inside each skill folder. These assets are imported by the skill markdown to keep the main SKILL.md content succinct and focused on instruction rather than reference data.

The Plugin Layer and MCP Integration

The plugins/ directory contains the runtime components that allow agent harnesses to execute skills.

Each plugin package includes a plugin.json manifest file that describes the plugin name, entry point, and required MCP servers. This manifest serves as the contract between the skill content and the agent runtime, specifying exactly how the AI should invoke the skill's capabilities.

Additionally, mcp.json files within plugin directories configure the MCP servers used by the skill runtime. These configurations tell the agent how to interface with external tools and APIs when executing a skill's workflow.

Machine-Readable Indexing with index.json

At the repository root, index.json enumerates all skills and plugins in a machine‑readable format. This catalog file enables the skills.sh installer and other automation tools to discover available components without parsing the entire directory tree.

The index acts as the source of truth for the installation workflow, mapping skill names to their folder locations and associating them with their corresponding plugin manifests.

Installation and Runtime Workflow

Users interact with the repository through a selective installation process that minimizes unnecessary file transfers.

To install the repository and browse available skills:

# Install the whole repository with interactive selection

npx skills add google/skills

The installer reads index.json to present a list of selectable skills, then clones only the chosen skill folders rather than the entire repository.

To integrate a specific skill with Claude, users add the marketplace and install the relevant plugin:

# Add the Google Skills marketplace to Claude

claude plugin marketplace add google/skills

# Install the cloud-agent-platform plugin

claude plugin install agent-platform@google-plugins

Once installed, skills can be invoked directly from an agent harness using the skill name:

# Invoke the authentication skill with a specific question

agent run google-cloud-recipe-auth \
    --question "How do I authenticate a GKE workload using Workload Identity?"

Summary

• The repository separates content (human-readable skill markdown in skills/**/SKILL.md) from runtime metadata (plugin manifests in plugins/**/plugin.json).
• Each skill follows a standardized structure with front‑matter schema, clarifying questions, and a references/ subdirectory for supporting assets.
• The index.json file provides a machine-readable catalog that powers the selective installation workflow via npx skills add.
• MCP configurations in mcp.json files define how agent harnesses interface with external tools when executing skills.
• Users install specific skills rather than the entire repository, then invoke them through platform-specific plugin commands.

Frequently Asked Questions

What is the difference between skills and plugins in the Google Skills repository?

Skills are instructional packages stored in the skills/ directory, containing SKILL.md files with educational content and clarifying questions. Plugins are runtime components in the plugins/ directory that contain plugin.json manifests and MCP configurations, enabling agent harnesses like Claude or Codex to execute the logic described in the skills.

How does the installation process work for specific skills?

The installer uses the root index.json file to present available skills without downloading the entire repository. When you run npx skills add google/skills, the tool reads the machine-readable catalog and clones only the selected skill folders, minimizing disk usage and install time while ensuring you receive the correct references/ assets and associated plugin metadata.

What is the purpose of the index.json file?

index.json serves as the machine-readable source of truth that maps skill names to their directory locations and associates them with plugin manifests. This file enables automated discovery by the skills.sh installer and other tooling, allowing selective installation and version management without requiring deep parsing of the repository structure.

How are reference materials organized within a skill?

Each skill folder contains a references/ sub-directory that stores supplementary markdown files, code snippets, and external links. These assets are imported or referenced by the main SKILL.md file to keep the primary instructional content concise, ensuring that detailed reference data remains available without cluttering the step-by-step guidance.

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