Cuando empiezas con Antigravity, las Skills parecen simples archivos Markdown con instrucciones. Pero el frontmatter YAML esconde campos que cambian por completo cómo el agente ejecuta cada tarea: desde qué modelo usa hasta cuántas herramientas puede invocar o cuántos turnos puede dar antes de parar. He estado probando estos campos en proyectos reales y voy a explicar qué hace cada uno y cuándo usarlo.

## Estructura de una SKILL

Una Skill es un directorio con un archivo `SKILL.md`. El archivo tiene dos partes:

1. **Frontmatter YAML**: metadatos y parámetros de ejecución
2. **Cuerpo Markdown**: instrucciones, flujos de trabajo y criterios de verificación

El motor de Antigravity lee primero el frontmatter para decidir si esa Skill encaja con la intención de quien la usa. Solo cuando la activa carga el cuerpo completo. Esto importa para las buenas prácticas que veremos al final.

```yaml
---
name: webperf-lcp-audit
description: Audita el LCP de una página analizando el elemento candidato, su tiempo de carga y los recursos que lo bloquean. Genera un informe con las regresiones encontradas y propuestas de mejora priorizadas.
kind: subagent
model: gemini-2.5-pro
temperature: 0.2
max_turns: 15
tools:
  - run_command
  - view_file
  - write_to_file
  - mcp_chrome-devtools/*
---
```

