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

> Integrate Google Cloud Well-Architected Framework principles with Agent Skills. Leverage declarative markdown skills for real-time workload recommendations without code redeployment.

- Repository: [Google/skills](https://github.com/google/skills)
- Tags: how-to-guide
- Published: 2026-09-04

---

**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`](https://github.com/google/skills/blob/main/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`](https://github.com/google/skills/blob/main/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`](https://github.com/google/skills/blob/main/skills/cloud/google-cloud-waf-cost-optimization/SKILL.md) captures cost-optimization principles, while [`skills/cloud/google-cloud-waf-security/SKILL.md`](https://github.com/google/skills/blob/main/skills/cloud/google-cloud-waf-security/SKILL.md) defines security controls.
- **Skill Registry ([`index.json`](https://github.com/google/skills/blob/main/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`](https://github.com/google/skills/blob/main/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`](https://github.com/google/skills/blob/main/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`](https://github.com/google/skills/blob/main/index.json) to identify which WAF pillars are available. The registry returns skill names, descriptions, and entrypoint locations.

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

```bash
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:

```python
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`](https://github.com/google/skills/blob/main/SKILL.md) files and registering them in [`index.json`](https://github.com/google/skills/blob/main/index.json). For example, to add an AI Security pillar:

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

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

# Then register in index.json:

```

```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`](https://github.com/google/skills/blob/main/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`](https://github.com/google/skills/blob/main/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`](https://github.com/google/skills/blob/main/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`](https://github.com/google/skills/blob/main/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`](https://github.com/google/skills/blob/main/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`](https://github.com/google/skills/blob/main/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`](https://github.com/google/skills/blob/main/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.