Anatomía de un skill de Google: disección de casos reales

En el capítulo 3 recorriste el catálogo desde arriba: tres áreas, 103 skills, 17 categorías de frontmatter. Ahora bajamos al nivel del archivo. Este capítulo abre cuatro skills reales de complejidad creciente y los disecciona completos: árbol de directorios, frontmatter íntegro, esqueleto de encabezados, uso de references/, scripts/ y assets/. Al final extraemos los patrones de escritura que Google repite en todo el catálogo, con conteos verificados, y los contrastamos con las buenas prácticas del estándar que viste en el curso hermano Agent Skills.

Recordatorio: el repositorio está marcado como under active development en su README. Los números de este capítulo describen el estado del clon analizado, no un catálogo congelado.

El molde: qué hay dentro de una carpeta de skill

Un skill del catálogo es un directorio con un archivo obligatorio y hasta tres subdirectorios opcionales.

skills/<area>/<nombre-del-skill>/
├── SKILL.md          # obligatorio, siempre presente, siempre uno solo
├── references/       # opcional: documentación que se carga bajo demanda
├── scripts/          # opcional: ejecutables que el agente invoca
└── assets/           # opcional: plantillas listas para copiar o aplicar

No hay README.md por skill, no hay manifest.json, no hay templates/ ni examples/. El nombre del directorio coincide siempre con el campo name del frontmatter: cero discrepancias en los 103 skills. Y la distribución real de subdirectorios y tamaños dice mucho sobre cómo escribe Google:

Métrica sobre los 103 skills	Valor
Solo SKILL.md, sin subdirectorios	41 skills
Con references/	55 skills
Con assets/	17 skills
Con scripts/	12 skills
Líneas del SKILL.md: mínimo / mediana / media / máximo	30 / 193 / 216 / 726
SKILL.md que superan las 500 líneas	3 skills

Cuatro de cada diez skills son un único archivo Markdown: la complejidad no es el estado por defecto, es la excepción justificada. Y los tres que se pasan del umbral recomendado por el estándar son agent-platform-tuning con 531 líneas, gemini-interactions-api con 591 y agent-platform-inference con 726. El mecanismo que mantiene esa mediana baja es la carga progresiva:

flowchart TD
  A[Frontmatter: name + description] -->|siempre en contexto| B[El agente decide si el skill aplica]
  B -->|dispara| C[Cuerpo del SKILL.md<br/>mediana 193 lineas]
  C -->|solo si hace falta| D[references/archivo.md<br/>el agente abre uno, no todos]
  C -->|solo si ejecuta| E[scripts/*.py o *.sh]
  C -->|solo si genera artefactos| F[assets/*.tf, *.yaml, *.md, *.xml]

Caso 1: el skill mínimo, skills/ads/google-mobile-ads-get-started

El SKILL.md más corto del catálogo tiene 30 líneas. Merece la pena leerlo entero porque es el molde reducido a su esqueleto.

skills/ads/google-mobile-ads-get-started/
├── SKILL.md                              (30 líneas)
├── assets/
│   └── skadnetwork-identifiers.xml
└── references/
    ├── android-get-started.md
    ├── ios-get-started.md
    └── unity-get-started.md

Frontmatter íntegro

---
name: google-mobile-ads-get-started
description: Provides instructions for integrating the Google Mobile Ads (GMA)
  SDK. Use this skill when the user wants to get started with, install,
  integrate, set up, or configure the SDK for AdMob or Ad Manager, GMA Next-Gen
  SDK or mobile ads framework in an Android, iOS, or Unity application.
metadata:
  version: 1.1.0
  category: GoogleAds
---

Tres observaciones inmediatas:

1. La description es bimodal: primero qué hace y después cuándo dispararlo con un Use this skill when… que enumera sinónimos reales del usuario: get started with, install, integrate, set up, or configure. Eso no es prosa decorativa, es superficie de activación.
2. metadata es un bloque anidado con category, y aquí también version. No es una clave del estándar sino una extensión propia de Google.
3. El orden de claves es name → description → metadata. En otros skills es name → metadata → description. El catálogo no impone un orden.

Cuerpo completo

# Google Mobile Ads SDK - Install

## Workflow

1.  **Determine the user's platform**: Identify if the project is Android, iOS,
    or Unity. If unclear, ask before proceeding.

2. **Read the platform guide** for implementation details:
    - Android: `references/android-get-started.md`
    - iOS: `references/ios-get-started.md`
    - Unity: `references/unity-get-started.md`

3. **Follow these steps in order**:
   - [ ] Add the SDK dependency
   - [ ] Set the application identifier
   - [ ] Initialize the SDK
   - [ ] Verify the integration

4. After the SDK is successfully installed, ask the user to select an ad format
   to continue the integration.

Eso es todo. El cuerpo no explica qué es un SDK de anuncios ni cómo funciona Gradle: añade solo lo que el agente no sabría por su cuenta. Tres decisiones de diseño a copiar:

• Desambiguación antes de actuar: If unclear, ask before proceeding. Una pregunta, no un cuestionario.
• Enrutado explícito a referencias: el paso 2 no dice «consulta las referencias», dice qué archivo exacto abrir para cada condición. Esa es la diferencia entre carga progresiva funcional y carga progresiva decorativa.
• Checklist con casillas: el paso 3 usa - [ ] para que el agente marque avance y no salte pasos.

El asset no se menciona en el SKILL.md: se referencia desde la hoja de iOS, que en su checklist dice Add the SKAdNetwork identifiers from assets/skadnetwork-identifiers.xml to the Info.plist file. Es decir, un asset puede colgar de una referencia y no del archivo raíz, lo que mantiene limpio el archivo que siempre se carga.

Las referencias, por su parte, son documentos técnicos densos: references/android-get-started.md entra en materia justo después de su H1, con un ## Required Imports y una lista de imports de Kotlin, seguido de ## Method Signatures con la firma exacta de initialize. Cero introducción: material de consulta puro.

Caso 2: el skill de producto, skills/cloud/cloud-run-basics

Este es el molde que verás repetido en spanner-basics, gke-basics, bigquery-basics, cloud-sql-basics y compañía: un SKILL.md autosuficiente para el camino feliz, más un abanico de referencias por dimensión del producto.

skills/cloud/cloud-run-basics/
├── SKILL.md                        (382 líneas)
└── references/                     (778 líneas en total)
    ├── core-concepts.md    cli-usage.md    client-library-usage.md
    ├── iac-usage.md        iam-security.md    mcp-usage.md
    └── networking.md

Sin scripts ni assets: siete ejes de referencia que se repiten casi idénticos en otros skills de producto, incluido spanner-basics, que añade terraform-usage.md, postgresql-dialect.md y schema-design.md a la misma base.

Frontmatter íntegro

---
name: cloud-run-basics
metadata:
  category: Serverless
description: >-
  Manages Cloud Run services, jobs, and worker pools. Use when you need to deploy applications
  responding to HTTP requests (services), run event-triggered or scheduled tasks (jobs),
  or handle always-on pull-based background processing (worker pools).
---

De nuevo el par qué hace + cuándo, y aquí el Use when enumera los tres tipos de recurso con su disparador de negocio y no con su nombre de producto: quien pide «una tarea programada» activa el skill sin saber que Cloud Run tiene jobs.

Esqueleto del cuerpo

# Cloud Run Basics
## Prerequisites
### Required roles
## Deploy a Cloud Run service        # + 3 H3: imagen, imágenes soportadas, código fuente
## Create and execute a Cloud Run job
## Deploy a worker pool              # + 2 H3 equivalentes
### What to do if a deployment fails:
## Reference Directory

Cinco bloques funcionales en orden fijo: contexto mínimo → precondiciones → procedimiento por caso → recuperación de errores → índice de referencias.

Precondiciones como comandos, no como prosa

La sección ## Prerequisites no dice «asegúrate de tener las APIs habilitadas». Da el comando, y ### Required roles lista los identificadores IAM exactos y no sus nombres humanos sueltos: roles/run.admin, roles/run.sourceDeveloper, roles/iam.serviceAccountUser sobre la identidad del servicio y roles/logging.viewer. Para Cloud Build entrega además el comando de concesión:

gcloud services enable run.googleapis.com cloudbuild.googleapis.com --quiet

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:SERVICE_ACCOUNT_EMAIL_ADDRESS \
    --role=roles/run.builder \
    --quiet

Ese --quiet no es cosmético: aparece en 26 de los 103 SKILL.md y responde a una regla operativa del catálogo, que veremos más abajo.

La regla dura embebida

En medio del procedimiento aparece un blockquote con la única regla crítica del archivo, un gotcha en el sentido exacto del estándar, colocado donde el agente lo va a necesitar y no escondido en una referencia:

> **CRITICAL RULE:** Any deployed code MUST listen on 0.0.0.0 (not 127.0.0.1)
> and use the injected $PORT environment variable (defaults to 8080), or it will
> crash on boot.

Runbook de fallo

El cierre del procedimiento es un bloque que casi ningún skill de terceros escribe:

### What to do if a deployment fails:

1.  **IAM/Permission Error:** Read [iam-security.md](references/iam-security.md).
2.  **Crash on Boot / Healthcheck failed:** Fetch the logs immediately using
    `gcloud logging read "resource.labels.service_name=SERVICE_NAME" --limit=20`
    to find the exact runtime error.
3.  **Native Dependency Error (Node/Python):** If using `--no-build`, switch to
    `--source .` (Buildpacks) to compile native extensions properly for Linux.

Tres cosas a copiar: el fallo está clasificado por síntoma, cada rama tiene una acción concreta y una de ellas es precisamente abrir la referencia adecuada. El --limit=20 evita, de paso, que el volcado de logs desborde la ventana de contexto.

Índice anotado de referencias

El archivo cierra con ## Reference Directory, una lista de los siete archivos con una línea de propósito cada uno, y una cláusula de escape: If you need product information not found in these references, use the Developer Knowledge MCP server search_documents tool.

Ese encabezado literal ## Reference Directory aparece en 10 skills, y la cláusula de escape hacia search_documents en 13. El mismo patrón, con las mismas etiquetas, se repite palabra por palabra en spanner-basics, que anota su índice con frases del tipo [CLI Usage](references/cli-usage.md): Essential gcloud spanner command-line operations for managing instances and databases.

La anotación es lo que hace útil el índice: el enlace a secas obligaría al agente a abrir el archivo para saber si le sirve; la frase de propósito le permite decidir sin gastar contexto.

La variante «gotchas primero»: gke-basics

skills/cloud/gke-basics tiene 70 líneas y usa el mismo molde con un giro: su H1 es literalmente # GKE Basics & Critical Gotchas y su cuerpo son dos secciones, ## Key Selection Rules: Autopilot vs. Standard y ## Critical Gotchas & Best Practices, antes del ## Reference Directory.

Su regla de decisión es un ejemplo limpio de default con escapatoria, otra recomendación del estándar:

* **Default to Autopilot** for almost all workloads.
* **Use Standard ONLY if:**
  * Custom node OS kernel parameters (`sysctl`) are required.
  * Custom node taints or specific hardware node pools are required.
  * DaemonSets require raw `hostPath` mounts to the host OS filesystem.

No presenta dos opciones equivalentes: fija una y enumera las tres condiciones exactas que justifican la otra, más una obligación de transparencia: When explaining why Standard is required over Autopilot, explicitly cite all matching restrictions.

Su description añade la otra mitad del disparo, los anti-disparos: Don't use for specialized GKE networking (use gke-networking), advanced security hardening (use gke-platform-security or gke-workload-security), or cluster upgrades (use gke-upgrades). Con 89 skills solo en skills/cloud/, ese redireccionamiento explícito es lo que impide que un skill se coma el territorio de otro. Lo verás en detalle en el capítulo 8, sobre infraestructura.

Caso 3: scripts y assets juntos, skills/cloud/gke-workload-security

Este skill es el punto medio: 241 líneas de SKILL.md, un script de auditoría y dos plantillas YAML.

skills/cloud/gke-workload-security/
├── SKILL.md                              (241 líneas)
├── assets/
│   ├── default-deny-netpol.yaml          ( 12 líneas)
│   └── workload-identity-pod.yaml        ( 50 líneas)
└── scripts/
    └── audit_cluster.sh                  ( 71 líneas)

Frontmatter: la description como contrato de alcance

Es una de las descripciones más largas del catálogo y está estructurada en tres tramos. Primero un Covers que inventaría capacidades citando nombres de archivo y de recurso entre backticks: Covers running cluster security audits (audit_cluster.sh), configuring Workload Identity Federation ..., enforcing Network Policies ..., isolating high-risk pods inside GKE Sandbox (gVisor) .... Después el Use when con los verbos del usuario. Y por último el Don’t use for, que dibuja la frontera con el skill vecino en una línea:

  Don't use for cluster-wide
  control plane security, RBAC hardening, Binary Authorization, Shielded Nodes,
  or enabling platform-level GKE add-ons (use gke-platform-security instead).
metadata:
  category: Security

Workload frente a control plane: ese es todo el criterio de reparto entre gke-workload-security y gke-platform-security.

El cuerpo: workflows numerados con precondiciones locales

El cuerpo son cuatro flujos bajo ## Workflows, y cada uno repite la misma micro-estructura: **Prerequisites:** con lo que debe estar instalado y autenticado, **Capabilities:** con lo que el paso comprueba o cambia, y **Command:** con la invocación exacta. El primero es ### 1. Security Audit, cuyas precondiciones son gcloud CLI autenticado y jq instalado, y cuyo comando es scripts/audit_cluster.sh <cluster-name> <region> <project-id>.

Los pasos manuales van con sus comandos verificables, en secuencia numerada y con placeholders siempre en <angulares>:

gcloud iam service-accounts add-iam-policy-binding <gsa-name>@<project-id>.iam.gserviceaccount.com \
    --role roles/iam.workloadIdentityUser \
    --member "serviceAccount:<project-id>.svc.id.goog[workload-identity-test-ns/<ksa-name>]"

Y el paso final del flujo es de verificación con un asset: Use existing asset assets/workload-identity-pod.yaml to test the configuration. Update the <ksa-name> in the file first.

El asset como plantilla aplicable

Los assets aquí no son ejemplos ilustrativos, son archivos que el agente aplica directamente con kubectl apply -f assets/default-deny-netpol.yaml -n <target-namespace>. El de la política por defecto cabe en doce líneas, con podSelector: {} y policyTypes de Ingress y Egress, y lleva hasta un comentario que justifica ante el escáner de seguridad por qué casa con todos los pods a propósito: # checkov:skip=CKV_K8S_39:Default deny all intentionally matches all pods.

El script como auditoría con salida legible

scripts/audit_cluster.sh cabe en 71 líneas y establece un patrón que conviene robar tal cual: abre con set -e y set -o pipefail, valida sus tres argumentos posicionales y sale con exit 1 imprimiendo el Usage:. Después hace una sola llamada a la API y extrae todo con jq en una pasada, dejando escrito el motivo, y emite resultados con prefijos que el modelo puede parsear sin ambigüedad:

CLUSTER_JSON=$(gcloud container clusters describe "${CLUSTER_NAME}" --region "${REGION}" --project "${PROJECT_ID}" --format=json)

# Extract all configurations in one pass for performance
VALUES=$(echo "${CLUSTER_JSON}" | jq -r '[(.workloadIdentityConfig.workloadPool // "DISABLED"), (.networkPolicy.enabled // "FALSE" | tostring)] | @tsv')

if [[ "${WI_CONFIG}" != "DISABLED" ]]; then
    echo "[PASS] Workload Identity is ENABLED (${WI_CONFIG})"
else
    echo "[FAIL] Workload Identity is DISABLED"
fi

[PASS] / [FAIL] en lugar de prosa. El script no interpreta, reporta; la interpretación la hace el agente con el SKILL.md delante. Y para las advertencias condicionales el skill usa bloques de alerta de GitHub: > [!NOTE] If your cluster uses Dataplane V2 (--enable-dataplane-v2), Network Policy enforcement is built-in and this step is not required (and may fail).

Caso 4: el skill industrial, skills/cloud/agent-platform-alert-configuration

Con 27 archivos empata con gke-compute-classes en lo más alto del catálogo por número de archivos, y es el único con una suite de pruebas unitarias dentro de scripts/.

skills/cloud/agent-platform-alert-configuration/
├── SKILL.md                              (269 líneas)
├── references/                           (8 archivos)
│   ├── cost_alert_policies.md      quality_alert_policies.md
│   ├── reliability_alert_policies.md    safety_alert_policies.md
│   ├── security_alert_policies.md       telemetry_enablement.md
│   └── has_historical_traffic_data.md   no_historical_traffic_data.md
└── scripts/                              (18 archivos)
    ├── requirements.txt   config_utils.py   lint_syntax.py
    ├── gather_agent_info.py   analyze_traffic.py   check_telemetry.py
    ├── create_online_monitor.py   scan_duplicates.py
    ├── list_log_scope_table_names.py   list_trace_scope_table_names.py
    └── ocho archivos *_test.py, uno por script salvo lint_syntax.py

Cerca de 3.800 líneas de Python, de las que casi la mitad son tests. El agente no ejecuta esos tests: documentan el contrato de cada función para quien mantenga el skill.

Frontmatter: el único con allowed-tools

---
name: agent-platform-alert-configuration
metadata:
  category: AiAndMachineLearning
description: >-
  Configures best-practice alerting policies for AI agents using OpenTelemetry
  (OTel) metrics. Use when analyzing, writing, or deploying alerting policies ...
  NOTE: Reliability, Cost, Safety, and Security alerts use generic OTel metrics
  and work across runtimes (e.g., Cloud Run, Vertex AI). Quality alerts rely
  on Vertex AI Online Monitors and are strictly bound to Vertex AI deployments.
allowed-tools: terraform gcloud python
---

allowed-tools aparece en exactamente un SKILL.md de los 103. La description además mete un NOTE: con una restricción de aplicabilidad: parte de las alertas funciona en cualquier runtime y otra parte solo sobre Vertex AI. Es encuadre que evita que el agente prometa lo que no puede entregar.

Esqueleto: el ciclo completo

# Agent Platform Alert Configuration
## Critical Steps
    ### 1. Safety & Confirmation Tiers (CRITICAL)  ### 2. Prerequisites & Dependencies
    ### 3. Input Assumptions                       ### 4. Execution Steps
    ### 5. Outputs & Formats                       ### 6. Output Verification
## Tooling Scripts
## Gotchas & Behavioral Corrections
## Supporting Links

Ese orden es el ciclo de vida completo de una tarea agéntica: consentimiento, dependencias, supuestos, ejecución, salida, verificación, herramientas, correcciones de conducta y enlaces.

Tiers de consentimiento

Es el mecanismo de consentimiento más explícito del repositorio, y son dos categorías cerradas con los nombres de script que caen en cada una:

1.  **Tier R: Read-only (`check_telemetry.py` / `gather_agent_info.py`)**
    *   **Rule**: No confirmation needed. You may execute these scripts immediately ...
2.  **Tier B: Billing & Resource Creation (`create_online_monitor.py` / provisioning)**
    *   **Rule**: **Explicit User Confirmation Required**. These actions incur
        additional billing charges and create cloud resources. ... You MUST STOP ...

No hay un «pide permiso cuando corresponda»: hay un corte con motivo económico, y el skill obliga a nombrar el coste concreto, las evaluaciones con LLM y la exportación a Cloud Trace y Logging. El mismo mecanismo lo verás en los skills de onboarding del capítulo 5.

Precondiciones ejecutables

La sección de dependencias no sugiere, ordena: Before executing any python script in this skill you MUST install the required dependencies in your environment. Run this command first: pip install -r scripts/requirements.txt. Y ese requirements.txt lleva versiones fijadas, no rangos: google-cloud-monitoring==2.31.0, google-cloud-aiplatform==1.160.0, google-auth==2.55.2, requests==2.34.2.

Protocolo secuencial con fallbacks

### 4. Execution Steps obliga a un orden y define qué hacer cuando cada paso falla:

flowchart TD
  S1[Paso 1: gather_agent_info.py<br/>descubrimiento total] -->|exito completo| S3
  S1 -->|falla o datos parciales| S2A[Accion A: gcloud beta monitoring metrics-scopes list]
  S2A -->|sin resultado| S2B[Accion B: buscar google_monitoring_monitored_project en Terraform]
  S2B -->|ambiguo| S2C[Accion C: preguntar al usuario<br/>por el scoping project ID]
  S2C --> S3
  S2A --> S3
  S3[Paso 3: scan_duplicates.py<br/>evitar politicas duplicadas] --> R[Leer references/*_alert_policies.md<br/>segun el tipo de alerta]
  R --> W[Escribir alerts.tf y variables.tf]
  W --> L[lint_syntax.py]
  L -->|salida distinta de cero| F[Corregir en sitio y reejecutar]
  F --> L
  L -->|salida cero| OK[Entregar con explicacion en lenguaje llano]

La pregunta de la Acción C está escrita literal en el skill, entre comillas, para que el agente no la improvise: Are you using a multi-project Cloud Monitoring Metric Scope? If so, what is the scoping project ID?.

Enrutado a referencias por tabla y contratos numéricos

El skill no dice «lee las referencias»: incluye una tabla de dos columnas, Alert Type y Reference File, con cinco filas que van de **Reliability** a [reliability_alert_policies.md](references/reliability_alert_policies.md) y así con Quality, Cost, Safety y Security. Es el nivel máximo de precisión en carga progresiva: el agente no elige por intuición, casa una fila.

Y la sección de salidas tampoco deja el volumen al criterio del modelo: fija cantidades exactas. Exactamente cinco políticas de fiabilidad, tres de calidad, una de coste, una de safety y una de seguridad. Formato de salida: solo Terraform, con provider >= 6.0.0 —o versiones tardías de la rama 5.x que ya soporten la función— porque condition_sql lo exige. Ese determinismo numérico es una de las señas de identidad de la casa: el mismo prompt debería producir el mismo número de artefactos en dos ejecuciones distintas.

Bucle de autocorrección

*   **Config Linting**: Validates PromQL grammar, matching engine labels, and HCL structure:
    *   Command: `python3 scripts/lint_syntax.py {path_to_tf_file}`
    *   **Self-Correction Loop**: If validation fails (exits non-zero or outputs
        errors), you MUST read the command output, locate the line/file
        containing the lint error, ... apply adjustments in-place, and re-run the
        `lint_syntax.py` validation. Repeat this loop until the validation
        script passes successfully.

Esta es la mejor pieza del skill para copiar: el agente escribe, un script determinista juzga y el agente corrige hasta que el juez aprueba. No hay «revisa que esté bien».

Gotchas de verdad

Y por último, la sección de correcciones de conducta, con hechos que ningún modelo adivinaría:

• ALIGN_MEAN no se puede aplicar a métricas DELTA de distribución como online_evaluator/scores; hay que usar aligners de percentil como ALIGN_PERCENTILE_50.
• Dentro de heredocs de HCL, las variables van como ${var.nombre}: Bare references like var.variable_name will fail at deployment time.
• scan_duplicates.py saliendo con código 1 es un resultado esperado, no un error: hay que parsear su JSON, editar en sitio y reintentar.
• Y una prohibición operativa tajante: You MUST NOT run recursive listing or search commands (such as ls -R, find ., or raw recursive grep) from the repository root ... as this will freeze your session.

Los patrones que Google repite en todo el catálogo

Con los cuatro casos delante, estos son los patrones medibles, contados sobre los 103 archivos:

Patrón	Presencia
description con Use when / Use this skill when	87 skills
description con cláusula de exclusión (Don't use for, Do not use)	77 skills
…y que además nombra el skill al que redirigir	33 skills
Uso de MUST en mayúsculas	48 skills
Comandos con --quiet	26 skills
Encabezado de validación o verificación explícita	20 skills
Encabezado ## Prerequisites / cláusula de escape hacia search_documents	13 skills cada uno
Encabezado literal ## Reference Directory	10 skills
Mención explícita de gotchas	8 skills
Campo metadata.version / campo allowed-tools	13 skills / 1 skill

A eso se suman los bloques de alerta estilo GitHub, contando ocurrencias en todo el catálogo: > [!IMPORTANT] 68 veces, > [!NOTE] 18, > [!WARNING] 15, > [!TIP] 14 y > [!CAUTION] 11. La jerarquía es informativa: lo que se marca como importante multiplica por seis a lo que se marca como precaución. Traducidos a reglas de escritura, los ocho patrones que definen el estilo de la casa son:

1. Frontmatter mínimo y bimodal. name, metadata.category, description. La descripción casi siempre dice qué hace y cuándo dispararse; tres cuartas partes dicen además cuándo no, y un tercio nombra al skill vecino.
2. Encabezados funcionales, no temáticos. Prerequisites, Workflow, Execution Steps, Outputs & Formats, Output Verification, Gotchas, Reference Directory. Un lector humano sabría qué hay en cada sección sin leerla.
3. Precondiciones como comandos ejecutables, con los roles IAM en su forma roles/loquesea y el comando que los concede.
4. Determinismo de terminal. --quiet para no colgarse en prompts interactivos, --format=json para salida parseable, --limit=N para no desbordar la ventana de contexto, prohibición de recorridos recursivos desde la raíz.
5. Criterios de éxito verificables. Checklists con - [ ], salidas [PASS] / [FAIL], códigos de retorno, comprobaciones que devuelven un HTTP esperado.
6. Manejo de errores clasificado por síntoma, con una acción por rama y, cuando aplica, con la referencia exacta a abrir.
7. Carga progresiva enrutada. El índice de referencias está anotado, y cuando la decisión es discreta se convierte en tabla condición → archivo.
8. Puertas de consentimiento con motivo económico. No «pide permiso»: tiers cerrados, con el coste concreto que se le va a explicar al usuario.

Contraste con las buenas prácticas del estándar

El curso Agent Skills cubre el formato y las recomendaciones de escritura. Puesto uno al lado del otro, el catálogo de Google es en gran medida esas recomendaciones aplicadas a escala industrial, con algunas desviaciones interesantes.

Buena práctica del estándar	Cómo la aplica Google
Añade lo que el agente no sabe, omite lo que ya sabe	Ningún skill explica qué es un contenedor o qué es SQL; entran directo a los flags, roles y nombres de recurso
Da defaults, no menús	Default to Autopilot ... Use Standard ONLY if con tres condiciones cerradas
Sección de gotchas con hechos contraintuitivos	ALIGN_MEAN no aplica a métricas DELTA; el código debe escuchar en 0.0.0.0 y no en 127.0.0.1
Plantillas para el formato de salida	Assets normativos: .tf, .yaml y plantillas de informe en assets/
Checklists para flujos multipaso	- [ ] en google-mobile-ads-get-started y en las validaciones de varios skills
Bucles de validación; plan, validar, ejecutar	gather_agent_info.py → scan_duplicates.py → escritura → lint_syntax.py hasta salida cero
Empaquetar scripts reutilizables	12 skills con scripts/, uno de ellos con tests unitarios por script
Decir cuándo cargar cada referencia	Índices anotados y tablas condición → archivo, no un genérico «ver referencias»
SKILL.md por debajo de 500 líneas	Mediana de 193; solo 3 de 103 se pasan

Y donde el catálogo se aparta:

• metadata no es del estándar. El bloque anidado con category y a veces version es una extensión propia de Google para su taxonomía interna. Un harness que solo lea el estándar lo ignorará sin romperse, pero no cuentes con que lo interprete.
• version es inconsistente. Solo 13 skills lo declaran —los doce de skills/ads/ más google-cloud-storage-basics—, en siete formas distintas: 1.0, "1.0", 1.0.0, "1.0.0", 1.1, 1.1.0 y v1. Y el orden de claves del frontmatter varía: 67 archivos usan name/metadata/description y 36 usan name/description/metadata. Son 103 archivos escritos por varios equipos.
• allowed-tools está prácticamente sin usar. Un solo skill lo declara, aunque decenas ejecutan gcloud, kubectl, terraform y Python. Si tu harness lo respeta, declararlo te da una capa de contención barata.
• Hay referencias colgantes. Cuatro descripciones redirigen a skills que no existen en este repositorio: ima-sdk-dai-basics, vertex-deploy, gma-android-integrate y cloud-monitoring-promql-query. Si copias el patrón Don't use for X (use el skill Y), verifica que Y exista de verdad.

Para el otro extremo del ciclo, cómo se empaqueta todo esto en unidades distribuibles con manifiesto y marketplace, el curso Agent Plugins Spec cubre la especificación, y el capítulo 11 muestra cómo la implementa este repositorio.

Plantilla que puedes copiar

Destilando los cuatro casos, este es el esqueleto que reproduce el estilo de la casa para un skill de complejidad media:

---
name: mi-skill
metadata:
  category: MiCategoria
description: >-
  Hace X sobre Y. Use when el usuario pide A, B o C.
  Don't use for D (use el skill mi-otro-skill instead).
---

# Mi Skill

Dos o tres líneas de contexto: qué es el sistema y cuáles son sus piezas.

## Prerequisites

1.  Habilitar lo que haga falta, con un comando concreto y no interactivo.
2.  Roles requeridos, con su identificador exacto y el comando que los concede.

## Workflow

1.  **Desambiguar**: identificar la variante. Si no está claro, preguntar antes de seguir.
2.  **Leer la guía correspondiente**: caso A en `references/caso-a.md`, caso B en `references/caso-b.md`.
3.  **Ejecutar en orden**:
    - [ ] Paso 1
    - [ ] Paso 2
    - [ ] Paso 3

> **CRITICAL RULE:** El hecho del entorno que rompe todo si se ignora.

## Qué hacer si falla

1.  **Síntoma de permisos**: leer `references/iam.md`.
2.  **Síntoma en arranque**: recuperar logs con un comando acotado por `--limit`.

## Output Verification

Ejecutar `scripts/validate.sh <ruta>` y corregir en sitio hasta que salga con código cero.

## Gotchas

-   Hecho no obvio 1, con su consecuencia si se ignora.

## Reference Directory

-   [Core Concepts](references/core-concepts.md): qué contiene y cuándo abrirlo.
-   [CLI Usage](references/cli-usage.md): qué contiene y cuándo abrirlo.

Checklist de adopción antes de dar un skill por terminado:

• La description responde qué hace, cuándo usarlo y cuándo no, y el skill al que redirige existe de verdad.
• Ningún párrafo explica algo que el modelo ya sabe.
• Cada precondición es un comando, no una frase; toda mutación es no interactiva y de salida acotada.
• Existe al menos un criterio de éxito comprobable por máquina.
• Los errores están clasificados por síntoma, con una acción por rama.
• El índice de referencias dice cuándo abrir cada archivo, no solo que existe.
• Los gotchas están en el SKILL.md, no escondidos en una referencia.
• El SKILL.md está por debajo de 500 líneas.

Resumen

• Un skill del catálogo es un directorio con SKILL.md obligatorio y hasta tres subdirectorios opcionales: references/ en 55 skills, assets/ en 17 y scripts/ en 12. 41 de los 103 son un solo archivo Markdown, con una mediana de 193 líneas y solo 3 skills por encima de las 500.
• skills/ads/google-mobile-ads-get-started demuestra que 30 líneas bastan cuando el cuerpo es un enrutador con checklist; skills/cloud/cloud-run-basics fija el molde del skill de producto con precondiciones ejecutables, runbook de fallo e índice anotado; skills/cloud/gke-workload-security combina script de auditoría con salida [PASS]/[FAIL] y assets aplicables con kubectl apply -f; skills/cloud/agent-platform-alert-configuration lleva el molde a escala industrial con tiers de consentimiento, protocolo secuencial con fallbacks, contratos numéricos y bucle de autocorrección con linter propio.
• Los patrones repetidos son medibles: 87 skills con Use when, 77 con cláusula de exclusión (33 de ellas nombrando el skill alternativo), 48 con MUST, 26 con --quiet, 20 con encabezado de validación, 68 ocurrencias de > [!IMPORTANT].
• El catálogo cumple casi punto por punto las buenas prácticas del estándar y se aparta en detalles menores: metadata es extensión propia, version aparece en 13 skills con siete formatos distintos, allowed-tools solo en uno, y hay cuatro redirecciones a skills inexistentes.

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