# Google/Skills Architecture Components: A Complete Technical Guide

> Explore the google/skills architecture components including skill definitions, registry, and runtime modules. Master LLM agents with this comprehensive technical guide.

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

---

**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`](https://github.com/google/skills/blob/main/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`](https://github.com/google/skills/blob/main/SKILL.md). For example, [`skills/cloud/google-cloud-recipe-auth/SKILL.md`](https://github.com/google/skills/blob/main/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`](https://github.com/google/skills/blob/main/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`](https://github.com/google/skills/blob/main/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`](https://github.com/google/skills/blob/main/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`](https://github.com/google/skills/blob/main/skills/cloud/cloud-monitoring-chart-generation/scripts/validate_chart.py) – validates monitoring chart configurations
- [`skills/cloud/agent-platform-tuning/scripts/prepare_dataset.py`](https://github.com/google/skills/blob/main/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`](https://github.com/google/skills/blob/main/.claude-plugin/marketplace.json) – Claude Code integration
- [`.agents/plugins/marketplace.json`](https://github.com/google/skills/blob/main/.agents/plugins/marketplace.json) – Codex and Antigravity CLI integration

These hidden directories declaratively register the repository with consuming tools.

### Installation Tooling

The [`skills.sh`](https://github.com/google/skills/blob/main/skills.sh) installer and `npx skills add` command provide one-click skill bundle deployment. Configuration is documented in the top-level [`README.md`](https://github.com/google/skills/blob/main/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`](https://github.com/google/skills/blob/main/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`](https://github.com/google/skills/blob/main/skills/cloud/google-cloud-solution-rag-enterprise-search-gke-sqldb/references/related-documentation.md)
- [`skills/cloud/spanner-basics/references/core-concepts.md`](https://github.com/google/skills/blob/main/skills/cloud/spanner-basics/references/core-concepts.md)

---

## Interacting with the Google/Skills Architecture

### Listing Skills via CLI

```bash

# Install the skills package (one-time)

npx skills add google/skills

# List every available skill in the repository

skills list

```

### Discovering Skills Programmatically

```python
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

```python
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`](https://github.com/google/skills/blob/main/SKILL.md) files define capabilities in version-controlled Markdown
2. **Registry** – [`skill_registry_ops.py`](https://github.com/google/skills/blob/main/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`](https://github.com/google/skills/blob/main/SKILL.md) files provide human- and machine-readable capability specifications
- **Skill registry** at [`skill_registry_ops.py`](https://github.com/google/skills/blob/main/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`](https://github.com/google/skills/blob/main/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`](https://github.com/google/skills/blob/main/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`](https://github.com/google/skills/blob/main/skills/cloud/agent-platform-skill-registry/scripts/skill_registry_ops.py) maintains a queryable index of all [`SKILL.md`](https://github.com/google/skills/blob/main/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`](https://github.com/google/skills/blob/main/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`](https://github.com/google/skills/blob/main/.claude-plugin/marketplace.json) and [`.agents/plugins/marketplace.json`](https://github.com/google/skills/blob/main/.agents/plugins/marketplace.json) files declaratively expose the skill catalog to these external tools.