Skills de fundamentos: autenticación y onboarding en Google Cloud

El README de google/skills abre su índice con una sección llamada Getting started with Google Cloud. Tiene exactamente tres entradas, y las tres viven en skills/cloud/:

Título en el README	Directorio	metadata.category
Authenticating to Google Cloud	skills/cloud/google-cloud-recipe-auth/	GettingStarted
Google Cloud Recipe: Foundation Builder	skills/cloud/google-cloud-recipe-foundation-builder/	GettingStarted
Onboarding to Google Cloud	skills/cloud/google-cloud-recipe-onboarding/	GettingStarted

Son el punto de entrada práctico del catálogo: lo primero que un agente carga cuando alguien dice “quiero empezar con Google Cloud” y no tiene ni proyecto, ni billing, ni idea de cómo se autentica una client library. Este capítulo abre los tres SKILL.md reales y los recorre paso a paso.

Recuerda el aviso del propio repositorio, en la línea 9 del README:

This repository is under active development.

Nada de lo que sigue es una API estable. Es una fotografía del catálogo tal como está publicado.

Tres skills, tres problemas distintos

Es tentador pensar que los tres hacen “lo mismo pero más grande”. No es así. Se distinguen por escala de la identidad y por naturaleza del contenido:

• google-cloud-recipe-onboarding es un runbook ejecutable para un desarrollador solo. Toca la CLI, crea proyecto, vincula billing.
• google-cloud-recipe-auth no ejecuta nada. Es un árbol de decisión conceptual sobre identidades y credenciales.
• google-cloud-recipe-foundation-builder es un runbook ejecutable a nivel de organización: despliega una landing zone completa. Está marcado en preview.

flowchart TD
  A[El usuario quiere empezar con Google Cloud] --> B{Que escala tiene}
  B -->|Un desarrollador, una cuenta personal| C[google-cloud-recipe-onboarding]
  B -->|Una organizacion corporativa completa| D[google-cloud-recipe-foundation-builder]
  B -->|Duda sobre credenciales o identidades| E[google-cloud-recipe-auth]
  C --> F[Proyecto activo mas billing vinculado]
  D --> G[Landing zone con 17 politicas y 4 carpetas]
  E --> H[Recomendacion de mecanismo de autenticacion]

Los tamaños confirman el reparto: google-cloud-recipe-auth son 260 líneas de SKILL.md sin más archivos, google-cloud-recipe-onboarding son 228 también sin más archivos, y google-cloud-recipe-foundation-builder son 355 líneas más un directorio references/ con 3 archivos.

Dos de los tres son monolíticos: todo cabe en el cuerpo del SKILL.md sin necesidad de progressive disclosure hacia archivos auxiliares. Solo el más pesado delega en references/. Si vienes del curso hermano de Agent Skills, aquí ves aplicado el criterio de dividir solo cuando el volumen lo exige.

google-cloud-recipe-onboarding: el camino feliz de un desarrollador solo

Qué problema resuelve y cuándo se dispara

Su description en el frontmatter incluye disparo y anti-disparos explícitos:

description: >-
  Guides a developer's first steps on Google Cloud, covering account creation,
  billing setup, project management, and deploying a first resource.
  Use when a new developer wants to initialize their first Google Cloud project,
  configure billing, and verify deployment.
  Don't use for enterprise organization setup (use Google Cloud Setup guided flow for that instead).
  Don't use for complex multi-project architectures.

El cuerpo lo define como “a streamlined, non-interactive ‘happy path’ for a singleton developer”. Traducción operativa: una persona, una cuenta, un proyecto, un billing account. Cualquier cosa que huela a organización corporativa se deriva a otro sitio.

Las cuatro reglas de comportamiento

Antes del procedimiento, un bloque > [!IMPORTANT] fija cuatro reglas para agentes autónomos. Son la parte más interesante del skill porque no hablan de Google Cloud, hablan de cómo debe comportarse el agente:

1. Check-Before-Mutate Audits: auditar el estado en silencio antes de proponer o ejecutar cualquier cambio de proyecto o billing.
2. Single-Question Policy: preguntar al usuario exactamente un parámetro o confirmación por turno.
3. Non-Interactive Output: añadir --quiet y --format="json" a todos los comandos de mutación “to guarantee deterministic, machine-parseable outputs and prevent terminal hangs”.
4. First Turn Interaction Rules: en el turno que dispara el skill, incluir un preámbulo que oriente a crear la cuenta en https://console.cloud.google.com/ y a correr gcloud auth login, hacer las auditorías en silencio, no mostrar todavía la tabla de parámetros ni pedir consentimiento final, y hacer una sola pregunta inicial, por ejemplo “Would you like to reuse an existing active project, or create a brand new one?”.

La regla 4 trae una excepción textual: si el prompt inicial ya dice "I approve the onboarding configuration", "Let's proceed with onboarding" o pide un plan dry-run, el agente se salta el preámbulo y va directo al paso solicitado.

La regla 3 merece atención de quien escribe skills. --quiet no está ahí por estética: sin él, un gcloud projects create puede quedarse esperando una confirmación interactiva y colgar la sesión del agente. Es una defensa contra el bloqueo del proceso.

El procedimiento, sección por sección

flowchart TD
  S1[Seccion 1 verificar tooling local] --> Q1{which gcloud devuelve ruta}
  Q1 -->|No| HALT[Detener y derivar al skill gcloud]
  Q1 -->|Si| S2[Seccion 2 autenticar y enrutar sesion]
  S2 --> Q2{gcloud organizations list}
  Q2 -->|Hay directoryCustomerId| HALT2[Detener y derivar a Cloud Setup guided flow]
  Q2 -->|Lista vacia o SOO personal| S3[Seccion 3 elegir o crear proyecto]
  S3 --> S4[Seccion 4 verificar y vincular billing]
  S4 --> S5[Seccion 5 encadenar a skills de workload]

Sección 1 — Verify Host Tooling Setup. Auditoría silenciosa del host:

which gcloud
gcloud auth list --format="json"

Si which gcloud devuelve una ruta válida, salta directo a la Sección 2. Si el binario falta, el skill ordena detener la ejecución y derivar al skill gcloud del propio catálogo (skills/cloud/gcloud/) o a la guía oficial de instalación del SDK.

Sección 2 — Authenticate and Route Session.

gcloud auth login
gcloud config get-value account --format="json"
gcloud organizations list --format="json"

El tercer comando es lo que el skill llama Programmatic Enterprise Routing Guardrail, y su criterio de bifurcación es literal:

• Enterprise Organization, halt execution: si algún nodo del JSON trae owner.directoryCustomerId presente —lo que confirma una organización de Google Workspace o Cloud Identity con dominio verificado—, o si el prompt menciona landing zones corporativas o estructuras multi-tenant, hay que detener el skill y derivar al Google Cloud Setup guided flow.
• Personal Account o Free Trial SOO, proceed: si la lista es [], o si contiene una Self-Owned Organization donde owner.directoryCustomerId está ausente y displayName no es un dominio verificado, se continúa.

Ese detalle —que una cuenta de Free Trial recibe automáticamente una Self-Owned Organization y por eso organizations list no viene vacío— es exactamente el tipo de conocimiento que justifica que exista un skill en vez de un párrafo de documentación.

Sección 3 — Select or Instantiate Your Google Cloud Project.

gcloud projects list --filter="lifecycleState=ACTIVE" --limit=20 --format="json"
gcloud config set project {PROJECT_ID} --quiet

El --limit=20 está justificado en el texto “to prevent context window overflow”: el skill protege la ventana de contexto del agente. La preferencia declarada es reutilizar un proyecto existente, porque el Free Trial ya crea uno llamado “My First Project”.

Si hay que crear uno nuevo, entra el Structured Confirmation & Consent Gate, marcado como obligatorio. El agente debe presentar una tabla markdown con estos cuatro parámetros:

Parameter	Value
Target Project ID	{PROJECT_ID}
Target Project Name	{PROJECT_NAME}
Active Identity Account	{ACCOUNT}
Target Billing Account ID	{BILLING_ACCOUNT_ID}

Y formular la pregunta de consentimiento con este texto exacto:

"I am ready to initialize your Google Cloud project and link billing. Do you want me to proceed?"

La restricción que sigue está en mayúsculas en el original:

CRITICAL: The agent MUST NOT execute any gcloud projects create or billing link commands during this turn.

El agente muestra la tabla, hace la pregunta y se detiene. Nada de mutar recursos en el mismo turno en que se pide permiso.

