GitHub Copilot : instructions, prompt files et agents

Par défaut, GitHub Copilot ignore les conventions de votre projet : il propose du code générique que vous corrigez sans cesse. VS Code permet de le personnaliser de A à Z avec trois leviers : des instructions toujours appliquées, des prompt files réutilisables, et des custom agents spécialisés. Ce guide montre quand utiliser chacun, où placer les fichiers, comment les activer et vérifier qu'ils agissent. Prérequis : Copilot déjà installé dans VS Code.

Ce que vous allez apprendre

Écrire des instructions que Copilot applique automatiquement
Créer un prompt file réutilisable, invoqué par une commande /
Définir un custom agent avec des outils restreints
Activer et vérifier ces personnalisations dans VS Code

Prérequis

GitHub Copilot installé et actif dans VS Code
Un projet ouvert comme workspace (un dossier avec du code)
Savoir éditer un fichier Markdown et un peu de YAML (le frontmatter)

Les trois leviers de personnalisation

Avant de plonger, situez les trois mécanismes : ils ne servent pas au même moment.

Levier	Fichier	Déclenchement	Pour quoi
Instructions	`copilot-instructions.md`, `*.instructions.md`, `AGENTS.md`	automatique, à chaque requête du chat	imposer vos standards (style, frameworks, tests)
Prompt files	`*.prompt.md`	manuel, via `/nom` dans le chat	une tâche réutilisable (générer un endpoint, une revue)
Custom agents	`*.agent.md`	en choisissant l'agent	un persona avec des outils restreints (revue, planification)

La règle pratique : un standard toujours vrai va dans les instructions ; une action ponctuelle dans un prompt file ; un rôle avec des outils limités dans un custom agent.

Instructions : des standards toujours appliqués

Les instructions décrivent vos conventions une fois, et Copilot les respecte à chaque échange dans le chat. Il existe trois formats complémentaires.

Le fichier global `copilot-instructions.md`

C'est le point de départ : un fichier .github/copilot-instructions.md à la racine du dépôt, en Markdown, appliqué à toutes les requêtes du chat dans ce workspace.

# Instructions Copilot pour ce dépôt

Ce projet est une API REST FastAPI de gestion de bibliothèque.

