# Understanding the Google Skills Plugin Architecture: A Developer's Guide

> Explore the Google Skills plugin architecture using JSON metadata and Markdown for easy extensibility. Learn how to add new capabilities without core code modifications.

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

---

**Google Skills implements a modular plugin system that uses JSON metadata declarations and Markdown-based skill definitions to extend the framework with new capabilities without modifying core code.**

The `google/skills` repository provides a flexible framework for building AI-powered developer tools. Its **Google Skills plugin architecture** separates metadata, skill logic, and grounding services into distinct, discoverable components, enabling developers to add domain-specific knowledge through self-contained extensions.

## Plugin Discovery and Registration

Plugins are organized as folders within the `plugins/` directory hierarchy. The framework identifies valid plugins by detecting a **[`plugin.json`](https://github.com/google/skills/blob/main/plugin.json)** file at the root of each plugin folder, which must conform to the [agent-plugins.org schema](https://github.com/google/skills/blob/main/plugins/cloud/google-cloud-developer/plugin.json).

When the Skills runtime initializes, it scans these directories and registers any plugin containing valid metadata. This discovery mechanism allows the `npx skills plugins list` command to enumerate available extensions and the `npx skills add <plugin-name>` command to install them by copying the plugin folder and updating the central registry.

## Metadata Definition in plugin.json

The **[`plugin.json`](https://github.com/google/skills/blob/main/plugin.json)** file serves as the plugin's manifest, declaring essential metadata used for documentation, search, and CLI integration. According to the source code in [`plugins/cloud/google-cloud-developer/plugin.json`](https://github.com/google/skills/blob/main/plugins/cloud/google-cloud-developer/plugin.json), this file specifies:

- **Identity fields**: `name`, `version`, `description`, `author`, and `homepage`
- **Repository links**: Source code location and license information
- **Keywords**: Taxonomy tags for discovery (e.g., "google-cloud", "authentication")

```json
{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
  "name": "google-cloud-developer",
  "version": "1.1.0",
  "description": "Google Cloud guidance for coding agents: first‑project onboarding, authentication …",
  "author": { "name": "Google LLC", "url": "https://cloud.google.com" },
  "homepage": "https://github.com/google/skills/tree/main/plugins/cloud/google-cloud-developer",
  "repository": "https://github.com/google/skills",
  "license": "Apache-2.0",
  "keywords": ["google-cloud", "gcloud", "authentication", "onboarding"]
}

```

This structured metadata enables automated tooling to validate, categorize, and surface plugins without parsing implementation code.

## Skill Bundles and Markdown Definitions

Inside each plugin, functional capabilities are defined as **skills**—individual units of functionality stored as `.md` files with a `SKILL` header. For example, the *retrieving-developer-knowledge* skill resides at [`plugins/cloud/google-cloud-developer/skills/retrieving-developer-knowledge/SKILL.md`](https://github.com/google/skills/blob/main/plugins/cloud/google-cloud-developer/skills/retrieving-developer-knowledge/SKILL.md).

These **skill bundles** specify:
- User-visible commands and their parameters
- MCP (Multi-Channel Protocol) tool definitions
- Fallback behavior for handling unsupported queries

The framework parses these Markdown files at startup, exposing their commands as callable tools through the Skills CLI:

```bash

# Run a specific skill from the Google Cloud Developer plugin

skills run retrieving-developer-knowledge "How do I enable the Cloud Scheduler API?"

```

## MCP Integration for Grounded Documentation

Plugins leverage the **Multi-Channel Protocol (MCP)** to supply runtime documentation that remains synchronized with live services. The [`mcp.json`](https://github.com/google/skills/blob/main/mcp.json) and [`mcp_config.json`](https://github.com/google/skills/blob/main/mcp_config.json) files configure an MCP server that the Skills runtime queries for up-to-date information.

This architecture enables **dynamic grounding**—when a user asks about Google Cloud services, the system queries the MCP server rather than relying on static training data. The [`mcp_config.json`](https://github.com/google/skills/blob/main/mcp_config.json) file provides runtime parameters such as port configurations and caching strategies, while [`mcp.json`](https://github.com/google/skills/blob/main/mcp.json) defines the server endpoints and capabilities.

## Extension Points and Safety Controls

Beyond core skills, the Google Skills plugin architecture supports specialized extension mechanisms:

**Gemini Extensions**: The [`gemini-extension.json`](https://github.com/google/skills/blob/main/gemini-extension.json) file registers custom Gemini AI capabilities, allowing plugins to expose specialized model behaviors or fine-tuned interactions.

**Safety Rules**: The `rules/` directory contains Markdown files (e.g., [`rules/google-cloud-discovery.md`](https://github.com/google/skills/blob/main/rules/google-cloud-discovery.md)) that define validation logic for safe command execution. These rules govern critical operations such as credential handling and organization-level onboarding procedures, ensuring that agent actions comply with security policies before execution.

## Plugin Loading Flow

The Skills runtime initializes plugins through a sequential validation and registration process:

1. **Discovery**: Scan `plugins/` directories for folders containing [`plugin.json`](https://github.com/google/skills/blob/main/plugin.json)
2. **Validation**: Parse and validate the JSON against the agent-plugins.org schema
3. **Registration**: Load MCP server configurations from [`mcp.json`](https://github.com/google/skills/blob/main/mcp.json)
4. **Skill Extraction**: Parse [`SKILL.md`](https://github.com/google/skills/blob/main/SKILL.md) files and expose their commands as MCP tools
5. **CLI Integration**: Update the plugin registry to enable `npx skills` commands

This loading flow ensures that plugins are sandboxed, validated, and immediately available to the CLI without requiring core codebase modifications.

```bash

# List all installed plugins

npx skills plugins list

# Add the Google Cloud Developer plugin to your environment

npx skills add google-cloud-developer

# Inspect plugin metadata directly

cat $(npx skills plugins path google-cloud-developer)/plugin.json

```

## Summary

- **Discovery-driven**: The framework automatically detects plugins by scanning for [`plugin.json`](https://github.com/google/skills/blob/main/plugin.json) files in the `plugins/` directory hierarchy.
- **Metadata-first**: Each plugin declares its identity, dependencies, and keywords through a standardized JSON schema.
- **Markdown-based skills**: Functional capabilities are defined in `.md` files with `SKILL` headers, specifying commands and MCP tool contracts.
- **Live grounding**: MCP server integration provides real-time documentation queries, ensuring responses reflect current service states.
- **Safety enforcement**: Rule-based validation in `rules/*.md` files ensures secure command execution and proper credential handling.
- **Zero-core modifications**: The architecture enables plug-and-play extensions through an isolated loading flow that doesn't alter the Skills framework core.

## Frequently Asked Questions

### How do I create a custom plugin for Google Skills?

Create a new folder under `plugins/` containing a valid [`plugin.json`](https://github.com/google/skills/blob/main/plugin.json) file conforming to the agent-plugins.org schema. Add your skill definitions as `.md` files with `SKILL` headers in a `skills/` subdirectory. Include an [`mcp.json`](https://github.com/google/skills/blob/main/mcp.json) if your plugin requires live documentation grounding, and validate your structure using `npx skills plugins list` to ensure discovery.

### What is the purpose of MCP integration in Google Skills plugins?

MCP (Multi-Channel Protocol) integration allows plugins to configure documentation servers that supply **grounded, up-to-date information** at runtime. Rather than relying on static knowledge, the Skills framework queries the MCP server configured in [`mcp.json`](https://github.com/google/skills/blob/main/mcp.json) to retrieve current service documentation, ensuring accurate answers about rapidly evolving platforms like Google Cloud.

### How does the plugin architecture ensure security during command execution?

The architecture enforces security through **rule-based validation** defined in `rules/*.md` files within each plugin. These rules specify safety constraints for credential handling, organization-level permissions, and command execution boundaries. The Skills runtime evaluates these rules before executing any plugin-provided command, preventing unauthorized operations.

### Can plugins extend Gemini AI capabilities?

Yes. Plugins may include a [`gemini-extension.json`](https://github.com/google/skills/blob/main/gemini-extension.json) file that registers custom Gemini AI extensions. This allows developers to expose specialized model behaviors, custom prompting strategies, or domain-specific AI capabilities that integrate seamlessly with the Skills framework's agent architecture.