Tutorial de Custom Agents de Antigravity: crea tus propios especialistas
Convierte los trabajos recurrentes en sub-agentes guardados: un archivo markdown con frontmatter YAML bajo .agents/agents, una lista de herramientas acotada y reglas, flujos de trabajo y skills por encima — cada captura proviene de una grabación real.
La versión corta
- Un custom agent es un solo archivo markdown: frontmatter YAML (name, description, model, tools) más el cuerpo con el prompt del sistema — guarda el especialista recurrente una vez y deja de explicarlo en cada sesión.
- Los agentes de workspace viven en .agents/agents/<nombre>.md y se entregan con el repositorio; los personales en ~/.gemini/config/agents/ se aplican a todos los proyectos de la máquina.
- tools exige nombres exactos de herramientas de Antigravity — view_file, grep_search, list_dir — y un nombre erróneo tumba al agente al arrancar; subagent: true lo hace delegable y mainAgent: true lo añade al selector de entrada.
- Prueba rápida con "What are your tools?" en el selector del IDE, delega desde el chat principal o inspecciona con /agents y Alt+J en la CLI — después añade reglas, flujos de trabajo y skills.
Google Antigravity Livestream: Remote Control and Custom Agents
Canal:Google Antigravity47:43
Antigravity Customization Features That 10X Your Coding Speed
Canal:Code A Program11:02
Defining Custom Subagents (.md) — Antigravity Docs
Docs:antigravity.googleDocs
Las capturas son fotogramas de la grabación de pantalla de Code A Program (citado arriba); el flujo de creación del archivo del custom agent se documenta a partir del livestream oficial de Google y de la documentación de subagents de Antigravity, de la que aún no existe una grabación limpia de terceros.
La verificación de hechos también se apoya en los vídeos sobre custom agents de Use AI with Tech Dad y AI with Surya. Todas las marcas pertenecen a Google; este es un tutorial independiente, sin afiliación con Google.
De la carpeta vacía al especialista de confianza
1 · Acota el especialista
- 1
Detecta un rol que merezca guardarse
Un custom agent gana su archivo cuando el mismo trabajo se repite: un revisor de código con checklist fija, un modernizador de dependencias, un lanzador de tests, un mantenedor de documentación. Si las instrucciones son estables, distintas de tu asistente general y la caja de herramientas se puede nombrar por adelantado, guarda el rol. Las peticiones puntuales quedan mejor como un prompt simple.
- 2
Sepáralo de los sub-agentes y las skills
Un sub-agente es el puesto de trabajo: la sesión a la que tu agente principal delega. Un custom agent es el perfil guardado que puede ocupar ese puesto — o con quien puedes hablar directamente. Las skills son otra capa: empaquetan conocimiento de tarea que cualquier agente puede tomar, mientras que un custom agent cambia sus instrucciones base y su acceso a herramientas. Para un trabajador puntual no necesitas archivo; Antigravity puede crear un sub-agente transitorio con la herramienta define_subagent en mitad de la sesión.
- 3
Elige el alcance: repositorio o máquina
Antigravity descubre los .md de custom agents en tres sitios. Las customizations de workspace viven en .agents/agents/<nombre>.md (o .agents/agents/<nombre>/agent.md) y viajan con el repositorio — ideales para convenciones compartidas. Las customizations globales viven en ~/.gemini/config/agents/<nombre>.md y se aplican a todos los proyectos de la máquina — ideales para especialistas personales. Los plugins pueden incluir agentes en plugins/<nombre_plugin>/agents/.
La página Rules de la documentación de Antigravity: las reglas globales viven en ~/.gemini/GEMINI.md y valen para todos los workspaces, las del workspace en la carpeta .agents — la misma división que siguen los archivos de custom agents.Ver en 0:30
2 · Escribe el archivo del agente
- 4
Crea el archivo del agente
Dentro de tu proyecto, crea carpeta y archivo de una vez — el nombre del archivo o de la carpeta se convierte en la identidad del agente, así que minúsculas y guiones: .agents/agents/codereviewer/agent.md. También puedes pedirle al agente de Antigravity que lo monte: en el walkthrough oficial, un único prompt de "I have an idea for a custom agent" devolvió la ruta completa undefined/.agents/agents/codereviewer/agent.md y una definición lista para editar.
- 5
Rellena el frontmatter YAML
El frontmatter declara la identidad y los límites del especialista. name debe ser único — es lo que vas a @mencionar. description le dice a Antigravity cuándo usar al especialista, escríbela como un anuncio de empleo. model: inherit mantiene el nivel de modelo del padre, y tools lista exactamente lo que el rol puede usar. Dos banderas completan el cuadro: subagent por defecto true (se puede delegar) y mainAgent por defecto false (ponla en true para elegirlo directamente en el selector de entrada).
- 6
Escribe el cuerpo del prompt del sistema
Todo lo que queda bajo el delimitador del frontmatter se convierte en las instrucciones del sistema. El ejemplo oficial abre con una persona ("You are an expert, meticulous Code Reviewer"), lista responsabilidades — corrección, seguridad, rendimiento, estilo — y cierra con un formato de salida estricto: un veredicto Summary, hallazgos críticos bloqueantes con referencias de línea y sugerencias no bloqueantes. Un formato de informe estable es lo que hace fiables sus resultados.
---
name: codereviewer
description: >-
Code review specialist that analyzes diffs, inspects code for bugs,
architectural issues, performance bottlenecks, and style compliance.
model: inherit
tools:
- view_file
- grep_search
- list_dir
subagent: true
---
# Code Reviewer Persona & Instructions
You are an expert, meticulous Code Reviewer. Inspect proposed changes,
pull requests, and codebase files for correctness, security, performance,
and style.
## Review Output Format
- **Summary**: high-level assessment (LGTM / Changes Requested)
- **Critical findings**: blocking issues with line references and fixes
- **Suggestions & Improvements**: non-blocking refactors3 · Amplíalo y ponle límites
- 7
Acota la caja de herramientas con nombres reales
El frontmatter tools toma una lista blanca explícita y los nombres deben coincidir con las herramientas reales de Antigravity. En el walkthrough oficial, el archivo generado decía read — y el agente murió con "Agent execution terminated due to error" hasta corregirlo a view_file. Quédate con nombres como view_file, grep_search y list_dir, y dale al rol solo lo que necesita; un revisor rara vez necesita escritura.
Un archivo de configuración del workspace con los nombres de herramientas que un agente puede llamar — view_file, grep_search, read_file — el mismo vocabulario que espera la lista tools de un custom agent.Ver en 4:44 - 8
Decide cuándo actúa
Con subagent: true (por defecto) tu especialista está disponible para delegación: describe el trabajo al agente principal y este pasa la tarea acotada al especialista, cuyo informe vuelve a la conversación principal. Los sub-agentes delegados heredan los límites de permisos del padre — comandos permitidos, alcances de archivos y ajustes de sandbox — y las acciones que requieren aprobación aparecen en la interfaz principal. Pon también mainAgent en true y el especialista aparece en el selector para entrevistarlo directamente.
- 9
Abre Customizations y nombra una regla
Los custom agents se vuelven listos rápido cuando añades reglas de casa. En el IDE, abre el desplegable "..." de la parte superior del panel del agente y elige Customizations — el mismo panel aloja Rules y Workflows. En Rules, crea una regla nueva: las reglas globales viven en ~/.gemini/GEMINI.md y se aplican a todos los workspaces, mientras que las del workspace viven en la carpeta .agents del workspace o la raíz de git. Cada archivo de regla está limitado a 12.000 caracteres.
El panel Customizations del panel de agente de Antigravity: la pestaña Rules está activa y se escribe el nombre de una nueva regla con el placeholder e.g. code-style-guide.Ver en 0:56 - 10
Elige el modo de activación
Cada regla responde a una pregunta: ¿cuándo aplica? Always On la inyecta en cada conversación; Manual espera una @mención en el cuadro de entrada; Model Decision deja que el agente la active según su descripción en lenguaje natural; Glob la aplica solo a los archivos que coincidan con un patrón como *.test.ts. Elige el modo más estrecho que funcione — una regla de revisión que solo salta en diffs se mantiene centrada.
El desplegable Activation Mode en un editor de reglas de Antigravity con las cuatro opciones visibles — Always On, Manual, Model Decision y Glob.Ver en 1:04 - 11
Escribe el contenido de la regla
Las reglas son restricciones en Markdown plano: "añade comentarios que expliquen por qué existe el código, no qué hace", "usa JSDoc en las funciones", "no dejes TODOs". Mantén cada regla con un solo propósito — el agente las lee literalmente en cada conversación afectada. Las reglas moldean cómo trabaja tu especialista; las dos capas siguientes le dan procesos y conocimiento.
Un archivo de regla llamado comments.md en el editor de Antigravity, Activation Mode en Always On, listo para las instrucciones Markdown que seguirá cada conversación.Ver en 1:02 - 12
Empaqueta los procedimientos recurrentes como workflows
Cuando el especialista deba repetir un procedimiento de varios pasos — limpiar ramas fusionadas, cortar una release, regenerar la documentación de la API — guárdalo como workflow en vez de reescribir los pasos. Los workflows son archivos markdown con una descripción YAML en el frontmatter, invocados con un comando de barra: escribe /cleanup-branches y el agente ejecuta cada paso listado.
La sección Workflows de la documentación de Antigravity: los archivos de workflow viven en la carpeta .agent workflows y se invocan en el chat con un comando /workflow-name.Ver en 5:40 - 13
Crea el archivo del workflow
Pide al agente que lo monte o hazlo tú: mkdir -p .agent/workflows y luego cleanup-branches.md con una descripción breve en el frontmatter y los pasos numerados. En el ejemplo grabado, los pasos van de git fetch --prune a borrar ramas fusionadas — y como cada paso es explícito, el agente se detiene y pregunta antes de los destructivos.
Una conversación de Antigravity donde el agente ejecuta mkdir -p .agent/workflows y nano, y recibe el markdown del workflow — frontmatter de descripción más una checklist de git de diez pasos.Ver en 6:20
4 · Prueba, publica y distingue las capas
- 14
Mira la barrera de seguridad en acción
La ejecución grabada termina con el agente informando de la rama obtenida, señalando feature/about-page como fusionada y segura de borrar, y preguntando "Would you like me to proceed with deleting these?" antes de tocar nada. Ese hábito de aprobación se extiende a los custom agents delegados: las acciones que requieren autorización aparecen en la interfaz principal, así el especialista nunca cruza un límite en silencio.
El informe del workflow: feature/about-page está fusionada y es segura de borrar, y el agente pregunta "Would you like me to proceed?" antes de ejecutar git branch -d y git gc.Ver en 7:46 - 15
Enséñale una skill
Las reglas moldean el comportamiento; las skills añaden conocimiento. Una skill es una carpeta con un archivo SKILL.md — las del workspace bajo .agents/skills/<nombre-skill>/, las personales bajo ~/.gemini/skills. El name y la description del frontmatter le dicen al agente cuándo es relevante; el cuerpo lleva las instrucciones completas, scripts y referencias. Custom agents y skills se combinan: tu codereviewer puede apoyarse en una skill nextjs-reviewer para comprobaciones específicas del framework.
La sección Agent Skills de la documentación de Antigravity: crea una carpeta en uno de los directorios de skills y añade un archivo SKILL.md con frontmatter YAML.Ver en 8:42 - 16
Escribe el frontmatter del SKILL.md
Escribe la description como un disparador: "Reviews Next.js and TypeScript code for critical issues only — types, performance, security, and App Router patterns". Cuando una petición encaja, el agente carga la skill completa; cuando no, la skill no estorba. Esa carga progresiva es justo la razón por la que el material de referencia profundo va en una skill y no en el prompt del sistema del agente.
Un SKILL.md de nextjs-reviewer en el editor de Antigravity: el frontmatter YAML lleva el nombre de la skill y su descripción — Reviews Next.js and TypeScript code for critical issues only.Ver en 9:16 - 17
Mira la skill dispararse en una revisión real
En la sesión grabada, pedir al agente que revisara el código Next.js hizo que cargara la skill de revisión, analizara la página y respondiera con una revisión estructurada: Project Strengths destacó utilidades tipadas y la optimización de fuentes, y el agente preguntó "Would you like me to apply these fixes for you?" antes de editar. Tu custom agent hereda esa disciplina cuando su prompt exige el mismo formato de salida.
El agente revisor en acción: lista las fortalezas del proyecto — utilidades tipadas, next/image, patrones de App Router — y pregunta si aplicar sus correcciones.Ver en 10:15 - 18
Pruébalo desde el IDE y la CLI
Con mainAgent: true el especialista aparece en el selector de entrada — selecciónalo y pregunta "What are your tools?" para verificar la caja de herramientas; una lista tools rota falla al instante con un error de ejecución, el smoke test más rápido. En la CLI, /agents lista los agentes descubiertos y Alt+J abre el panel de sub-agentes para seguir el trabajo delegado en vivo.
- 19
Commitea la carpeta para que el equipo tenga los mismos especialistas
Todo lo que el especialista necesita vive ya en el repositorio: .agents/agents/ para las definiciones de agentes, más la carpeta .agent con rules, skills y workflows junto al código. Haz commit y cada compañero — y cada ejecución de CI — descubre los mismos especialistas con los mismos límites. Las definiciones personales en ~/.gemini se quedan fuera del repositorio: son preferencias de máquina.
El explorador de Antigravity con la carpeta .agent expandida — agent, rules, skills y workflows junto al código, listos para el commit.Ver en 9:04 - 20
Entiende qué capa hace qué
Las tres capas de customización complementan al archivo del agente en vez de reemplazarlo: Rules son estándares siempre activos (o por patrón), Workflows son procedimientos con comando de barra, Skills son conocimiento experto autodescubierto. El custom agent es la identidad que los une — un archivo markdown que da a un trabajo recurrente nombre, caja de herramientas y memoria.
Una tabla comparativa de Rules, Workflows y Skills: los estándares de código se aplican solos, la automatización va con comandos de barra y el conocimiento experto se descubre cuando toca.Ver en 10:20