Google/Skills Architecture: 9 Core Components Explained

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.

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 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 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. 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)
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, 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 (skills/cloud/cloud-monitoring-chart-generation/scripts/) — Validates monitoring dashboard configurations
• 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
Codex / Antigravity CLI	.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 installer and npx skills add command provide frictionless onboarding:

# 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. For example, 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 + 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 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 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:

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

# 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 files) declare capabilities in human- and machine-readable form
• Skill registry (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, 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 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 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 and .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 which wraps the Vertex AI SDK. This module handles prompt submission, response streaming, and error handling for skill execution.

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