Skip to main content
skill CX Codex

gcp-architecture-discovery — Claude Code skill: GCP infra map

gcp-architecture-discovery — a skill that walks a GCP project outward from the service that broke and writes down what it finds: compute, networks, databases, buckets. The map stays on disk between sessions.

Apache-2.0 ★ 151 updated 2026-10-12

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add gemini-cli-extensions/sre
/plugin install sre-extension@sre
Open on GitHub

What gcp-architecture-discovery does

Point it at a GCP project and it maps what the incident touches: compute, network layers, storage, and the links between services. It starts from an anchor, the service that failed or was just fixed. Then it works outward through load balancers, VPCs and subnets, firewalls, NAT, databases, Pub/Sub topics and buckets. Stopping at the single broken resource hides the firewall edit or the deleted database behind it.

Output goes to disk rather than into the chat. Under discover/{gcp-project}/{PROJECT_ID}/ you get discover.json with resources, dependencies and the Graphviz DOT used for the drawing, one wiki.<category>.md per resource type, and a rendered discover.png. wiki.overview.md holds the topology image link plus a project summary. Every resource gets its own ## heading in its category file, with properties and dependencies underneath.

Running it inline blocks the agent for the whole sweep, so the workflow is built around a background subagent: spawn one with invoke_subagent (type self) and let it report back through send_message. Resource facts come from list and describe calls against GCP.

What it helps with

  • trace dependencies of a failing GCP service mid-incident
  • find firewall or NAT changes made after a fix
  • draw a topology diagram both a human and the agent can read
  • document each resource type in its own wiki.*.md file
  • refresh a stale cache after a database or topic was deleted

Example prompts for the agent

  • Spawn a background subagent with the gcp-architecture-discovery skill: sweep everything around the failing service in prod-42, refresh discover.json, and message me when it's done.
  • Check which firewall rules and subnets changed around api-gateway in my-proj and redraw discover.png.
  • Write the per-type wiki files for my-proj, starting with Cloud Run and the databases.

How to install gcp-architecture-discovery

1Plugin marketplace

/plugin marketplace add gemini-cli-extensions/sre
/plugin install sre-extension@sre

This installs the whole sre-extension plugin with all its skills

2Skills CLI (Vercel)

npx skills add gemini-cli-extensions/sre --skill gcp-architecture-discovery -a claude-code

3Manually: put the files in place

~/.claude/skills/gcp-architecture-discovery/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/gcp-architecture-discovery/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about gcp-architecture-discovery

How do I install gcp-architecture-discovery in Claude Code?

Add the marketplace first with /plugin marketplace add gemini-cli-extensions/sre, then install the plugin: /plugin install sre-extension@sre.

What does gcp-architecture-discovery do?

It sweeps GCP resources around an anchor service and stores the result as discover.json with dependencies and DOT code, per-category wiki files, and a discover.png diagram.

Why does the skill have to run in the background?

The sweep takes a while and blocks whatever runs it, so the skill asks for a subagent spawned through invoke_subagent with type self, reporting back via send_message.

Source text

SKILL.md · Apache-2.0
---
name: gcp-architecture-discovery
description: 🐉 Discover and map GCP infrastructure architecture including compute, networking, storage, and service dependencies.
metadata:
  author: sstawski
  version: 0.1.2
---

# GCP Architecture Discovery

## Overview

This skill provides a **discovery** approach for GCP infrastructure. It discovers what's needed for the current investigation and caches results for future use.

> **RULE: ASYNCHRONOUS INVOCATION ONLY**
> You MUST NEVER execute this skill in the main conversation thread. Because architecture discovery is a long-running, blocking task, you must **ALWAYS** invoke it as a background subagent, regardless of whether you are in an investigation, setting up a new project, or performing a routine audit.
> **How to invoke:** Use the `invoke_subagent` tool to spawn a clone of yourself (Subagent Type: `self`), and provide it with a prompt to execute this discovery workflow and notify you via `send_message` when complete. The main agent must continue its tasks immediately without waiting.

## When to Use