- Toujours typer les fonctions publiques (type hints obligatoires).
- snake_case pour les fonctions, PascalCase pour les classes.
- Valider les entrées avec Pydantic, jamais le corps brut d'une requête.
- Chaque endpoint a un test pytest (cas nominal + cas d'erreur).

Gardez chaque instruction courte et autoportante : une phrase, une règle. La documentation recommande des consignes simples, et GitHub limite ce fichier à l'équivalent de deux pages côté github.com. Un pavé de contexte dilue les règles importantes.

Les instructions ciblées avec `applyTo`

Pour des règles qui ne valent que pour certains fichiers, créez des fichiers *.instructions.md dans .github/instructions/, avec un frontmatter applyTo (un motif glob) :

---
applyTo: "tests/**/*.py"
description: "Conventions de test"
---

- Utiliser pytest et des fixtures, pas de classes de test.
- Un test par comportement, nommé test_<comportement>.
- Couvrir le happy path ET au moins un cas d'erreur (404, 422).

`AGENTS.md` : le standard partagé entre outils

VS Code lit aussi le standard AGENTS.md (et CLAUDE.md), placé à la racine du dépôt, comme des instructions toujours actives. L'intérêt : le même fichier sert à Copilot, à Claude Code et à d'autres agents, au lieu de dupliquer vos conventions. Côté github.com, l'AGENTS.md le plus proche dans l'arborescence prend la priorité.

Prompt files : des commandes réutilisables

Un prompt file est une consigne enregistrée que vous déclenchez à la demande, comme une commande. Placez les fichiers *.prompt.md dans .github/prompts/.

---
description: "Générer un endpoint FastAPI complet avec son test"
agent: agent
---

Crée un endpoint FastAPI pour la ressource ${input:ressource}.

- Route avec validation Pydantic et gestion des erreurs 404/422.
- Réponse JSON typée.
- Un test pytest (cas nominal + cas absent) dans tests/.

Respecte les conventions du dépôt.

Le frontmatter accepte notamment description, agent (ask, agent, plan ou un agent personnalisé), tools et model. Dans le corps, les variables comme ${input:ressource} (saisie demandée à l'exécution) et ${selection} (le code sélectionné) rendent le prompt générique.

Pour l'invoquer, tapez / suivi du nom du prompt dans le chat (par défaut, le nom du fichier), ou lancez la commande « Chat: Run Prompt ».

Custom agents : des personas avec outils restreints

Les custom agents (anciennement « chat modes », fichiers .chatmode.md désormais renommés .agent.md) regroupent dans un seul fichier une spécialisation et une liste d'outils autorisés. Placez les fichiers *.agent.md dans .github/agents/.

---
description: "Agent de revue de sécurité du code Python"
tools: ['search', 'codebase']
---

Tu es un relecteur sécurité. Pour le code sélectionné, signale :
secrets en dur, injections, entrées non validées, usage de eval/exec.
Donne le correctif. Ne modifie aucun fichier.

L'intérêt d'un agent dédié est le cadrage : un agent « revue » qui n'a pas le droit d'écrire ne risque pas de modifier votre code, il se contente de signaler. C'est l'équivalent Copilot des subagents Claude Code. Créez-en un via la commande « Chat: New Custom Agent ».

Organiser tout ça dans `.github/`

Sur un vrai projet, l'ensemble vit dans le dépôt et se partage par git :

AGENTS.md
Répertoire.github/
- copilot-instructions.md
- Répertoireinstructions/
  - tests.instructions.md
- Répertoireprompts/
  - generer-endpoint.prompt.md
- Répertoireagents/
  - revue-securite.agent.md

Tout est versionné : toute l'équipe hérite des mêmes standards, prompts et agents en clonant le dépôt. C'est le principal avantage par rapport à une configuration personnelle dispersée.

Activer et vérifier

Les fichiers d'instructions et de prompts sont reconnus dans leurs emplacements par défaut. Quelques réglages (settings.json) ajustent le comportement :

{
  "chat.instructionsFilesLocations": [".github/instructions"],
  "chat.promptFilesLocations": [".github/prompts"],
  "chat.agentFilesLocations": [".github/agents"],
  "github.copilot.chat.commitMessageGeneration.instructions": [
    { "text": "Messages au format Conventional Commits." }
  ]
}

Vous pouvez aussi générer un squelette d'instructions par analyse du projet avec la commande /init dans le chat, ou créer les fichiers via « Chat: New Instructions File » et « Chat: New Prompt File ».

Pour vérifier qu'une instruction a bien agi, ouvrez la section References de la réponse du chat : elle liste les fichiers d'instructions réellement utilisés. Si rien n'apparaît, l'instruction n'a pas été chargée.

Pièges courants

Symptôme	Cause probable	Correction
L'instruction n'a aucun effet	Fichier au mauvais endroit	`.github/copilot-instructions.md`, sous-fichiers dans `.github/instructions/`
Un `*.instructions.md` est ignoré	`applyTo` absent ou glob qui ne matche pas	Ajouter `applyTo` et vérifier le motif
Le prompt ne s'affiche pas en `/nom`	Mauvais dossier ou suffixe	Fichier `.prompt.md` dans `.github/prompts/`
Les suggestions inline n'obéissent pas	Les instructions ne couvrent que le chat	Utiliser le chat pour le code soumis aux règles
Règles contradictoires	Plusieurs sources se chevauchent	Priorité personnel puis dépôt ; garder les règles courtes

À retenir

Trois leviers : instructions (toujours appliquées), prompt files (à la demande), custom agents (persona + outils).
Le global .github/copilot-instructions.md s'applique à tout le chat ; les *.instructions.md ciblent via applyTo.
AGENTS.md mutualise vos conventions entre Copilot, Claude Code et d'autres agents.
Un prompt file s'invoque par /nom ; un custom agent restreint les outils (ex revue en lecture seule).
Les instructions agissent dans le chat, pas sur la complétion inline ; vérifiez via la section References.
Tout vit dans .github/, versionné, partagé par toute l'équipe.

Prochaines étapes

GitHub Copilot : les bases Installer et utiliser Copilot dans VS Code

Agent Skills : le standard portable Le format de personnalisation commun aux agents IA

Configurer CLAUDE.md L'équivalent AGENTS.md côté Claude Code

Conventional Commits La convention à imposer via une instruction de commit