К основному содержанию
скилл CX Codex

gcp-architecture-discovery — скилл для Claude Code: карта GCP

Скилл gcp-architecture-discovery обходит GCP-проект от сбойного сервиса и собирает карту зависимостей: compute, сети, базы, бакеты. Результат кладёт в файлы, чтобы следующая сессия не начинала с нуля.

Apache-2.0 ★ 151 обновлён 2026-10-12

Установить в Claude Code · Через маркетплейс плагинов Все способы и платформы ↓
/plugin marketplace add gemini-cli-extensions/sre
/plugin install sre-extension@sre
Открыть на GitHub

Что делает gcp-architecture-discovery

Скилл обходит GCP-проект и собирает карту инфраструктуры: compute, сети, хранилища, зависимости между сервисами. Начинает с якоря — сервиса, который сбоит или только что починили. Дальше разворачивает окружение: балансировщики, VPC и подсети, firewall и NAT, базы, топики Pub/Sub, бакеты. На одном ресурсе останавливаться нельзя, иначе изменённое правило firewall или удалённая база останутся незамеченными.

Результат не живёт в чате. В каталоге discover/{gcp-project}/{PROJECT_ID}/ появляются discover.json со списком ресурсов, зависимостями и Graphviz DOT-кодом для схемы, файлы wiki.<категория>.md по типам ресурсов и отрисованный discover.png. В wiki.overview.md лежит ссылка на картинку топологии и описание проекта. Каждый ресурс в своей вики идёт заголовком ##, свойства и зависимости — уровнями ниже. Найденное сразу пишут в файлы, старую схему переписывают без колебаний.

Запускать это в основном потоке нельзя. Обход долгий и блокирующий, поэтому описание требует фоновый подагент через invoke_subagent с типом self, а готовый результат приходит через send_message. Ресурсы находятся запросами list и describe к GCP.

Какие задачи решает

  • собрать карту зависимостей упавшего сервиса в GCP
  • выяснить, какие правила firewall и подсети поменялись после правок
  • отрисовать топологию проекта в PNG для разбора инцидента
  • разложить ресурсы по категориям в wiki.*.md с их свойствами
  • проверить, что бакет или топик из старой схемы ещё существует

Примеры запросов агенту

  • Запусти фоновый подагент со скиллом gcp-architecture-discovery: обойди окружение упавшего сервиса в проекте prod-42, обнови discover.json и напиши мне, когда закончишь.
  • Разберись, какие правила firewall и подсети поменялись вокруг api-gateway в my-proj, и перерисуй discover.png.
  • Собери вики по типам ресурсов для проекта my-proj: начни с Cloud Run и баз, потом пришли сообщение.

Как установить gcp-architecture-discovery

1Через маркетплейс плагинов

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

Команда ставит плагин sre-extension целиком, со всеми его скиллами

2Через Skills CLI (Vercel)

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

3Вручную: положить файлы

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

Папка скилла целиком; для одного проекта — .claude/skills/gcp-architecture-discovery/

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы о gcp-architecture-discovery

Как установить gcp-architecture-discovery в Claude Code?

Подключите маркетплейс командой /plugin marketplace add gemini-cli-extensions/sre, затем поставьте плагин: /plugin install sre-extension@sre.

Что делает gcp-architecture-discovery?

Обходит ресурсы GCP от якорного сервиса и раскладывает найденное по файлам: discover.json с зависимостями и DOT-кодом, вики по категориям и схему discover.png.

Почему скилл требует запуска в фоне?

Обход проекта долгий и блокирует работу, поэтому вместо основного потока описание велит поднять подагент через invoke_subagent с типом self и ждать сообщения через send_message.

Исходный текст

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

Похожие скиллы

Все скиллы по теме «Облака: AWS, Azure, GCP» →
aws-architecture-diagram vidanov Скилл aws-architecture-diagram для Claude Code собирает AWS-архитектурные диаграммы в формате .drawio из официальных иконок. Экспортирует результат в PNG, SVG или PDF. CX Codex +1 872установок google-cloud-solution-architecture официальный google Скилл google-cloud-solution-architecture для Claude Code проектирует решения на Google Cloud из нескольких сервисов. Он начинает с вопросов о требованиях к новой нагрузке или миграции. CX Codex +1 5 980установок design-discovery-full gotalab Правило design-discovery-full проводит систематическое исследование требований, существующего кода, технологий и рисков перед тем, как начать дизайн. Помогает выбрать архитектуру на основе фактов, а не предположений. CX Codex +1 ★ 3 774звёзд репо dt-obs-gcp Dynatrace Скилл dt-obs-gcp для Claude Code запрашивает GCP-ресурсы через Dynatrace Smartscape и DQL. Охватывает Compute Engine, GKE, Cloud Run, Pub/Sub, VPC, IAM и Secret Manager. CX Codex +1 2 300установок gcp-development Mindrally Скилл gcp-development для Claude Code и Codex. Задаёт рамки разработки под Google Cloud: Cloud Functions, Cloud Run, Firestore, BigQuery, Terraform и безопасность через IAM. CX Codex +1 986установок gcp-to-aws cline Скилл gcp-to-aws для Claude Code планирует перенос рабочих нагрузок из GCP в AWS, включая AI-приложения. Запускается по запросам о миграции сервисов, Terraform или AI-провайдера. CX Codex +1 842установок

Из того же набора17

Весь набор →
postmortem-aggregator Скилл postmortem-aggregator для Claude Code разбирает Post Mortem в папке, рассчитывает показатели сбоев и обновляет POMO_AGGREGATED.md. Помогает находить повторяющиеся причины инцидентов. CX Codex +1 ★ 151звёзд репо gcp-mcp-setup Скилл gcp-mcp-setup для Claude Code, Codex и Gemini CLI автоматизирует подключение Google Managed MCP-серверов (OneMCP) к CLI-окружению. Включает нужные API, генерирует ключи и записывает конфигурацию в нужный файл настроек. CX Codex +1 ★ 151звёзд репо generic-mitigations Скилл generic-mitigations учит ИИ-агента купировать сбои в продакшене типовыми мерами SRE вместо долгих раскопок причин во время аварии. CX Codex +1 ★ 151звёзд репо monitoring-graphs Скилл monitoring-graphs для Claude Code, Codex и Gemini CLI генерирует аннотированные графики инцидентов на Python. Запускается, когда нужно визуализировать сбой, показать скачки ошибок или соотнести метрики с этапами инцидента. CX Codex +1 ★ 151звёзд репо anomaly-detection Скилл anomaly-detection находит аномалии во временных рядах из CSV, мониторинга облака и других источников. Автоматически выбирает алгоритм и параметры сглаживания, или работает по вашим настройкам. CX Codex +1 ★ 151звёзд репо investigation-entrypoint Скилл investigation-entrypoint расследования сбоев в Google Cloud Platform для Claude Code, Codex и Gemini CLI. Координирует диагностику GKE и Cloud Run при инцидентах. CX Codex +1 ★ 151звёзд репо postmortem-generator Скилл postmortem-generator для Claude Code собирает постмортем по инциденту: ведёт к таймлайну, action items и черновику Google Doc. Нужны данные расследования и root cause. CX Codex +1 ★ 151звёзд репо sre-extension Плагин sre-extension для Claude Code помогает расследовать сбои в Google Cloud, разбирать логи и создавать постмортемы. CX Codex ★ 151звёзд репо

Спонсоры проекта

Компании, которые помогают держать аналитику открытой