Google/Skills Architecture Components: A Complete Technical Guide

Google/Skills is a modular, skill-first framework that enables LLM agents to discover, invoke, and manage cloud-native capabilities through skill definitions, a central registry, and specialized runtime modules.

This repository implements a plug-and-play ecosystem where agents query a skill registry, fetch canonical skill definitions, and execute associated runtime code. Understanding the Google/Skills architecture components is essential for developers building extensible AI agents on Google Cloud.

---

Core Google/Skills Architecture Components

The framework organizes functionality into nine distinct component types, each with specific responsibilities and implementation locations.

Skill Definitions

Every capability in the system starts with a human-written Markdown file named SKILL.md. These files act as the canonical source of truth, documenting purpose, inputs, outputs, and usage examples.

Each skill folder contains its own SKILL.md. For example, skills/cloud/google-cloud-recipe-auth/SKILL.md defines authentication patterns for cloud recipes.

Skill Registry

The central discovery service stores metadata about all available skills. Implemented in skills/cloud/agent-platform-skill-registry/scripts/skill_registry_ops.py, this registry enables runtime agent queries for capability discovery and invocation.

The registry abstracts skill locations, letting agents find capabilities without hardcoding paths.

Agent-Platform Runtime Modules

The execution layer comprises four specialized sub-packages:

• Inference – skills/cloud/agent-platform-inference/scripts/*.py handles model calls. Key file: openmaas_vertexai_sdk.py wraps Vertex AI SDK for agent consumption.
• Model tuning – skills/cloud/agent-platform-tuning/scripts/*.py manages fine-tuning workflows. Key file: tune_open_model.py launches training jobs with status streaming.
• Prompt management – skills/cloud/agent-platform-prompt-management centralizes prompt versioning and templates.
• Alert configuration – skills/cloud/agent-platform-alert-configuration sets up monitoring and notification rules.

Utility and Validation Scripts

Helper Python scripts support skill development and maintenance:

• skills/cloud/cloud-monitoring-chart-generation/scripts/validate_chart.py – validates monitoring chart configurations
• skills/cloud/agent-platform-tuning/scripts/prepare_dataset.py – transforms data for training pipelines

Plugin Infrastructure

Thin wrappers expose the skill set to external agent harnesses through manifest files:

• .claude-plugin/marketplace.json – Claude Code integration
• .agents/plugins/marketplace.json – Codex and Antigravity CLI integration

These hidden directories declaratively register the repository with consuming tools.

Installation Tooling

The skills.sh installer and npx skills add command provide one-click skill bundle deployment. Configuration is documented in the top-level README.md.

Well-Architected Framework Skill Set

Six pillar-specific skill groups encode Google Cloud WAF principles:

• skills/cloud/google-cloud-waf-cost
• skills/cloud/google-cloud-waf-operational-excellence
• skills/cloud/google-cloud-waf-performance
• skills/cloud/google-cloud-waf-reliability
• skills/cloud/google-cloud-waf-security
• skills/cloud/google-cloud-waf-sustainability

Each pillar contains independent SKILL.md files with architecture guidance.

Domain-Specific Skill Families

Specialized skill groups expose cloud-native APIs as agent-callable capabilities:

• skills/cloud/gke-basics – Kubernetes cluster operations
• skills/cloud/bigquery-basics – Data warehouse interactions
• skills/cloud/firebase-basics – Mobile and web platform services
• skills/cloud/spanner-basics – Distributed SQL operations

Documentation and Reference Assets

Markdown reference files in references/*.md directories provide implementation support:

• skills/cloud/google-cloud-solution-rag-enterprise-search-gke-sqldb/references/related-documentation.md
• skills/cloud/spanner-basics/references/core-concepts.md

---

Interacting with the Google/Skills Architecture

Listing Skills via CLI

# Install the skills package (one-time)

npx skills add google/skills

# List every available skill in the repository

skills list

Discovering Skills Programmatically

import requests, json

# The skill-registry endpoint is exposed by the Agent Platform runtime.

REGISTRY_URL = "https://skill-registry.googleapis.com/v1/skills"

def list_skills():
    resp = requests.get(REGISTRY_URL)
    resp.raise_for_status()
    return json.loads(resp.text)["skills"]

for skill in list_skills():
    print(f"{skill['name']}: {skill['description']}")

Executing a Skill

import json
import requests

SKILL_ENDPOINT = "https://agent-platform.googleapis.com/v1/skills/gke-cluster-creation:execute"

payload = {
    "inputs": {
        "project_id": "my-gcp-project",
        "cluster_name": "demo-cluster",
        "zone": "us-central1-a"
    }
}
response = requests.post(SKILL_ENDPOINT, json=payload)
print(json.dumps(response.json(), indent=2))

---

Component Interaction Flow

The architecture follows a three-stage pipeline:

1. Catalog – SKILL.md files define capabilities in version-controlled Markdown
2. Registry – skill_registry_ops.py indexes and serves metadata
3. Runtime – Agent-platform modules execute inference, tuning, or alerting logic

Plugin manifests bridge this pipeline to external agent harnesses without modifying core code.

---

Summary

• Skill definitions in SKILL.md files provide human- and machine-readable capability specifications
• Skill registry at skill_registry_ops.py enables dynamic discovery and runtime binding
• Runtime modules separate concerns across inference, tuning, prompts, and alerts
• Plugin infrastructure via marketplace.json files integrates with Claude Code, Codex, and Antigravity
• Modular design allows extension by adding new skill folders without platform changes

---

Frequently Asked Questions

What file defines a skill in the Google/Skills repository?

Every skill requires a SKILL.md file in its directory. This Markdown file contains the skill's purpose, input/output schemas, and usage examples, serving as the single source of truth for both human developers and automated systems.

How does the skill registry work?

The registry in skills/cloud/agent-platform-skill-registry/scripts/skill_registry_ops.py maintains a queryable index of all SKILL.md metadata. Agents call registry endpoints at runtime to discover available capabilities without embedding static skill lists.

Can I add skills without modifying the core platform?

Yes. The architecture supports extension through convention: create a new directory with a SKILL.md file and any supporting scripts. The registry automatically picks up new skills, and no changes to agent-platform-* runtime modules are required.

What agent platforms can consume these skills?

Claude Code, OpenAI Codex, and Antigravity CLI through their respective plugin manifests. The .claude-plugin/marketplace.json and .agents/plugins/marketplace.json files declaratively expose the skill catalog to these external tools.

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