Hay además una recuperación específica, Project ID Collision Suffix Recovery: si gcloud projects create falla con PROJECT_ID_COLLISION o ALREADY_EXISTS porque el ID ya está tomado a nivel global, el agente anexa un sufijo aleatorio de 4 dígitos —my-project pasa a my-project-8472—, propone el nuevo ID y vuelve a pedir consentimiento antes de reintentar.

Con el consentimiento confirmado:

gcloud projects create {PROJECT_ID} --name="{PROJECT_NAME}" --quiet --format="json"
gcloud config set project {PROJECT_ID} --quiet

Sección 4 — Verify and Link Billing. Tres comandos, con un cortocircuito:

gcloud billing projects describe {PROJECT_ID} --format="json"
gcloud billing accounts list --format="json"
gcloud billing projects link {PROJECT_ID} --billing-account={BILLING_ACCOUNT_ID} --format="json"

Si el primero devuelve "billingEnabled": true, el skill ordena saltar directamente a la Sección 5 sin tocar nada más.

Sección 5 — Skill Chaining. El onboarding no pretende terminar en sí mismo. Encadena hacia dos lados:

1. Control de gasto: deriva a la guía oficial Disable Billing Usage with Notifications, que apaga billing automáticamente cuando el costo supera el presupuesto.
2. Workloads: encadena a un skill especializado del catálogo, con cloud-run-basics y bigquery-basics como ejemplos —ambos existen como directorios en skills/cloud/—. Y aclara la división de responsabilidades: “those downstream specialized skills are individually responsible for dynamically enabling their own required service APIs (e.g., run.googleapis.com) inline during execution”. El onboarding no habilita APIs de producto; eso le toca a cada skill de destino.

La validación final

El skill cierra con cuatro comandos de diagnóstico que confirman el estado alcanzado:

which gcloud
gcloud config get-value account
gcloud projects describe {PROJECT_ID} --format="json"
gcloud billing projects describe {PROJECT_ID} --format="json"

El último se valida buscando "billingEnabled": true en el JSON. Es una condición binaria y verificable, no un “revisa que todo esté bien”.

Cómo se ve en una sesión real

sequenceDiagram
  participant U as Usuario
  participant A as Agente
  participant G as gcloud CLI
  U->>A: Quiero empezar con Google Cloud
  A->>G: which gcloud
  A->>G: gcloud auth list --format json
  A->>G: gcloud projects list --filter lifecycleState ACTIVE --limit 20
  A->>U: Preambulo mas una sola pregunta reusar o crear proyecto
  U->>A: Crear uno nuevo llamado demo-siemprelisto
  A->>U: Tabla de parametros mas pregunta de consentimiento exacta
  U->>A: Si, procede
  A->>G: gcloud projects create demo-siemprelisto --quiet --format json
  A->>G: gcloud billing projects link demo-siemprelisto
  A->>U: Validacion mas propuesta de encadenar a cloud-run-basics

Fíjate en el ritmo: tres comandos de lectura, una pregunta, una tabla, un permiso, y recién ahí las mutaciones. Ese ritmo no lo inventa el modelo, lo impone el SKILL.md.

google-cloud-recipe-auth: un árbol de decisión, no un runbook

Qué problema resuelve

Este skill es distinto en naturaleza a los otros dos: no ejecuta un procedimiento. Es conocimiento estructurado para responder bien a “¿cómo me autentico?”. Su primera frase separa los dos conceptos que la gente mezcla:

[Authentication] is the process of proving who you are. In Google Cloud, you represent a Principal. This is the first step before [Authorization] (determining what you can do).

Su description no trae anti-disparos; se limita a declarar la cobertura: usuarios humanos, identidades de servicio, Application Default Credentials y buenas prácticas de acceso seguro.

Las cuatro preguntas que ordenan todo

Antes de proponer nada, el skill obliga al agente a aclarar cuatro cosas:

1. ¿Quién o qué se autentica? Un desarrollador humano, un script local o una aplicación en producción.
2. ¿Dónde corre el código? Laptop, Compute Engine, GKE, Cloud Run u otra nube como AWS o Azure.
3. ¿Cuál es el destino? Una API de Google Cloud como Storage o BigQuery, o una aplicación propia.
4. ¿Se usa una client library de alto nivel? Las librerías de Python, Go o Node.js suelen resolver ADC automáticamente.

