How to Integrate Google Cloud Well-Architected Framework Principles with Agent Skills

The google/skills repository encapsulates each Well-Architected Framework pillar as a declarative markdown skill that agents fetch via HTTP to generate real-time workload recommendations without code redeployment.

The Google Cloud Well-Architected Framework (WAF) defines six pillars—Cost Optimization, Security, Reliability, Performance Optimization, Operational Excellence, and Sustainability—that guide cloud architecture decisions. The google/skills open-source repository implements each pillar as a self-contained Agent Skill, allowing conversational AI and automation workflows to programmatically embed WAF best practices into infrastructure design and operational tasks.

Architectural Mapping of WAF Pillars to Agent Skills

Each WAF pillar maps to a dedicated skill definition stored as SKILL.md within the repository's skills/cloud/ directory. These files contain the core principles, validation checklists, and assessment questions required to evaluate workloads against Google Cloud standards.

The architectural components function as follows:

• Skill definition (SKILL.md) – Stores declarative pillar content including principles, GCP product references, and assessment questions. For example, skills/cloud/google-cloud-waf-cost-optimization/SKILL.md captures cost-optimization principles, while skills/cloud/google-cloud-waf-security/SKILL.md defines security controls.
• Skill Registry (index.json) – Located at the repository root, this JSON file lists all available skills with metadata and entrypoint URLs, enabling dynamic discovery.
• Entrypoint URL – A raw GitHub URL (e.g., https://raw.githubusercontent.com/google/skills/main/skills/cloud/google-cloud-waf-reliability/SKILL.md) that agents call to fetch the latest skill definition on demand.
• Agent Platform Integration – Runtime services such as skills/cloud/agent-platform-skill-registry/scripts/skill_registry_ops.py parse the markdown and orchestrate user assessments based on the embedded questions.

Because skills are defined in standalone markdown files rather than compiled code, updating WAF guidance requires only modifying the relevant SKILL.md. Agents automatically receive changes on the next fetch, ensuring continuous compliance without redeployment.

Implementing Agent-Driven WAF Assessments

Agents interact with the framework through a three-phase workflow: discovery, fetch, and orchestration. Below are concrete implementations for each phase.

Discovering Skills via the Registry

Agents first query index.json to identify which WAF pillars are available. The registry returns skill names, descriptions, and entrypoint locations.

import requests

REGISTRY_URL = (
    "https://raw.githubusercontent.com/google/skills/main/index.json"
)

def list_waf_skills():
    data = requests.get(REGISTRY_URL).json()
    waf_skills = [
        s for s in data["skills"]
        if "WellArchitectedFramework" in s["description"]
    ]
    for skill in waf_skills:
        print(f"- {skill['name']}: {skill['description']}")

if __name__ == "__main__":
    list_waf_skills()

This returns entries for all six pillars, including google-cloud-waf-cost-optimization, google-cloud-waf-security, and google-cloud-waf-reliability.

Fetching Pillar Definitions

Once an agent identifies the relevant pillar, it fetches the raw markdown definition. For example, to retrieve security principles:

curl -s https://raw.githubusercontent.com/google/skills/main/skills/cloud/google-cloud-waf-security/SKILL.md \
| grep -A5 "Core principles"

The response contains the structured guidance that the agent parses to generate recommendations.

Orchestrating the Assessment Workflow

The following pseudo-code demonstrates how an agent evaluates cost optimization for a specific workload by combining the skill definition with user input:

def evaluate_cost_optimization(workload_context):
    # 1. Fetch skill definition

    skill_url = "https://raw.githubusercontent.com/google/skills/main/skills/cloud/google-cloud-waf-cost-optimization/SKILL.md"
    skill_md = requests.get(skill_url).text
    
    # 2. Extract assessment questions

    questions = extract_section(skill_md, "Workload assessment questions")
    answers = conduct_qa(questions)  # Interactive user prompt

    
    # 3. Map answers to principles

    principles = extract_section(skill_md, "Core principles")
    recommendations = [
        tailor(principle, answers) 
        for principle in principles
    ]
    
    return {
        "principles": principles,
        "assessment_answers": answers,
        "recommendations": recommendations
    }

The extract_section helper parses markdown headings, while tailor maps user context (e.g., "no committed use discounts") to specific GCP service recommendations (e.g., "Enable CUDs via Cloud Billing").

Extending the Framework with Custom Pillars

Teams can add new WAF-aligned skills by creating additional SKILL.md files and registering them in index.json. For example, to add an AI Security pillar:

mkdir -p skills/cloud/google-cloud-waf-ai-security

# Create SKILL.md with AI-specific principles and assessment questions

# Then register in index.json:

{
  "name": "google-cloud-waf-ai-security",
  "description": "Generates AI-security guidance based on the Well-Architected Framework.",
  "entrypoint": "https://raw.githubusercontent.com/google/skills/main/skills/cloud/google-cloud-waf-ai-security/SKILL.md"
}

Once committed to the repository, agents discover the new skill immediately upon the next registry poll.

Summary

• The google/skills repository implements the six WAF pillars as standalone markdown skills that agents consume via HTTP.
• Each pillar's logic resides in skills/cloud/google-cloud-waf-{pillar}/SKILL.md, containing principles, questions, and GCP service mappings.
• The index.json registry enables dynamic skill discovery without hardcoding URLs in agent logic.
• Agents fetch definitions at runtime, enabling continuous compliance—updates to WAF guidance propagate instantly without code redeployment.
• Helper utilities in skills/cloud/agent-platform-skill-registry/scripts/skill_registry_ops.py provide runtime support for registry operations.

Frequently Asked Questions

What is the relationship between SKILL.md files and the Well-Architected Framework pillars?

Each SKILL.md file represents a single WAF pillar (Cost Optimization, Security, Reliability, Performance Optimization, Operational Excellence, or Sustainability). The markdown contains the pillar's core principles, assessment questions, and recommended GCP services, structured so agents can parse and present them programmatically.

How does the agent platform discover available WAF skills?

The agent queries index.json at the repository root, which lists all skills with their names, descriptions, and raw entrypoint URLs. The platform filters for WAF-related entries by checking descriptions or name prefixes like google-cloud-waf-.

Can I customize or extend the existing WAF skills?

Yes. Because skills are declarative markdown files, you can modify existing SKILL.md files to add new assessment questions or update GCP service recommendations. You can also create new skill directories following the naming convention google-cloud-waf-{custom-name} and register them in index.json for immediate agent availability.

How does the system ensure agents use the latest WAF guidance?

Agents fetch skill definitions directly from raw GitHub URLs at runtime rather than bundling static copies. When the google/skills repository updates a SKILL.md, those changes are reflected in the next HTTP request from any agent, ensuring continuous synchronization with the latest Well-Architected Framework standards without requiring code redeployment or version bumps.

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