# How the Google Skills Repository Architecture Works: Modular Skills and Agent Plugins > Explore the Google Skills repository architecture. Learn how modular skills and agent plugins create a single source of truth for documentation and runtime execution. - Repository: [Google/skills](https://github.com/google/skills) - Tags: architecture - Published: 2026-09-02 --- **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`](https://github.com/google/skills/blob/main/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`](https://github.com/google/skills/blob/main/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`](https://github.com/google/skills/blob/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`](https://github.com/google/skills/blob/main/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`](https://github.com/google/skills/blob/main/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`](https://github.com/google/skills/blob/main/index.json) enumerates all skills and plugins in a machine‑readable format. This catalog file enables the [`skills.sh`](https://github.com/google/skills/blob/main/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: ```bash # Install the whole repository with interactive selection npx skills add google/skills ``` The installer reads [`index.json`](https://github.com/google/skills/blob/main/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: ```bash # 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: ```bash # 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`](https://github.com/google/skills/blob/main/index.json) file provides a machine-readable catalog that powers the selective installation workflow via `npx skills add`. - MCP configurations in [`mcp.json`](https://github.com/google/skills/blob/main/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`](https://github.com/google/skills/blob/main/SKILL.md) files with educational content and clarifying questions. **Plugins** are runtime components in the `plugins/` directory that contain [`plugin.json`](https://github.com/google/skills/blob/main/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`](https://github.com/google/skills/blob/main/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`](https://github.com/google/skills/blob/main/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`](https://github.com/google/skills/blob/main/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`](https://github.com/google/skills/blob/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.