Con esas cuatro respuestas, el árbol se colapsa a una única recomendación:

flowchart TD
  Q1{Quien se autentica} -->|Humano desarrollador| H{Donde corre}
  Q1 -->|Servicio en produccion| S{Donde corre}
  Q1 -->|Usuario final de una app| E{Que necesita}
  H -->|Laptop, comandos CLI| H1[gcloud auth login]
  H -->|Laptop, client libraries| H2[gcloud auth application-default login]
  H -->|Necesita permisos de una service account| H3[Service Account Impersonation]
  S -->|Compute Engine o Cloud Run| S1[Adjuntar service account al recurso]
  S -->|GKE| S2[Workload Identity Federation for GKE]
  S -->|AWS, Azure o on-prem| S3[Workload Identity Federation]
  E -->|Proteger una app interna sin VPN| E1[Identity-Aware Proxy]
  E -->|Login de clientes dentro de la app| E2[Identity Platform]

Autenticación humana

El skill separa tipos de identidad de métodos de acceso.

Tipos de identidad para la fuerza de trabajo interna:

• Google-Managed Accounts: cuentas creadas con Cloud Identity o Google Workspace, cuyo ciclo de vida controla la organización.
• Federation using Cloud Identity or Google Workspace: los usuarios se autentican contra un IdP externo, pero hay que sincronizar las cuentas con herramientas como Google Cloud Directory Sync, Active Directory o Microsoft Entra ID.
• Workforce Identity Federation: usa el IdP externo directamente con IAM, sin sincronizar identidades. El texto lo llama “syncless, attribute-based single sign-on”.

Métodos de acceso para desarrolladores, con la distinción que el skill remarca porque se confunde a diario: gcloud auth login autentica la CLI y guarda un refresh token OAuth 2.0 local, mientras que gcloud auth application-default login autentica las client libraries creando un archivo JSON de ADC. “This is different from CLI auth”, dice el original sobre el segundo. Un gcloud compute instances list funciona con el primero; tu script de Python con storage.Client() necesita el segundo.

Y la recomendación de seguridad más fuerte del skill, citada textual:

For security reasons, developers should avoid downloading Service Account keys entirely. Instead, they should authenticate as humans (gcloud auth login) and use Service Account Impersonation to run CLI commands or generate short-lived credentials.

Para usuarios finales que no son desarrolladores, dos productos distintos: Identity-Aware Proxy, que intercepta las peticiones web y verifica identidad antes de llegar a la aplicación —el skill lo describe como forma de proteger apps internas sin VPN—, e Identity Platform, la solución CIAM para meter login de email, teléfono o redes sociales dentro del código de tu app.

Autenticación servicio a servicio

Primero, una distinción de vocabulario: una Service Account es una identidad no humana con su propio email; un Service Agent es una service account gestionada por Google que permite a un servicio como Pub/Sub acceder a tus recursos en tu nombre.

La buena práctica central es adjuntar la service account al recurso en lugar de usar claves JSON, que el skill califica sin rodeos de “dangerous JSON files”. El entorno del recurso entrega entonces un token de corta vida a través del metadata server local: en Compute Engine se asigna al crear la VM, en Cloud Run se asigna en la configuración del servicio.

Los casos especiales que documenta:

• GKE: Workload Identity Federation for GKE, que mapea identidades de Kubernetes a principals de IAM.
• Cargas externas: para código fuera de Google Cloud en AWS, Azure u on-prem, Workload Identity Federation intercambia un token externo por un access token de corta vida. No claves.
• API Keys: solo para datos públicos o accesos simplificados como Vertex AI Express Mode. Deben restringirse a APIs y proyectos concretos, y guardarse en Secret Manager.
• OAuth 2.0 Access Scopes: mecanismo legado en VMs y node pools. El apunte de troubleshooting vale su peso: “If a VM’s scope is restricted, the attached service account will fail to make API calls even if it has the correct IAM permissions. Check this first if attached service accounts are failing unexpectedly.”
• Short-Lived Credentials: la IAM Service Account Credentials API genera dinámicamente access tokens, OIDC ID tokens y JWTs autofirmados, eliminando las credenciales estáticas.

Autorización y ejemplos canónicos

