Tutoriel Antigravity Custom Agents : créez vos propres spécialistes
Transformez les tâches récurrentes en sub-agents enregistrés : un fichier markdown avec frontmatter YAML sous .agents/agents, une liste d'outils bornée, puis des règles, workflows et skills par-dessus — chaque capture d'écran vient d'un vrai enregistrement.
L'essentiel en bref
- Un custom agent tient dans un fichier markdown : frontmatter YAML (name, description, model, tools) plus un corps de prompt système — enregistrez le spécialiste récurrent une fois, plus besoin de le réexpliquer à chaque session.
- Les agents de workspace vivent dans .agents/agents/<nom>.md et partent avec le dépôt ; les personnels dans ~/.gemini/config/agents/ s'appliquent à tous les projets de la machine.
- tools n'accepte que les vrais noms d'outils Antigravity — view_file, grep_search, list_dir — et un nom erroné fait planter l'agent au démarrage ; subagent: true le rend délégable, mainAgent: true l'ajoute au sélecteur de saisie.
- Test rapide avec "What are your tools?" dans le sélecteur de l'IDE, déléguez depuis le chat principal, ou inspectez avec /agents et Alt+J en CLI — puis ajoutez règles, workflows et skills.
Google Antigravity Livestream: Remote Control and Custom Agents
Chaîne:Google Antigravity47:43
Antigravity Customization Features That 10X Your Coding Speed
Chaîne:Code A Program11:02
Defining Custom Subagents (.md) — Antigravity Docs
Docs:antigravity.googleDocs
Les captures d'écran sont des stills de l'enregistrement de Code A Program (crédité ci-dessus) ; le parcours de création du fichier d'agent est documenté d'après le livestream officiel de Google et la doc subagents d'Antigravity — aucun enregistrement tiers propre ne le couvre encore.
La vérification des faits s'appuie aussi sur les vidéos custom agents de Use AI with Tech Dad et AI with Surya. Toutes les marques appartiennent à Google ; ceci est un tutoriel indépendant, sans affiliation avec Google.
Du dossier vide au spécialiste de confiance
1 · Cadrer le spécialiste
- 1
Repérer un rôle digne d'être enregistré
Un custom agent mérite son fichier quand le même travail revient : un relecteur de code avec sa checklist fixe, un moderniseur de dépendances, un lanceur de tests, un mainteneur de docs. Si les instructions sont stables, différentes de votre assistant général, et que la boîte à outils se nomme à l'avance, enregistrez le rôle. Les demandes ponctuelles restent un simple prompt.
- 2
Le distinguer des sub-agents et des skills
Un sub-agent est le poste de travail : la session à laquelle votre agent principal délègue. Un custom agent est le profil enregistré qui peut occuper ce poste — ou qu'on interpelle directement. Les skills sont encore autre chose : elles empaquettent un savoir-faire que n'importe quel agent peut mobiliser, tandis qu'un custom agent change ses instructions centrales et ses accès outils. Pour un travail ponctuel, pas besoin de fichier ; Antigravity peut créer un sub-agent transitoire en pleine session via l'outil define_subagent.
- 3
Choisir la portée : dépôt ou machine
Antigravity découvre les .md de custom agents à trois endroits. Les customizations de workspace vivent dans .agents/agents/<nom>.md (ou .agents/agents/<nom>/agent.md) et voyagent avec le dépôt — parfait pour les conventions partagées. Les customizations globales vivent dans ~/.gemini/config/agents/<nom>.md et valent pour tous les projets de la machine — parfait pour vos spécialistes personnels. Les plugins peuvent embarquer des agents sous plugins/<nom_plugin>/agents/.
La page Rules de la doc Antigravity : les règles globales vivent dans ~/.gemini/GEMINI.md et valent pour tous les workspaces, les règles de workspace dans le dossier .agents — la même répartition que suivent les fichiers d'agents.Voir à 0:30
2 · Écrire le fichier d'agent
- 4
Créer le fichier d'agent
Dans votre projet, créez dossier et fichier d'un coup — le nom du fichier ou du dossier devient l'identité de l'agent, donc minuscules et tirets : .agents/agents/codereviewer/agent.md. Vous pouvez aussi demander à l'agent Antigravity de l'échafauder : dans le walkthrough officiel, un simple prompt "I have an idea for a custom agent" a renvoyé le chemin complet undefined/.agents/agents/codereviewer/agent.md et une définition prête à éditer.
- 5
Remplir le frontmatter YAML
Le frontmatter déclare l'identité et les limites du spécialiste. name doit être unique — c'est ce que vous @mentionnerez. description indique à Antigravity quand appeler le spécialiste : rédigez-la comme une annonce d'emploi. model: inherit conserve le palier de modèle du parent, et tools liste exactement ce que le rôle peut utiliser. Deux drapeaux complètent le tableau : subagent vaut true par défaut (délégable) et mainAgent false par défaut (passez-le à true pour le choisir directement dans le sélecteur de saisie).
- 6
Écrire le corps du prompt système
Tout ce qui suit le délimiteur du frontmatter devient les instructions système de l'agent. L'exemple officiel ouvre sur une persona ("You are an expert, meticulous Code Reviewer"), liste les responsabilités — correction, sécurité, performance, style — et se clôt sur un format de sortie strict : un verdict Summary, les Critical findings bloquants avec références de lignes, et les Suggestions non bloquantes. Un format de rapport stable rend ses résultats dignes de confiance.
---
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 · L'étendre et l'encadrer
- 7
Restreindre la boîte à outils avec de vrais noms d'outils
Le frontmatter tools prend une liste blanche explicite, et les noms doivent correspondre aux vrais outils d'Antigravity. Dans le walkthrough officiel, le fichier généré listait read — et l'agent est mort avec "Agent execution terminated due to error" jusqu'à correction en view_file. Tenez-vous-en à des noms comme view_file, grep_search et list_dir, et n'accordez au rôle que ce dont son travail a besoin ; un relecteur écrit rarement.
Un fichier de configuration du workspace listant les outils qu'un agent peut appeler — view_file, grep_search, read_file — le vocabulaire exact qu'attend la liste tools d'un custom agent.Voir à 4:44 - 8
Décider quand il intervient
Avec subagent: true (défaut), votre spécialiste est délégable : décrivez le travail à l'agent principal, il confie la tâche bornée au spécialiste dont le rapport revient dans la conversation principale. Les sub-agents délégués héritent des frontières de permissions du parent — commandes autorisées, périmètres de fichiers, réglages de sandbox — et les actions à approbation remontent dans l'interface principale. Passez aussi mainAgent à true et le spécialiste apparaît dans le sélecteur de saisie, prêt à être interrogé directement.
- 9
Ouvrir Customizations et nommer une règle
Les custom agents gagnent vite en pertinence quand vous ajoutez des règles maison. Dans l'IDE, ouvrez le menu "..." en haut du panneau d'agent et choisissez Customizations — le même panneau héberge Rules et Workflows. Sous Rules, créez une règle : les règles globales vivent dans ~/.gemini/GEMINI.md et valent pour tous les workspaces, les règles de workspace dans le dossier .agents du workspace ou de la racine git. Une règle est limitée à 12 000 caractères.
Le panneau Customizations du panneau d'agent d'Antigravity : l'onglet Rules est actif et un nouveau nom de règle se saisit avec le placeholder e.g. code-style-guide.Voir à 0:56 - 10
Choisir le mode d'activation
Chaque règle répond à une question : quand s'applique-t-elle ? Always On l'injecte dans chaque conversation ; Manual attend une @mention dans la zone de saisie ; Model Decision laisse l'agent la déclencher d'après sa description en langage naturel ; Glob ne l'applique qu'aux fichiers correspondant à un motif comme *.test.ts. Prenez le mode le plus étroit qui marche — une règle de relecture qui ne se déclenche que sur les diffs reste concentrée.
Le menu Activation Mode d'un éditeur de règles Antigravity avec les quatre options visibles — Always On, Manual, Model Decision et Glob.Voir à 1:04 - 11
Écrire le contenu de la règle
Les règles sont des contraintes en Markdown pur : "les commentaires expliquent pourquoi le code existe, pas ce qu'il fait", "JSDoc pour les fonctions", "aucun TODO qui traîne". Une règle, un seul propos — l'agent les lit à la lettre dans chaque conversation concernée. Les règles façonnent la manière de travailler ; les deux couches suivantes apportent procédures et savoir.
Un fichier de règle nommé comments.md dans l'éditeur Antigravity, Activation Mode sur Always On, prêt à recevoir les instructions Markdown que chaque conversation devra suivre.Voir à 1:02 - 12
Empaqueter les procédures récurrentes en workflows
Quand le spécialiste doit répéter une procédure en plusieurs étapes — nettoyer les branches fusionnées, couper une release, régénérer la doc API — enregistrez-la en workflow au lieu de retaper les étapes. Les workflows sont des fichiers markdown avec une description YAML en frontmatter, invoqués par commande slash : tapez /cleanup-branches et l'agent exécute chaque étape listée.
La section Workflows de la doc Antigravity : les fichiers de workflow vivent dans le dossier workflows de .agent et s'invoquent en chat par une commande /workflow-name.Voir à 5:40 - 13
Créer le fichier de workflow
Demandez à l'agent de l'échafauder, ou faites-le vous-même : mkdir -p .agent/workflows, puis cleanup-branches.md avec une courte description en frontmatter et des étapes numérotées. Dans l'exemple enregistré, les étapes vont de git fetch --prune à la suppression des branches fusionnées — et comme chaque étape est explicite, l'agent s'arrête et demande avant les opérations destructrices.
Une conversation Antigravity où l'agent lance mkdir -p .agent/workflows et nano, puis reçoit le markdown du workflow — frontmatter de description plus une checklist git de dix étapes.Voir à 6:20
4 · Tester, livrer, distinguer les couches
- 14
Voir le garde-fou en action
L'exécution enregistrée se termine par l'agent qui rapporte la branche récupérée, désigne feature/about-page comme fusionnée et supprimable, et demande "Would you like me to proceed with deleting these?" avant d'y toucher. Ce réflexe d'approbation vaut aussi pour les custom agents délégués : les actions nécessitant une autorisation remontent dans l'interface principale — le spécialiste ne franchit jamais une limite en silence.
Le rapport du workflow : feature/about-page est fusionnée et supprimable sans risque, et l'agent demande "Would you like me to proceed?" avant de lancer git branch -d et git gc.Voir à 7:46 - 15
Lui apprendre une skill
Les règles façonnent le comportement ; les skills ajoutent du savoir. Une skill est un dossier avec un fichier SKILL.md — skills de workspace sous .agents/skills/<nom-skill>/, personnelles sous ~/.gemini/skills. Le name et la description du frontmatter disent à l'agent quand la skill est pertinente ; le corps porte les instructions complètes, scripts et références. Custom agents et skills se combinent : votre codereviewer peut s'appuyer sur une skill nextjs-reviewer pour les vérifications propres au framework.
La section Agent Skills de la doc Antigravity : créez un dossier dans l'un des répertoires de skills et ajoutez un fichier SKILL.md avec frontmatter YAML.Voir à 8:42 - 16
Rédiger le frontmatter du SKILL.md
Écrivez la description comme un déclencheur : "Reviews Next.js and TypeScript code for critical issues only — types, performance, security, and App Router patterns". Quand une demande correspond, l'agent charge la skill entière ; sinon, elle reste hors du chemin. Ce chargement progressif est exactement la raison pour laquelle la documentation de référence profonde va dans une skill plutôt que dans le prompt système de l'agent.
Un SKILL.md nextjs-reviewer dans l'éditeur Antigravity : le frontmatter YAML porte le nom de la skill et sa description — Reviews Next.js and TypeScript code for critical issues only.Voir à 9:16 - 17
Voir la skill se déclencher sur une vraie relecture
Dans la session enregistrée, demander à l'agent de relire le code Next.js l'a fait charger la skill de relecture, analyser la page et répondre avec une revue structurée : Project Strengths saluait les utilitaires typés et l'optimisation des polices, et l'agent demandait "Would you like me to apply these fixes for you?" avant d'éditer. Votre custom agent hérite de cette discipline quand son prompt exige le même format de sortie.
L'agent relecteur à l'œuvre : il liste les forces du projet — utilitaires typés, next/image, patterns App Router — et demande s'il doit appliquer ses correctifs.Voir à 10:15 - 18
Tester depuis l'IDE et la CLI
Avec mainAgent: true, le spécialiste apparaît dans le sélecteur de saisie — sélectionnez-le et demandez "What are your tools?" pour vérifier la boîte à outils ; une liste tools cassée échoue aussitôt avec une erreur d'exécution, le smoke test le plus rapide. En CLI, /agents liste les agents découverts et Alt+J ouvre le panneau des sub-agents pour suivre les délégations en direct.
- 19
Committer le dossier pour que l'équipe livre les mêmes spécialistes
Tout ce dont le spécialiste a besoin vit désormais dans le dépôt : .agents/agents/ pour les définitions d'agents, plus le dossier .agent avec rules, skills et workflows à côté du source. Commitez-les et chaque membre de l'équipe — chaque run de CI — découvre les mêmes spécialistes avec les mêmes limites. Les définitions personnelles dans ~/.gemini restent hors du dépôt : ce sont des préférences machine.
L'explorateur Antigravity avec le dossier .agent déplié — agent, rules, skills et workflows à côté du code source, prêts à être commités.Voir à 9:04 - 20
Savoir quelle couche fait quoi
Les trois couches de customisation complètent le fichier d'agent sans le remplacer : Rules ce sont des standards de code toujours actifs (ou déclenchés par motif), Workflows des procédures en commande slash, Skills un savoir expert découvert automatiquement. Le custom agent est l'identité qui les relie — un fichier markdown qui donne à un travail récurrent un nom, une boîte à outils et une mémoire.
Un tableau comparatif Rules vs Workflows vs Skills : les standards de code s'appliquent automatiquement, l'automatisation passe par commandes slash, le savoir expert se découvre au besoin.Voir à 10:20