What Are Agent Skills in the google/skills Repository?

Agent Skills in the google/skills repository are modular, declarative Markdown assets that enable AI agents to perform concrete, repeatable tasks on Google Cloud through standardized workflows, MCP tool integrations, and official documentation references.

The google/skills repository serves as the central registry for Google's Agent Skills Platform, housing self-contained knowledge files that power AI agents including Claude, Codex, and Antigravity CLI. These declarative assets enable agents to generate precise CLI commands, provision infrastructure, and troubleshoot services without requiring hard-coded logic within the agent itself.

Architecture of the Agent Skills Platform

The repository implements a four-layer architecture that separates skill definition from execution, enabling dynamic discovery and runtime adaptation.

The Skill Registry

The repository functions as a centralized registry where each skill is discoverable via the Skill Registry skill defined in skills/cloud/agent-platform-skill-registry/SKILL.md. This meta-skill allows agents to query available capabilities and understand the taxonomy of the entire collection. Skills are grouped by product domain under the skills/ directory, with subdirectories like cloud/, ads/, and analytics/ organizing capabilities by use case.

Runtime Harness and MCP Integration

When an agent executes npx skills add google/skills, the runtime harness parses each SKILL.md file, registers the metadata, and exposes the skills through the agent's toolset. Skills integrate with the Managed Control Plane (MCP) tooling—specifically functions like answer_query and search_documents—to retrieve official Google documentation in real time. If MCP services are unavailable, skills automatically fall back to direct REST API calls, as implemented in skills/developers/retrieving-developer-knowledge/SKILL.md.

Anatomy of a Skill File

Each Agent Skill is a self-contained SKILL.md file that declares four critical components governing agent behavior.

Metadata Block

The metadata section defines name, category, and description fields that provide unique identifiers and instruct the agent-harness how to surface and categorize the skill. This declarative header enables the runtime to filter and select appropriate skills based on user intent without parsing the full workflow logic.

Workflow Description and Tool Selection

The workflow section outlines exact execution steps, specifying which MCP tools to invoke (such as answer_query for documentation retrieval) or how to construct curl-based REST fallbacks. For example, the Developer Knowledge skill specifies that agents should prefer answer_query when available, but provides exact curl syntax for the developerknowledge.googleapis.com/v1:answerQuery endpoint when MCP is inaccessible.

Synthesis and Output Guidelines

Skills enforce strict synthesis guidelines requiring that final agent responses consist of complete, executable solutions—including commands, YAML or JSON snippets, and code blocks—grounded exclusively in official Google documentation. This constraint eliminates hallucination by binding outputs to verified source material retrieved through the skill's tool chain.

Installing and Executing Agent Skills

The repository supports installation via npm and direct invocation through standardized JSON payloads.

Installation via CLI

Add the complete skill collection to your agent environment using the skills CLI:

# Install the Google Skills collection

npx skills add google/skills

# List available skills (e.g., retrieving-developer-knowledge)

skills list | grep retrieving-developer-knowledge

Direct Skill Invocation

Agents invoke skills by specifying the skill name, target action, and parameters through a structured JSON interface:

# Example: Using the "retrieving-developer-knowledge" skill via the CLI harness

{
  "skill": "retrieving-developer-knowledge",
  "action": "answer_query",
  "params": {
    "query": "How do I enable Cloud Logging for a GKE cluster?"
  }
}

REST Fallback Execution

When MCP tooling is unavailable, agents execute the fallback REST pattern defined in the skill specification:

# Direct REST fallback (if MCP tools are missing)

curl -s -X POST "https://developerknowledge.googleapis.com/v1:answerQuery" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{"query":"Enable Cloud Logging for GKE"}'

Key Skill Implementations

The repository contains reference implementations demonstrating different complexity levels:

• skills/developers/retrieving-developer-knowledge/SKILL.md – Illustrates metadata definition, MCP tool selection (answer_query), and REST fallback logic for documentation retrieval.
• skills/cloud/google-cloud-solution-build-deploy-agents/SKILL.md – Demonstrates orchestration patterns for building and deploying AI agents on Google Cloud infrastructure.
• skills/cloud/gke-inference/SKILL.md – Provides specialized workflows for GKE AI/ML inference deployment, including resource provisioning and model serving configurations.
• skills/cloud/agent-platform-skill-registry/SKILL.md – Defines the meta-skill that enables agents to discover and enumerate other skills within the repository.

Summary

• Agent Skills are declarative SKILL.md files stored in the google/skills repository that define how AI agents interact with Google Cloud services.
• Each skill specifies metadata, workflows, MCP tool preferences (like answer_query and search_documents), and synthesis guidelines that enforce executable output formats.
• The repository acts as a central registry via the Skill Registry skill, enabling dynamic discovery and registration through npx skills add google/skills.
• Skills implement graceful degradation: when MCP tools are unavailable, they fall back to direct REST API calls using authenticated curl commands.
• Skills are organized hierarchically under skills/cloud/, skills/ads/, and skills/analytics/ directories, covering infrastructure, advertising, and analytics use cases.

Frequently Asked Questions

What is the purpose of the SKILL.md file format?

The SKILL.md format provides a declarative, human-readable structure for defining agent capabilities that separates knowledge assets from agent implementation. This standardization allows multiple AI agents—including Claude, Codex, and Antigravity CLI—to consume the same skill definitions without requiring platform-specific adapters or hard-coded logic.

How do Agent Skills handle MCP service unavailability?

According to the source implementation in skills/developers/retrieving-developer-knowledge/SKILL.md, skills define explicit fallback logic that triggers when MCP tools are unreachable. The agent automatically switches to direct REST API calls using curl commands authenticated via gcloud auth print-access-token, ensuring continuous operation even when the Managed Control Plane experiences outages.

What types of tasks can Agent Skills perform on Google Cloud?

Agent Skills enable agents to execute concrete operational tasks including generating precise CLI commands for infrastructure provisioning, troubleshooting service configurations, retrieving official documentation through the Developer Knowledge API, and orchestrating complex deployments such as GKE inference clusters as defined in skills/cloud/gke-inference/SKILL.md.

Where are Agent Skills organized within the repository structure?

Skills are categorized by product domain under the root skills/ directory, with subdirectories like cloud/ for infrastructure tasks, ads/ for advertising platform operations, and analytics/ for data analysis workflows. This taxonomy allows the Skill Registry to filter and surface relevant capabilities based on the agent's current operational context.

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