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

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 file at the root of each plugin folder, which must conform to the agent-plugins.org schema.

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 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, 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")

{
  "$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.

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:

# 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 and 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 file provides runtime parameters such as port configurations and caching strategies, while 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 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) 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
2. Validation: Parse and validate the JSON against the agent-plugins.org schema
3. Registration: Load MCP server configurations from mcp.json
4. Skill Extraction: Parse 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.

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

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