# Google/Skills Architecture: 9 Core Components Explained

> Explore the google/skills architecture and its 9 core components. Understand how this skill-first framework empowers LLM agents to manage cloud-native capabilities for enhanced performance.

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

---

**The Google/Skills architecture is a modular, "skill-first" framework that enables LLM agents to discover, invoke, and manage cloud-native capabilities through a layered system of skill definitions, a central registry, runtime modules, and plugin infrastructure.**

This open-source repository implements a plug-and-play ecosystem where each component has a distinct responsibility. Whether you're building agent capabilities or integrating with external harnesses like Claude Code or Codex, understanding these architectural layers is essential for effective development.

---

## Skill Definitions: The Canonical Interface

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 live in individual skill folders (e.g., `skills/cloud/google-cloud-recipe-auth/`) and specify:

- Purpose and scope
- Input/output schemas
- Usage examples
- Dependencies

The [`SKILL.md`](https://github.com/google/skills/blob/main/SKILL.md) serves as the **single source of truth** for what a skill does and how to invoke it. 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 that downstream agents consume directly.

---

## Skill Registry: Central Discovery Service

The **Skill Registry** stores metadata about all available skills and enables runtime discovery.

Implementation lives 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 module handles:

- Registering new skills
- Updating skill metadata
- Querying available capabilities

Agents query this registry to resolve skill names to execution endpoints without hardcoding paths.

---

## Agent-Platform Runtime Modules

The runtime layer executes skill logic and manages the LLM lifecycle. It's organized into specialized sub-packages under `skills/cloud/`:

| Sub-package | Location | Purpose |
|-------------|----------|---------|
| **Inference** | `agent-platform-inference/scripts/` | Model inference and response generation |
| **Model Tuning** | `agent-platform-tuning/scripts/` | Fine-tuning pipelines (e.g., [`tune_open_model.py`](https://github.com/google/skills/blob/main/tune_open_model.py)) |
| **Prompt Management** | `agent-platform-prompt-management/` | Prompt versioning and template storage |
| **Alert Configuration** | `agent-platform-alert-configuration/` | Monitoring and notification setup |

The inference module includes [`openmaas_vertexai_sdk.py`](https://github.com/google/skills/blob/main/openmaas_vertexai_sdk.py), which wraps the Vertex AI SDK for agent consumption.

---

## Utility and Validation Scripts

Helper scripts ensure skill quality and automate infrastructure tasks:

- **[`validate_chart.py`](https://github.com/google/skills/blob/main/validate_chart.py)** (`skills/cloud/cloud-monitoring-chart-generation/scripts/`) — Validates monitoring dashboard configurations
- **[`prepare_dataset.py`](https://github.com/google/skills/blob/main/prepare_dataset.py)** (`skills/cloud/agent-platform-tuning/scripts/`) — Formats training data for tuning jobs
- **Terraform generators** — Provision cloud resources from skill specifications

These utilities run in CI pipelines and local development workflows alike.

---

## Plugin Infrastructure: External Agent Integration

Skills expose themselves to external agent harnesses through **thin wrapper manifests**:

| Plugin type | Manifest location |
|-------------|-----------------|
| Claude Code | [`.claude-plugin/marketplace.json`](https://github.com/google/skills/blob/main/.claude-plugin/marketplace.json) |
| Codex / Antigravity CLI | [`.agents/plugins/marketplace.json`](https://github.com/google/skills/blob/main/.agents/plugins/marketplace.json) |

These JSON files declare the repository as a skill source, enabling one-command installation into agent environments.

---

## Installation Tooling

The [`skills.sh`](https://github.com/google/skills/blob/main/skills.sh) installer and `npx skills add` command provide frictionless onboarding:

```bash

# One-time installation

npx skills add google/skills

# List all available capabilities

skills list

```

This pulls selected skill bundles into the user's environment with dependency resolution.

---

## Well-Architected Framework (WAF) Skill Set

A curated collection encoding Google Cloud's six operational pillars:

- Cost Optimization
- Operational Excellence
- Performance
- Reliability
- Security
- Sustainability

Each pillar resides in `skills/cloud/google-cloud-waf-<pillar>/` with its own [`SKILL.md`](https://github.com/google/skills/blob/main/SKILL.md). For example, [`google-cloud-waf-security/SKILL.md`](https://github.com/google/skills/blob/main/google-cloud-waf-security/SKILL.md) defines security best practices as invocable agent guidance.

---

## Domain-Specific Skill Families

Specialized skill groups wrap cloud-native APIs:

| Family | Path | Capabilities |
|--------|------|--------------|
| GKE basics | `skills/cloud/gke-basics/` | Cluster lifecycle, workload deployment |
| BigQuery basics | `skills/cloud/bigquery-basics/` | Query optimization, data loading |
| Spanner basics | `skills/cloud/spanner-basics/` | Schema design, instance management |
| Firebase basics | `skills/cloud/firebase-basics/` | Mobile backend, real-time sync |

Each family follows the same [`SKILL.md`](https://github.com/google/skills/blob/main/SKILL.md) + scripts pattern for consistency.

---

## Documentation and Reference Assets

Supporting materials live in `references/*.md` files adjacent to skills:

- Architecture diagrams
- Code snippet libraries
- Cross-skill best practices

Example: [`skills/cloud/spanner-basics/references/core-concepts.md`](https://github.com/google/skills/blob/main/skills/cloud/spanner-basics/references/core-concepts.md) provides foundational knowledge that skill implementations cite.

---

## How the Components Interact

The Google/Skills architecture follows a **catalog → registry → runtime → plugins** flow:

1. **Author** creates a [`SKILL.md`](https://github.com/google/skills/blob/main/SKILL.md) and supporting scripts
2. **Registry** ingests metadata from the skill folder
3. **Runtime** executes the skill logic via inference/tuning modules
4. **Plugins** expose the capability to Claude, Codex, or custom agents

Here's how to discover and invoke skills programmatically:

```python

# List available skills from the registry

import requests, json

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']}")

```

```python

# Execute a specific skill

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

```

---

## Summary

- **Skill definitions** ([`SKILL.md`](https://github.com/google/skills/blob/main/SKILL.md) files) declare capabilities in human- and machine-readable form
- **Skill registry** ([`skill_registry_ops.py`](https://github.com/google/skills/blob/main/skill_registry_ops.py)) enables dynamic discovery without hardcoded paths
- **Runtime modules** handle inference, tuning, prompts, and alerts as separate concerns
- **Utility scripts** validate quality and automate infrastructure
- **Plugin manifests** integrate with Claude Code, Codex, and other agent harnesses
- **Installation tooling** ([`skills.sh`](https://github.com/google/skills/blob/main/skills.sh), `npx skills`) provides one-command setup
- **WAF skill set** encodes operational excellence as reusable guidance
- **Domain families** offer specialized cloud API coverage (GKE, BigQuery, Spanner, Firebase)
- **Reference assets** supply diagrams and best-practice documentation

---

## Frequently Asked Questions

### What file format defines a skill in Google/Skills?

Skills are defined in **Markdown files named [`SKILL.md`](https://github.com/google/skills/blob/main/SKILL.md)** located in each skill's root folder. These files specify purpose, inputs, outputs, and examples. The format is intentionally human-readable so developers can author skills without learning a domain-specific language.

### How does the skill registry work at runtime?

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 metadata index of all skills. Agents query this service to resolve skill names to execution endpoints, fetch input schemas, and verify availability before invocation. This decouples skill discovery from hardcoded configuration.

### Can I use Google/Skills with Claude Code or other agents?

Yes. The repository includes plugin manifests in [`.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) that declare compatibility with Claude Code, Codex, and Antigravity CLI. Run `npx skills add google/skills` to install the skill set into these environments.

### Where is model inference implemented in the architecture?

Inference logic resides in `skills/cloud/agent-platform-inference/scripts/`, including [`openmaas_vertexai_sdk.py`](https://github.com/google/skills/blob/main/openmaas_vertexai_sdk.py) which wraps the Vertex AI SDK. This module handles prompt submission, response streaming, and error handling for skill execution.