- When investigating a failing service or starting an incident response.
- When an incident has been resolved and the system topology has changed (e.g., firewall blocked an IP, traffic diverted).
- When initializing a new GCP project for the first time.
- Identifying dependencies between services during incidents.
- Creating architecture diagrams for human and agent understanding.
- Auditing specific resource configurations.

### Philosophy & Agent Mindset

**The Architecture Graph is Your Mental Model.**
The `discover.json` and generated PNG represent *how you see the system right now*. **Do not hesitate** to update, rewrite, or expand the graph whenever you discover something new. For example: If you realize a Load Balancer connects to a different backend than previously drawn, overwrite it immediately.

**Discovery Strategy (Adaptive Blast Radius)**
Exhaustive scans of an entire massive project waste time, but lazily scanning just one node *causes you to miss critical infrastructure changes* (e.g. altered firewalls, deleted databases, changed IAM policies).
- **Find the Anchor**: Start at the service or node experiencing the incident.
- **Map the Full Blast Radius**: You MUST aggressively discover and map ALL resources functionally or topologically connected to the anchor. This includes checking:
  - Upstream Load Balancers or API Gateways.
  - Surrounding Network boundaries (VPCs, Subnets, Firewalls, NATs). Did any rules change?
  - Downstream targets (Databases, Pub/Sub topics, Cloud Storage). Do they still exist?
> 🚨 **CRITICAL RULE:** NEVER stop after discovering just the single affected resource. You MUST forcefully map its entire surrounding ecosystem. Relying on old cache assumptions causes you to miss deleted, unmapped, or altered infrastructure.
- **Update Cache**: Merge the discovered ecosystem slice into the existing graph.

### State Management

> 🚨 **CRITICAL RULE: MANDATORY OUTPUT GENERATION**
> Setting up or updating the discovery folder structure is **NOT OPTIONAL**. Every time this skill is triggered, you **MUST ALWAYS** create or update the corresponding target folder, `.json`, `.md` and generate the `.png` visualization accurately. Never leave the data exclusively in the chat context.

The folder structure **MUST** be strictly organized as follows:
`{AGENT_WORKSPACE_ROOT}/discover/{gcp-project|azure-subscription}/{PROJECT_ID_OR_SUBSCRIPTION_NAME}/`

Inside each project/subscription directory, maintain these explicit files:

1. **`discover.json` (Structured Data Cache)**:
   - Contains a list of instances.
   - Contains references/dependencies to other resources.
   - Holds the raw Graphviz DOT code inside a `"graphviz"` key for rendering.
   - Easy for the agent to parse programmatically.

2. **`wiki.<category>.md` (Topological Documentation by Resource Type)**:
   - Contains markdown documentation explaining how these pieces of architecture work together, separated into distinct files based on resource category (e.g., `wiki.gce.md` for VMs, `wiki.vnet.md` for networks, `wiki.cloudrun.md` for Cloud Run, `wiki.sql.md` for databases).
   - One file, `wiki.overview.md`, MUST contain the main topology image link (`![Topology](./discover.png)`) and the high-level project description.
   - **MANDATORY STRUCTURE**: Each resource/app running on GCP MUST be documented under an `##` (H2) header inside its respective category file.
   - Important sub-points (such as properties, dependencies, configurations) MUST use `###` (H3) or `####` (H4) headers under the respective resource.
   - All resources/apps must explicitly list their most important properties (e.g., regions, versions, tier/scaling limits) and their dependencies.
   - Easy for humans and reasoning models to read contextually.

## Core Discovery Workflow

**Step 1: Check Cache First**
```bash
# Agent checks documentation for architecture
# Files: ./discover/{gcp-project|azure-subscription}/{PROJECT_ID_OR_NAME}/discover.json and ./discover/{gcp-project|azure-subscription}/{PROJECT_ID_OR_NAME}/wiki.*.md
```

**Step 2: Discovery Sweep (Blast Radius)**
- Query GCP to `list` or `describe` core resources connected to the incident. Do not rely on old cache assumptions—if a resource is throwing errors, verify its existence, its properties, and its relations.
- Identify everything in the event's blast radius: services, DBs, storage buckets, VPCs, Firewalls, and their direct upstream callers/downstream dependencies. Look out for missing, newly created, or modified resources in this radius.