En autorización el skill es breve: una Allow Policy vincula un Principal con un Role sobre un Resource; los roles predefinidos como roles/storage.objectViewer o roles/bigquery.dataEditor se usan siempre primero —“Always try to use these first”— y los custom roles solo cuando los predefinidos resulten demasiado amplios.

Cierra con tres ejemplos completos:

1. Human-to-Service, desarrollo local en Python.

gcloud auth application-default login

Luego se concede roles/storage.objectViewer al email del desarrollador sobre el bucket, y el código usa storage.Client() sin credenciales explícitas. El skill documenta el orden de búsqueda de ADC: primero la variable de entorno GOOGLE_APPLICATION_CREDENTIALS, después el JSON local de gcloud, y por último el metadata server de la service account adjunta.

2. Service-to-Service, Cloud Run hacia Cloud SQL. Se adjunta una service account custom al servicio de Cloud Run, se le concede roles/cloudsql.client en el proyecto, y el entorno entrega el token al driver de conexión automáticamente.

3. Llamar a una aplicación propia con OIDC. Cuando un servicio llama a un Cloud Run privado, el llamante genera un OIDC ID Token firmado por Google y lo envía en la cabecera:

Authorization: Bearer <TOKEN>

El checklist de diagnóstico

Los siete ítems de validación no son pasos a ejecutar, son preguntas de diagnóstico que el agente se hace sobre la situación del usuario:

• ¿Corre código en local? Sugerir gcloud auth application-default login o impersonación.
• ¿Intenta usar claves de service account en local? “Strongly discourage this” y recomendar impersonación.
• ¿Está en producción? Recomendar una service account custom de mínimo privilegio, nunca claves.
• ¿Depende de la Compute Engine Default Service Account? Recomendar crear una custom.
• ¿Corre en otra nube? Recomendar Workload Identity Federation.
• ¿Llama a una app propia? Recomendar OIDC ID Tokens.
• ¿Restringió sus API keys?

Es un patrón reutilizable para tus propios skills de consultoría: convertir la sección de validación en una lista de preguntas de auditoría en vez de una lista de comandos.

google-cloud-recipe-foundation-builder: la landing zone completa

Estado y alcance

Este skill abre con un aviso que conviene no ocultar:

[!WARNING] This skill is currently in a preview state. It will deploy a secure foundation, but does not have all advanced features.

Y su description trae el anti-disparo que lo separa del onboarding:

Don’t use for individual project onboarding (use google-cloud-recipe-onboarding or product-specific skills instead).

Es el único de los tres con references/:

skills/cloud/google-cloud-recipe-foundation-builder/
├── SKILL.md
└── references/
    ├── admin-iam.md
    ├── logging-monitoring.md
    └── org-policies.md

Qué provisiona

Cuatro bloques declarados en el Overview:

• Security Guardrails: 17 Organization Policies base, 13 booleanas y 4 de tipo lista.
• Resource Hierarchy: 4 carpetas —Common, Production, Non-Production, Development— con sus proyectos correspondientes, usando los prefijos logging-, prod-, non-prod- y dev- seguidos de un sufijo compartido.
• Billing & API Enablement: vinculación de los 4 proyectos al billing account y habilitación de servicios.
• Centralized Logging & Monitoring: log bucket global centralizado con retención de 30 días, sink de audit logs a nivel de organización y metrics scope multiproyecto.

Las cuatro preguntas obligatorias

Antes de ejecutar, el agente debe recolectar:

1. Organization ID, listando con gcloud organizations list.
2. Billing Account ID, listando solo las cuentas abiertas con gcloud billing accounts list --filter=open=true.
3. Project ID Suffix: por defecto, prefijo más una cadena aleatoria compartida de 8 caracteres, por ejemplo prod-ab12cd34.
4. Log Bucket Region: por defecto global.

Las cinco fases

flowchart TD
  P1[Fase 1 confirmacion previa] --> GATE{Aprobacion explicita del usuario}
  GATE -->|No| ABORT[Abortar la operacion]
  GATE -->|Si| P3[Fase 3 aplicar 17 org policies]
  P3 --> P4[Fase 4 jerarquia de carpetas y proyectos]
  P4 --> P5[Fase 5 logging y monitoring centralizados]
  P3 -.Permission Denied.-> P2[Fase 2 remediacion perezosa de roles]
  P4 -.Permission Denied.-> P2
  P5 -.Permission Denied.-> P2
  P2 -->|Grant exitoso| RETRY[Reintentar el comando fallido]
  P2 -->|Grant fallido| STOP[Detener y pedir intervencion del administrador]

