Cor-IncorporatedCor-Incorporated/claude-code-skills/skills/gcp-deploy-guardian/SKILL.md

gcp-deploy-guardian

Skill5 starsChanged 2 months agoMITView on GitHub

Prevent GCP deployment failures by validating Docker builds, Cloud Run deploys, and GKE rollouts. Triggers on: docker build, docker push, gcloud run deploy, kubectl apply, Dockerfile/cloudbuild.yaml/nginx.conf edits. Catches arm64-amd64 platform mismatch, Mixed Content from http:// build args, VAD/WASM asset 404s, nginx MIME breakage. Use for all Apple Silicon to GCP deploy workflows. Do NOT use for local-only Docker builds, non-GCP deployments, or application logic changes.

In this repository25 other files it gives its agents.
- AGENTS.mdAGENTS.md
- adk-engineerSkill
- agent-orchestratorSkill
- brainstormingSkill
- bugfixSkill
- classify-reviewSkill
- code-reviewerSkill
- codex-reviewSkill
- context7-skillsSkill
- developer-growth-analysisSkill
- file-organizerSkill
- gws-workspaceSkill
- handoverSkill
- modern-architectureSkill
- planSkill
- repo-cleanSkill
- review-loopSkill
- security-reviewSkill
- skill-creatorSkill
- supabase-nextjs-debuggerSkill
- tdd-workflowSkill
- test-falsifySkill
- ui-design-systemSkill
- ui-skillsSkill
- ux-researcher-designerSkill

The file

We split this skill into the rules it gives an agent

2 rules. About 0 are common, 1 is distinctive, and 1 is very specific to this project.

≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.

Common
Distinctive
Very specific

Very specific:
Verify --platform linux/amd64 on every Docker build from Apple Silicon.
line 24
Distinctive:
After push, inspect the manifest:
line 30

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.

Files

SKILL.md

GCP Deploy Guardian

Auto-activate on GCP deploy operations. Prevent known production incidents (Issue #40, #43, #45, #47, #48).

Trigger Conditions

Activate when detecting:

docker build / docker push commands
gcloud run deploy commands
kubectl apply / kubectl set image commands
cloudbuild.yaml / Dockerfile / nginx.conf / vite.config.ts edits

Pre-Deploy Checks (Run ALL Before Build)

<important if="building Docker images for GCP deployment or running docker build on Apple Silicon">
### 1. Platform Verification (CRITICAL)

Verify --platform linux/amd64 on every Docker build from Apple Silicon.

bash ${CLAUDE_SKILL_DIR}/scripts/pre-deploy-check.sh "docker build ... -t image:tag context/"

After push, inspect the manifest:

docker manifest inspect <image:tag> | grep architecture
# Must contain "amd64"

Failure mode: arm64 image -> GKE ImagePullBackOff (9h outage, Issue #47), Cloud Run deploy rejection. </important>

<important if="auditing Docker build args or cloudbuild.yaml for http:// URLs">
### 2. Build Arg Audit

Reject any http:// URL in --build-arg or cloudbuild.yaml.

bash ${CLAUDE_SKILL_DIR}/scripts/pre-deploy-check.sh "docker build --build-arg URL=..."

Failure mode: http:// baked into SPA bundle -> browser blocks as Mixed Content -> feature fully broken (Issue #40). </important>

<important if="building Vite SPA for GCP deployment with VAD/ONNX/WASM assets">
### 3. SPA Build Checks (Vite Only)

Check	Why
`vite-plugin-static-copy` enabled	VAD/ONNX assets missing -> 404 (Issue #45)
`onnxWASMBasePath: '/'` set	WASM lookup fails at `/assets/`
`VITE_MILAOS_SESSION_WS_URL` provided	Falls back to `localhost:8080`
`VITE_MILAOS_STT_HTTP_URL` NOT provided	Mixed Content source

</important>

<important if="configuring nginx.conf MIME types or fixing .mjs/.wasm/.onnx 404 errors">
### 4. nginx MIME Types

# CORRECT: location-level default_type
location ~* \.mjs$ { default_type application/javascript; }
location ~* \.wasm$ { default_type application/wasm; }
location ~* \.onnx$ { default_type application/octet-stream; }

# WRONG: server-level types {} destroys entire MIME table
server { types { } }  # NEVER

</important>

<important if="verifying a Cloud Run SPA deployment for Mixed Content or missing assets">
## Post-Deploy Verification

Cloud Run (SPA)

./scripts/verify-spa-deploy.sh --service <service-name>

HTTP 200 response
No http:// in bundle: curl -sL <url>/assets/*.js | grep -oE 'http://[a-zA-Z0-9._-]+' | sort -u
VAD assets return 200: /ort-wasm-simd-threaded.mjs, /silero_vad_legacy.onnx, /vad.worklet.bundle.min.js
WebSocket/API connection succeeds</important>

<important if="verifying a Cloud Run API deployment or checking healthz endpoint">
### Cloud Run (API)
```bash
curl -s -o /dev/null -w "%{http_code}" https://<api-url>/v1/healthz  # Must be 200
gcloud run services logs read <service> --region <region> --limit 20  # No errors
```
</important>

<important if="verifying a GKE pod deployment or checking pod status">
### GKE (Pod/Service)
```bash
kubectl get pods -n <ns> -l app=<app> -o wide          # Must be Running
kubectl logs -n <ns> -l app=<app> --tail=20             # No panic/SIGSEGV
curl -s -w "%{http_code}" http://<lb-ip>:<port>/healthz # Reachable
```
</important>

<important if="diagnosing GCP deploy errors like ImagePullBackOff, Mixed Content, WASM 404, or push 403">
## Error Handling

Error	Cause	Fix
`ImagePullBackOff`	arm64 image on amd64 node	Rebuild with `--platform linux/amd64`
Mixed Content block	`http://` in build args	Remove `http://` args, use HTTPS only
WASM/ONNX 404	Missing static copy plugin	Enable `vite-plugin-static-copy`
`.mjs` not loading	Wrong MIME type	Use location-level `default_type`
Push 403	Wrong project	Use `milaos-realtime-avatar-spec`

</important>

Prohibited Patterns

NEVER  docker build without --platform linux/amd64 (Apple Silicon)
NEVER  http:// in VITE_* build args
NEVER  server-level types {} in nginx.conf
NEVER  VRMUtils.combineSkeletons()
NEVER  deploy without docker manifest inspect
NEVER  report deploy complete without running verification
NEVER  guess project ID (confirm: milaos-realtime-avatar-spec)

Known Traps

Full details in references/known-traps.md.

Skill Integration

Skill	When
webapp-testing	Post-deploy browser smoke test
security-review	Dockerfile/K8s manifest/nginx.conf changes
code-reviewer	cloudbuild.yaml/Dockerfile changes
build-fix	Post-deploy build errors

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

It worked
Partly
It didn't

What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free