**Step 3: Discover Dependencies & Network Layers**
- For the discovered compute services → check if they call other services (via environment variables, service mesh). Determine Serverless VPC Access connections if any.
- For the discovered GKE services → check backend services they depend on. Inspect VPC, subnets, and Network Policies.
- **Discover Network & Security Layers**: Identify and explicitly map ALL Virtual Networks (VPCs, Subnets), Security Perimeters (e.g., VPC Service Controls, IAP boundaries), Firewalls, Cloud NAT, and Load Balancers routing the traffic. Map all ingress/egress boundaries for your scope.
- Store this dependency map, security boundaries, and network topologies in the relevant `discover.json` file.


**Step 4: 🛑 MANDATORY TOOL EXECUTION - Update Cache**
You **MUST always perform this step**. Never skip saving your discoveries to disk. **Do not hesitate** to update the cache—this is your active mental model. Overwrite outdated assumptions immediately.
**CRITICAL:** You must physically execute the `replace_string_in_file` or `create_file` tools to update these files *BEFORE* responding to the user.
- Add newly discovered resources to `./discover/{gcp-project|azure-subscription}/{PROJECT_ID_OR_NAME}/discover.json`. Create the file/directory if it does not exist.
- Update timestamps inside `discover.json`.
- Update the context in the respective `./discover/{gcp-project|azure-subscription}/{PROJECT_ID_OR_NAME}/wiki.<category>.md` files based on resource type (e.g., `wiki.vnet.md`, `wiki.gce.md`). Create the files if they do not exist. Ensure there are NO raw graphviz blocks inside any wiki file.
- Save the raw Graphviz DOT code inside the `"graphviz"` key of `./discover/{gcp-project|azure-subscription}/{PROJECT_ID_OR_NAME}/discover.json`.
- **CRITICAL GRAPHING RULE**: The Graphviz graph **MUST visually encompass all topological layers**. You must map EVERY resource and application into proper `subgraph` structures that represent their actual Network boundaries (Virtual Networks, VPCs, Subnets), Security Perimeters (VPC Service Controls, IAM domains), and Firewall rules (ingress/egress policies). No compute resource should "hang flat" without its network/security context.
- Run `python skills/gcp-architecture-discovery/scripts/render_architecture_png.py ./discover/{gcp-project|azure-subscription}/{PROJECT_ID_OR_NAME}/discover.json` to generate a PNG graphic of the architecture.

**Step 5: Document in Session**
- When working on an incident, update the respective `wiki.<category>.md` files to reflect the latest known good state if discrepancies were found.
- Note any gaps or unknowns.

## Common Patterns

### Microservices on GKE
- GKE cluster → Namespaces → Deployments → Pods
- Ingress → Services → Pods
- ConfigMaps and Secrets for configuration
- Cloud SQL or external databases

### Serverless Architecture
- Cloud Run services → Cloud SQL
- Cloud Functions → Pub/Sub → Cloud Storage
- API Gateway → Backend services

### Hybrid Architecture
- GKE for stateful services
- Cloud Run for stateless APIs
- Cloud Functions for event processing
- Mix of GCE VMs for legacy applications

## Safe Mode Support

This skill respects `SAFE_MODE="enabled"` and will only use read-only commands. All discovery operations are non-mutating and safe to run during incidents.

## Related Skills

- **gcp-mcp-setup**: Setup Google Cloud MCP server. Highly recommended for agents as it provides native, structural API discovery instead of screen-scraping CLI output!
- **gcp-playbooks**: Use discovered architecture for mitigation
- **cloud-monitoring**: Query metrics for discovered resources

## Tips & Best Practices