Fase 1 — Pre-flight Confirmation. Se identifica la organización y se derivan dos valores de su metadata:

gcloud organizations list
gcloud organizations describe [ORGANIZATION_ID]

De la salida se calcula el Domain Name a partir de displayName —por ejemplo my-business.com— y el Customer ID a partir de owner.directoryCustomerId —por ejemplo C01234567—. Con eso se presenta el “Proposed Foundation Deployment Summary” y se pausa la ejecución esperando aprobación explícita. Si el usuario declina, se aborta.

Fase 2 — Error Recovery & Lazy Role Remediation Strategy. Es la decisión de diseño más llamativa del skill. En lugar de comprobar permisos por adelantado —algo que, según el texto, “require a quota project”—, el agente ejecuta cada comando, captura los errores Permission Denied y se autoremedia concediéndose el grupo administrativo completo de roles antes de reintentar.

El skill obliga además a explicar esta estrategia si el usuario pregunta por prerrequisitos: confirmar que ejecutará directamente, que capturará los errores, que intentará autoremediarse con gcloud organizations add-iam-policy-binding o gcloud billing accounts add-iam-policy-binding, que enumerará los grupos administrativos que va a conceder, y que detendrá la ejecución pidiendo intervención manual del administrador si la concesión falla.

Los grupos viven en references/admin-iam.md, que documenta 23 roles repartidos en 4 grupos:

Grupo administrativo	Roles	Ejemplos de roles
Organization Admin Group	9	roles/resourcemanager.organizationAdmin, roles/orgpolicy.policyAdmin, roles/billing.user
Billing Admin Group	3	roles/billing.admin, roles/billing.creator, roles/resourcemanager.organizationViewer
Logging/Monitoring Admin Group	2	roles/logging.admin, roles/monitoring.admin
Security Admin Group	9	roles/iam.securityAdmin, roles/resourcemanager.folderIamAdmin, roles/logging.privateLogViewer

El mapeo fase a grupo es explícito: si falla gcloud org-policies set-policy o gcloud resource-manager folders create o gcloud projects create, se concede el Organization Admin Group completo a nivel de organización; si falla gcloud billing projects link, el Billing Admin Group a nivel de billing account; si falla gcloud logging sinks create a nivel de organización, el Logging/Monitoring Admin Group más el Security Admin Group.

La referencia incluso trae los bucles listos para pegar:

for role in roles/logging.admin roles/monitoring.admin; do
    gcloud organizations add-iam-policy-binding [ORGANIZATION_ID] \
        --member="user:[YOUR_ACCOUNT_EMAIL]" \
        --role="$role"
done

Fase 3 — Security Guardrails. Se generan los YAML de las 17 políticas con las plantillas de references/org-policies.md y se aplican secuencialmente:

gcloud org-policies set-policy [POLICY_FILE_NAME].yaml

Las booleanas comparten una única plantilla:

name: organizations/[ORGANIZATION_ID]/policies/[CONSTRAINT_NAME]
spec:
  rules:
  - enforce: true

Entre esas 13 restricciones booleanas están iam.disableServiceAccountKeyCreation, iam.disableServiceAccountKeyUpload, iam.automaticIamGrantsForDefaultServiceAccounts, storage.publicAccessPrevention, storage.uniformBucketLevelAccess, sql.restrictPublicIp, sql.restrictAuthorizedNetworks, compute.requireOsLogin, compute.disableSerialPortAccess, compute.disableNestedVirtualization y compute.disableVpcExternalIpv6. Nota la coherencia con el skill de auth: las dos primeras hacen imposible el patrón de claves JSON que google-cloud-recipe-auth desaconseja en prosa.

Las 4 de tipo lista llevan plantillas propias. La de IPs externas es un denyAll:

name: organizations/[ORGANIZATION_ID]/policies/compute.vmExternalIpAccess
spec:
  rules:
  - denyAll: true

Y la más delicada, iam.allowedPolicyMemberDomains, restringe qué dominios pueden aparecer en políticas IAM al customer ID de tu organización. De ahí este aviso, que aparece dos veces en el skill:

[!CAUTION] Applying iam.allowedPolicyMemberDomains first can lock out the deployment identity if it resides in an unallowed domain.

Aplicar esa política antes de tiempo puede dejar fuera a la propia identidad que está desplegando la fundación.

Fase 4 — Resource Hierarchy. Para cada carpeta, primero se comprueba y solo después se crea:

gcloud resource-manager folders list --organization=[ORGANIZATION_ID] --filter="display_name=Common"
gcloud resource-manager folders create --display-name="Common" --organization=[ORGANIZATION_ID]

Para cada proyecto, la misma lógica de idempotencia y una tríada de comandos:

gcloud projects list --filter="parent.id=[PRODUCTION_FOLDER_ID] AND parent.type=folder AND name=production"
gcloud projects create prod-[SUFFIX] --name="production" --folder=[PRODUCTION_FOLDER_ID]
gcloud billing projects link prod-[SUFFIX] --billing-account=[BILLING_ACCOUNT_ID]
gcloud services enable compute.googleapis.com run.googleapis.com container.googleapis.com aiplatform.googleapis.com cloudkms.googleapis.com --project=prod-[SUFFIX]

Los proyectos prod-, non-prod- y dev- habilitan la misma lista larga de 17 APIs —de compute y run a aiplatform, cloudaicompanion, discoveryengine, cloudkms y cloudresourcemanager—; el proyecto logging- habilita solo tres: compute.googleapis.com, logging.googleapis.com y monitoring.googleapis.com.

Hay una nota que rara vez se ve en documentación de infraestructura, dirigida específicamente a agentes:

Agentic Parallelism Option: While the manual runbook enforces sequential project execution to avoid terminal race conditions, an AI agent with multi-agent orchestration capability may optionally spawn subagents to provision the 4 projects in parallel once folder IDs are resolved.

El runbook es secuencial por seguridad del terminal, pero el skill autoriza explícitamente a paralelizar con subagentes una vez resueltos los IDs de carpeta.

Fase 5 — Centralized Logging and Monitoring. Delegada por completo a references/logging-monitoring.md, que trae cuatro pasos:

gcloud logging buckets create [ORG_NAME]-logging \
    --project=logging-[SUFFIX] \
    --location=global \
    --retention-days=30 \
    --description="Central logging and monitoring bucket"

Después el sink de organización, cuyo nombre sigue el formato [ORGANIZATION_ID]-logbucketsink-[RANDOM_4_HEX] y cuyo filtro enruta los cuatro tipos de audit log: activity, system_event, data_access y access_transparency. La referencia insiste en guardar la writerIdentity que devuelve el comando, porque el paso siguiente le concede roles/logging.bucketWriter sobre el proyecto de logging. Por último, se enlazan dev-, non-prod- y prod- al metrics scope central con gcloud beta monitoring metrics-scopes create, usando primero un describe para no reintentar enlaces existentes.

El checklist de validación

Seis verificaciones con checkbox, todas comprobables por comando: las 17 políticas listadas con gcloud org-policies list, las 4 carpetas presentes bajo la raíz, los 4 proyectos vinculados según gcloud billing projects list, el bucket [ORG_NAME]-logging en global con retención de exactamente 30 días, el sink de organización enrutando audit logs con su writerIdentity, y el metrics scope mostrando dev, non-prod y prod en el proyecto logging.

Cómo encajan los tres en una sesión real

El recorrido natural para alguien que parte de cero con un agente:

flowchart LR
  A[Cuenta y CLI] --> B[google-cloud-recipe-onboarding]
  B --> C{Voy a escribir codigo que llame APIs}
  C -->|Si| D[google-cloud-recipe-auth]
  C -->|No aun| E[Skill de workload]
  D --> E
  E --> F[cloud-run-basics o bigquery-basics]
  G[Necesito estructura corporativa] --> H[google-cloud-recipe-foundation-builder]

Observa que google-cloud-recipe-auth no está en la ruta secuencial: es transversal. Se dispara cuando aparece la pregunta, en cualquier punto del recorrido, y por eso su SKILL.md no tiene fases ni orden de ejecución.

