gcp-awareness

# GCP Skills Guide

You have specialized GCP debugging skills. Use these instead of raw gcloud commands for consistent, well-documented workflows.

## Decision Tree

### Skills vs Agents

**Simple, single gcloud command query?**
→ Use `gcp-logs` skill
- Better than: Running raw `gcloud logging read` commands
- Example: "Find ERROR logs for api-gateway service"
- Use when: Quick log fetch, single service, no correlation needed

**Complex investigation requiring multiple steps?**
→ Use Task tool with GCP agents (conserves context)
- `gcp-locator` - Fetch logs from multiple services, save to /tmp
- `gcp-analyzer` - Filter logs, diagnose service issues, check IAM
- `gcp-pattern-finder` - Correlate logs across services, build timelines
- Use when: Multi-service investigation, correlation, pattern detection

### When to Use Which Agent

**Just need to fetch logs broadly?**
→ Use `gcp-locator` agent only
- Fetches logs from multiple services/time ranges
- Saves to /tmp for later analysis
- Example: "Get all ERROR logs from service-b, service-a, backend for last hour"

**Investigating single service issue?**
→ Use `gcp-locator` + `gcp-analyzer` agents
- Locator: Fetch relevant logs
- Analyzer: Filter, diagnose root cause, check IAM/roles
- Example: "Debug service-b permission errors"

**Need to correlate across services or find patterns?**
→ Use all three: `gcp-locator` + `gcp-analyzer` + `gcp-pattern-finder`
- Locator: Fetch from all relevant services
- Analyzer: Filter each service's logs
- Pattern-finder: Correlate by trace_id, build timelines, find patterns
- Example: "Trace request flow across service-a → service-b → backend"

**Need to understand GCP IAP authentication?**
→ Check documentation or use WebFetch
- GCP IAP tokens: `gcloud auth print-identity-token`
- Use for Grafana, ArgoCD, Temporal access

## Available GCP Tools

| Type | Name | Purpose |
|------|------|---------|
| Skill | gcp-logs | Simple log queries (single gcloud command) |
| Agent | gcp-locator |