1. **Prefer MCP over CLI (but use CLI as fallback)**: If connected, use GCP MCP tools for structured API exploration instead of invoking `gcloud` locally, as it perfectly fits the agent's JSON capabilities. If MCP is missing or lacking specific access, fall back to standard `gcloud` commands.
2. **Start Narrow, Expand as Needed**: Begin with the target service, then discover dependencies iteratively.
3. **Use `describe`** over `list` during incidents**: Target specific resources by name to save time, rather than performing bulk operations.
4. **Update Cache Incrementally**: When discovering new context, merge new discoveries into `discover.json`. Don't overwrite the entire cache unless performing a baseline regeneration.
5. **Trust the Mental Model**: If your `discover.json` cache is recent, rely on it to make architectural decisions quickly during an outage. Only refresh specific resource nodes when you suspect they've undergone recent changes (e.g. recent deployments).

© sstawski · Apache-2.0 · gemini-cli-extensions/sre

Similar skills

All skills for Cloud: AWS, Azure, GCP →
aws-architecture-diagram vidanov Generates AWS architecture diagrams as native .drawio files. It writes mxGraphModel XML with official AWS Architecture Icons and can export the result to PNG, SVG, or PDF via the draw.io CLI. CX Codex +1 872installs google-cloud-solution-architecture official google google-cloud-solution-architecture is a Claude Code skill for designing multi-service Google Cloud systems. It gathers workload or migration requirements before shaping a solution. CX Codex +1 5,980installs design-discovery-full gotalab The design-discovery-full rule systematically maps requirements, existing code, technologies, and risks before design begins. It ensures architectural choices rest on facts rather than assumptions. CX Codex +1 ★ 3,774repo stars dt-obs-gcp Dynatrace dt-obs-gcp — a skill for Claude Code, Codex, Cursor, GitHub Copilot, and Gemini CLI that queries GCP resources via Dynatrace Smartscape and DQL. Covers Compute Engine, GKE, Cloud Run, Pub/Sub, VPC, IAM, and Secret Manager. CX Codex +1 2,300installs gcp-development Mindrally gcp-development — a rule set for building on Google Cloud: Cloud Functions, Cloud Run, Firestore, BigQuery and Terraform. Useful when your agent writes GCP code or infrastructure. CX Codex +1 986installs gcp-to-aws cline gcp-to-aws is a Claude Code skill that plans GCP-to-AWS workload migrations, including AI applications. It activates on requests to move cloud services, Terraform infrastructure, or AI workloads. CX Codex +1 842installs

From the same set17

The whole set →
postmortem-aggregator postmortem-aggregator turns Post Mortem files in a folder into incident statistics and updates POMO_AGGREGATED.md. Use it to spot recurring causes across incidents. CX Codex +1 ★ 151repo stars gcp-mcp-setup gcp-mcp-setup — a skill for Claude Code, Codex, and Gemini CLI that wires up Google Managed MCP servers (OneMCP) to your CLI environment. It enables APIs, generates an API key, and writes the MCP config to the right settings file. CX Codex +1 ★ 151repo stars generic-mitigations generic-mitigations guides your agent to halt production outages quickly using standard SRE strategies before diving into root-cause analysis. CX Codex +1 ★ 151repo stars monitoring-graphs monitoring-graphs — a skill for Claude Code, Codex and Gemini CLI that generates annotated incident graphs in Python. Use it to visualize outages, plot error spikes, or correlate metrics with incident milestones. CX Codex +1 ★ 151repo stars anomaly-detection anomaly-detection detects outliers in time-series metrics from CSV, cloud monitoring, and other sources. Chooses smoothing and algorithms automatically, or accepts your tuning parameters. CX Codex +1 ★ 151repo stars investigation-entrypoint The investigation-entrypoint skill for Claude Code, Codex, and Gemini CLI coordinates GCP incident investigations across GKE and Cloud Run. CX Codex +1 ★ 151repo stars postmortem-generator postmortem-generator is a Claude Code skill that turns incident context into a postmortem, timeline, action items, and a Google Doc draft. It starts after investigation and root-cause work. CX Codex +1 ★ 151repo stars sre-extension The sre-extension plugin for Claude Code supports Google Cloud outage investigations, log analysis, and post-mortem generation. CX Codex ★ 151repo stars

Project sponsors

Companies that keep this analytics open