Importante: `name` y `description` son los únicos campos del [estándar abierto Agent Skills](https://agentskills.io/specification). Los campos `kind`, `model`, `temperature`, `max_turns` y `tools` son extensiones nativas de Antigravity, sin documentación oficial pública todavía. Los campos no reconocidos por otros agentes (Claude Code, Cursor, etc.) se ignoran sin error, así que puedes compartir las mismas Skills en entornos multiagénticos sin adaptarlas.

## `kind`: cómo se ejecuta la Skill

El campo `kind` define el modo de ejecución dentro de la arquitectura del agente.

- **`inline`**: la Skill se carga directamente en el contexto del agente principal, compartiendo todas sus herramientas y el historial de conversación.
- **`subagent`**: se instancia un agente aislado en segundo plano, dedicado en exclusiva a esa tarea. El contexto del agente principal queda limpio.
- **`workflow`**: indica que la Skill define un flujo de múltiples pasos estructurado.

<figure>
  <iframe
    id="ag-kind-demo"
    src="/demos/antigravity-kind-diagram.html"
    width="100%"
    height="340"
    style="border: none; border-radius: 8px; display: block;"
    title="Diagrama comparativo de los tres modos de ejecución: inline, subagent y workflow"
    loading="lazy"
  ></iframe>
</figure>
<script>
window.addEventListener('message', function(ev) {
  if (ev.data && typeof ev.data.agKindH === 'number') {
    var f = document.getElementById('ag-kind-demo');
    if (f) f.style.height = (ev.data.agKindH + 24) + 'px';
  }
});
</script>

Usa `subagent` para tareas complejas y delimitadas: análisis de rendimiento, refactorizaciones grandes, procesamiento de logs. Usa `inline` para tareas ligeras o transversales como guías de estilo o atajos de Git.

## `tools`: mínimo privilegio

Define explícitamente qué herramientas o servidores MCP puede usar el agente durante esa Skill.

<figure>
  <iframe
    id="ag-tools-demo"
    src="/demos/antigravity-tools-diagram.html"
    width="100%"
    height="340"
    style="border: none; border-radius: 8px; display: block;"
    title="Diagrama comparativo: agente sin tools declaradas vs con tools restringidas"
    loading="lazy"
  ></iframe>
</figure>
<script>
window.addEventListener('message', function(ev) {
  if (ev.data && typeof ev.data.agToolsH === 'number') {
    var f = document.getElementById('ag-tools-demo');
    if (f) f.style.height = (ev.data.agToolsH + 24) + 'px';
  }
});
</script>

Hay tres razones para restringir las herramientas:

### Seguridad (mínimo privilegio)

Una Skill de revisión de código no necesita `run_command` ni `write_to_file`. Si no las declaras, el agente no puede usarlas aunque estén disponibles en la sesión.

### Optimización de tokens

El sistema incluye el esquema JSON de cada herramienta en el prompt. Enviar la descripción de decenas de herramientas MCP en cada llamada consume tokens innecesarios. Restringirlas reduce latencia y coste.

### Menos alucinaciones

El modelo no puede intentar resolver una tarea con la herramienta equivocada si solo le expones las idóneas para esa Skill.

## `model`: el modelo adecuado para cada tarea

Sobrescribe el modelo de la sesión para esa Skill específica. La regla es sencilla:

```yaml
# Tareas mecánicas, iterativas o de baja complejidad
model: gemini-3.5-flash

# Tareas de alto valor cognitivo
model: gemini-2.5-pro
```

**Flash** para escribir boilerplate, formatear Markdown, tareas sencillas de Git o pre-filtrado de información. **Pro** para debugging de regresiones de rendimiento, análisis de LCP o INP, refactorización de lógica crítica o auditorías de Core Web Vitals.

No tiene sentido usar siempre el modelo más potente. Elegir el modelo adecuado para cada tarea optimiza el presupuesto del proyecto sin sacrificar calidad donde más importa.

## `temperature`: determinismo vs. creatividad

Modula la aleatoriedad de las respuestas. Rango de `0.0` a `2.0`.

```yaml
# Tareas analíticas: máximo determinismo
temperature: 0.2

# Tareas creativas: más variabilidad
temperature: 0.8
```

Temperaturas bajas (`0.0`-`0.3`) para refactorizaciones, análisis de waterfalls, generación de scripts de monitorización o debugging. Necesitas consistencia y cero desviaciones imaginativas.

Temperaturas altas (`0.7`-`1.0`) para ideación, diseño de interfaces, brainstorming de arquitectura o redacción de documentación descriptiva.

## `max_turns`: evitar bucles infinitos

Define el límite máximo de interacciones (pensar → llamar herramienta → recibir output) que el agente puede realizar.

```yaml
# Skill de comprobación rápida (ej. verificar un header de caché)
max_turns: 5

# Auditoría completa de Core Web Vitals con análisis de recursos y propuestas
max_turns: 30
```

En tareas automatizadas, un agente puede quedarse atrapado intentando optimizar una imagen que en realidad está bloqueada por un problema de prioridad de carga. Sin `max_turns`, consumirá recursos indefinidamente. Con el límite, se detiene e informa al usuario o usuaria.

Una configuración habitual de producción es `max_turns: 15` o `20` para Skills de mediana complejidad.

## Buenas prácticas al diseñar Skills

### Frontmatter ligero e informativo

El router de Antigravity empareja intenciones basándose en `name` y `description`. El cuerpo completo solo se carga al activar la Skill, así que el frontmatter debe ser suficientemente preciso para el matching pero sin sobrecargar el contexto innecesariamente.

### Descripciones precisas

El campo `description` debe detallar cuándo y para qué es útil la Skill. No basta con el nombre:

```yaml
# ❌ Demasiado genérico
description: Revisa accesibilidad web.

# ✅ Preciso y accionable
description: Actívalo cuando necesites auditar problemas de accesibilidad WCAG 2.1 AA en componentes React: contraste, roles ARIA, navegación por teclado y orden de foco.
```

### Combina `tools` con instrucciones de alcance

Puedes combinar la restricción de herramientas en el YAML con instrucciones en el Markdown que indiquen sobre qué directorios del workspace puede operar el agente. Doble capa de restricción.

## Dónde instalar las Skills

Las Skills se instalan en directorios distintos según la _"surface"_ (el cliente desde el que usas Antigravity: CLI, app de escritorio o extensión del IDE):

| Superficie | Global                              | Proyecto                     |
| ---------- | ----------------------------------- | ---------------------------- |
| CLI        | `~/.gemini/antigravity-cli/skills/` | `<proyecto>/.agent/skills/`  |
| App / IDE  | `~/.agents/skills/`                 | `<proyecto>/.agents/skills/` |

El comportamiento de los campos del frontmatter es idéntico en las tres superficies. Solo cambia el directorio de instalación.

## Conclusión

Los cinco campos extendidos de Antigravity (`kind`, `tools`, `model`, `temperature`, `max_turns`) no son detalles opcionales: son los controles que determinan la eficiencia, seguridad y coste de cada Skill. La combinación que más impacto tiene en la práctica es `kind: subagent` + `tools` restringido + `model` ajustado a la complejidad de la tarea. Con esos tres campos bien configurados, las Skills pasan de ser instrucciones Markdown a agentes con comportamiento predecible y presupuesto controlado.