Guide
Agent Skills : des compétences chargées à la demande
Comment fonctionnent les Agent Skills d'Anthropic : trois niveaux de chargement, coût en jetons, structure du SKILL.md, limites et sécurité.
Mis à jour le
Une skill (compétence d'agent) est un dossier qui contient des instructions, éventuellement des scripts et des documents de référence, que l'agent charge seulement quand la tâche le demande. C'est une réponse au problème que les pages sur la mémoire et le coût posent : les instructions chargées occupent du contexte et peuvent augmenter la consommation facturée, selon le modèle et le cache. Ce qui suit résume la documentation d'Anthropic, relue le 16/11/2026.
Pour un besoin centré sur les réponses à partir de documents, comparez aussi les fonctions de personnalisation d’ALMA. Distinguez la configuration d’un assistant des fichiers de compétence exécutables : demandez quel mécanisme votre outil accepte réellement.
Trois niveaux de chargement
La documentation parle de « divulgation progressive » : l'agent charge l'information par étapes.
| Niveau | Quand | Coût en contexte | Contenu |
|---|---|---|---|
| 1. Métadonnées | toujours, au démarrage | environ 100 jetons par skill | name et description du SKILL.md |
| 2. Instructions | quand la skill est déclenchée | moins de 5 000 jetons | corps du SKILL.md |
| 3. Ressources | au besoin | rien tant que non lues | fichiers joints, scripts |
Ces valeurs décrivent le modèle de chargement présenté par Anthropic ; elles ne constituent pas un forfait de facturation ni un plafond automatique pour vos propres fichiers. Mesurez les instructions et sorties réellement chargées.
Le déroulé de l’exemple de la documentation, avec une skill de traitement de PDF : au démarrage, seule la ligne de description est dans le message système ; la demande « extrais le texte de ce PDF » fait lire le SKILL.md par une commande bash ; le guide de remplissage de formulaires, inutile ici, n'est pas lu. L’exécution d’un script n’injecte pas automatiquement son code dans le contexte ; sa sortie y entre. Si l’agent ouvre aussi le fichier pour l’inspecter, son contenu sera naturellement lu.
Écrire le fichier
Chaque skill exige un fichier SKILL.md avec un en-tête YAML (name et description) :
name: 64 caractères au plus, lettres minuscules, chiffres et tirets seulement, sans les mots réservés « anthropic » et « claude » ;description: non vide, 1 024 caractères au plus, sans balises XML. Elle doit dire ce que fait la skill et quand l'utiliser, car c'est elle que l'agent compare à la demande pour décider de la déclencher.
Où ça fonctionne
- API Claude : on liste des
skill_idsdans le paramètrecontainer, avec l'outil d'exécution de code. L'environnement n'a pas d'accès réseau et on ne peut pas y installer de paquets à l'exécution. Les skills personnalisées sont partagées dans tout l'espace de travail. - Claude Code : des dossiers dans
~/.claude/skills/(personnel) ou.claude/skills/(projet). - Agents gérés : les skills s'attachent dans la liste
skillsde l'agent. - claude.ai : selon les offres, avec l'exécution de code activée.
Les skills ne se synchronisent pas entre ces surfaces : chacune se gère séparément. Dans l'Agent SDK, les descriptions de skills se chargent au démarrage via les sources de réglages et le contenu complet seulement à l'appel (documentation de la boucle de l'agent), voir le Claude Agent SDK.
Vérifier le déclenchement
Préparez une demande qui doit activer la compétence et une demande voisine qui ne doit pas l’activer. Observez les fichiers effectivement lus. Si la sélection se trompe, révisez d’abord la description et les conditions d’utilisation avant d’ajouter des instructions au corps du guide.
Tester le contenu après chargement
Le déclenchement correct n’est que le premier contrôle. Pour une compétence de préparation de devis, fournissez un dossier complet, puis un dossier sans prix validé. Vérifiez que la procédure produit le document attendu dans le premier cas et signale l’information manquante dans le second. Un script doit aussi rendre ses erreurs compréhensibles : fichier absent, format non reconnu, dépendance indisponible.
Conservez une version identifiable de la compétence avec vos essais. Une modification de script ou de référence peut changer le résultat sans modifier la description affichée à l’agent. Enfin, les permissions de l’environnement restent séparées du guide : écrire « ne pas envoyer » dans le SKILL.md n’enlève pas techniquement un outil d’envoi.
Précautions
La documentation assimile l'installation d'une skill à celle d'un logiciel : une skill malveillante peut diriger l'agent vers des appels d'outils ou du code qui ne correspondent pas à son objet, avec risque de fuite de données. Elle demande d'auditer tous les fichiers (instructions, scripts, images), de se méfier des skills qui récupèrent des données sur des adresses externes, et d'être particulièrement prudent en production. Elle indique aussi que les skills ne sont pas couvertes par les accords de conservation zéro des données : leurs données suivent la politique standard.
Skill, outil ou prompt ?
Cette comparaison est la lecture de ce site, pas celle de la documentation :
- une règle qui doit s'appliquer à toute conversation reste dans le message système ;
- une procédure utile à certaines tâches, avec ses modèles et ses scripts, est une bonne candidate à une skill ;
- une action sur un système externe reste un outil appelé par votre code.
Pour une présentation côté utilisateur, sans code, voir créer une skill Claude par la conversation.
Questions fréquentes
Quelle différence entre une skill et une instruction dans le prompt ?
D'après la documentation, un prompt est une instruction de niveau conversation pour une tâche ponctuelle, alors qu'une skill se charge à la demande : seuls son nom et sa description sont toujours présents.
Combien une skill coûte-t-elle en contexte ?
Environ 100 jetons par skill pour les métadonnées toujours chargées, un corps de SKILL.md présenté à moins de 5 000 jetons dans son tableau de conception, une fois la skill déclenchée, et rien pour les fichiers joints tant qu'ils ne sont pas lus.
Peut-on installer n'importe quelle skill ?
La documentation recommande de n'utiliser que des skills de confiance (les siennes ou celles d'Anthropic) et d'auditer tous les fichiers d'une skill d'origine inconnue avant usage.
Sources
Pages consultées pour écrire cet article :