Y observa la asimetría de disparo: onboarding y foundation builder son mutuamente excluyentes por diseño. Cada uno lleva en su description el anti-disparo que apunta al otro. Ese cruce de anti-disparos es el mecanismo que Google usa para que el agente no confunda “un desarrollador con una tarjeta de crédito” con “una empresa con dominio verificado”.

Qué copiar de estos tres skills

Si estás escribiendo tus propios skills, estos tres regalan patrones concretos:

• Anti-disparos cruzados en la description. No basta con decir cuándo usar el skill; hay que decir cuándo no, y nombrar el skill alternativo. El formato del campo está en el curso de Agent Skills y su disección en el capítulo 4.
• Consent gate con texto exacto. Fijar la pregunta literal y prohibir mutar en el mismo turno convierte una recomendación blanda en una regla verificable.
• Flags anti-bloqueo. --quiet y --format="json" en toda mutación evitan que un prompt interactivo cuelgue la sesión del agente.
• Límites contra el desbordamiento de contexto. Ese --limit=20 con su justificación escrita es un recordatorio de que la ventana de contexto es un recurso del skill, no del modelo.
• Recuperación de errores como estrategia declarada. La remediación perezosa del foundation builder documenta qué hacer al fallar, hasta dónde llegar y cuándo detenerse.
• Idempotencia por comprobación previa. Listar antes de crear, en carpetas y proyectos, hace el runbook reejecutable.
• Validación como comandos, no como adjetivos. "billingEnabled": true o “retención de exactamente 30 días” se verifican; “todo correcto” no.

Cuando quieras distribuir skills así, el empaquetado está cubierto en Agent Plugins Spec, y cómo lo hace Google concretamente lo verás en el capítulo 11.

Más allá de este catálogo

Los tres skills de fundamentos cubren Google Cloud, pero el README enlaza además otros repositorios de skills de Google que viven fuera de google/skills:

• Flutter Skills: https://github.com/flutter/skills
• Dart Skills: https://github.com/dart-lang/skills
• Advanced Google Cloud Storage Skills: https://github.com/gemini-cli-extensions/google-cloud-storage
• Agent Development Kit Skills: https://github.com/google/agents-cli
• Firestore Skills: https://github.com/firebase/agent-skills/tree/main/skills/firebase-firestore
• Genkit Skills: https://github.com/genkit-ai/skills

Para instalar el catálogo principal, los comandos son los del README, sin variaciones:

# skills.sh
npx skills add google/skills

# Claude Code
claude plugin marketplace add google/skills
claude plugin install <plugin>@google-plugins

# Codex
codex plugin marketplace add google/skills

# Antigravity CLI
agy plugin install https://github.com/google/skills/<plugin-path>

El detalle de cada uno está en el capítulo 2.

Resumen

La sección Getting started with Google Cloud tiene tres skills, todos con metadata.category: GettingStarted y todos en skills/cloud/:

• google-cloud-recipe-onboarding es el camino feliz de un desarrollador solo: verifica gcloud, autentica, aplica un guardrail que detecta organizaciones corporativas por owner.directoryCustomerId, selecciona o crea un proyecto detrás de un consent gate obligatorio, vincula billing y encadena a skills de workload. Sus cuatro reglas —Check-Before-Mutate, Single-Question, Non-Interactive Output y First Turn— gobiernan el comportamiento del agente más que la infraestructura.
• google-cloud-recipe-auth no ejecuta nada: es un árbol de decisión sobre identidades. Separa gcloud auth login de gcloud auth application-default login, prefiere impersonación y service accounts adjuntas sobre claves JSON, y cierra con siete preguntas de diagnóstico en vez de una lista de comandos.
• google-cloud-recipe-foundation-builder, en preview, despliega una landing zone: 17 organization policies, 4 carpetas, 4 proyectos con billing y APIs, log bucket con 30 días de retención, sink de organización y metrics scope multiproyecto. Es el único con references/, con tres archivos: admin-iam.md, org-policies.md y logging-monitoring.md. Su estrategia de remediación perezosa de roles es su decisión de diseño más característica.

Los tres son runbooks de operador escritos para que los ejecute un agente, con consentimiento explícito antes de cada mutación y validación comprobable al final. En el próximo capítulo subimos un nivel: skills que no configuran una cuenta sino que diseñan y despliegan arquitecturas completas de varios productos.

Siguiente: Skills de soluciones multi-producto: arquitecturas completas