Concevoir des capacités réutilisables et efficaces pour les agents IA
Nicolas HERNANDEZ - M2 ATAL - Novembre 2026
Agent Skills
« Si un agent sait déjà lire un PDF ou écrire du SQL, que reste-t-il à lui apprendre ? »
Les conventions du projet, les cas limites et les procédures spécifiques à votre équipe qu’il ne peut pas deviner.
Les Skills, une manière d’équiper un agent avec une expertise procédurale réutilisable spécifique à votre contexte.
Objectifs d’apprentissage
À l’issue des deux séances, vous serez capables de :
Concevoir une Skill dans le format standard Agent Skill
Développer une Skill à partir d’une expertise réelle, puis la raffiner par l’exécution.
Optimiser une description : comprendre son rôle dans le déclenchement, construire un jeu de requêtes d’évaluation, éviter le surapprentissage.
Mobiliser les techniques d’instruction : gotchas, templates, checklists, boucles de validation, plan-validate-execute, scripts embarqués.
Structurer le contenu : répartir l’information entre SKILL.md, references/, scripts/ et assets/ en exploitant la progressive disclosure.
Calibrer le contrôle laissé à l’agent selon la sensibilité de la tâche.
Plan et répartition du temps
Séance
Partie
Source principale
Durée
1
I. Le format d’une Skill
Specification
20 min
1
II. Concevoir et développer
Best practices
20 min
1
III. Structurer le contenu
Specification + Best practices
20 min
1
Atelier 1 — assembler une Skill
—
15 min
2
IV. Écrire et optimiser la description
Optimizing descriptions
30 min
2
V. Calibrer le contrôle
Best practices
15 min
2
VI. Techniques d’instruction
Best practices
15 min
2
Atelier 2 — optimiser une description
—
15 min
2
Synthèse
—
5 min
Convention de lecture
Légende des slides
Source contenu fidèle à la page citée en bas de slide
Cours reformulation, synthèse ou exercice conçu pour le cours
Chaque slide « Source » indique la page et la section d’origine. Les exemples (PDF, base de données, CSV) viennent tous de ces trois pages.
Pourquoi un agent généraliste ne suffit-il pas toujours ?
Un modèle de langue généraliste dispose de connaissances générales, mais ne connaît pas nécessairement :
les conventions d’un projet ;
les procédures propres à une organisation ;
les schémas de données utilisés ;
les cas limites et les erreurs récurrentes.
LLM seul
Prompt ponctuel
Contexte à répéter
Conventions implicites
Résultat potentiellement variable
Agent + Skill
Procédure réutilisable
Contexte organisé
Règles explicites
Workflow plus reproductible
Une Skill externalise un savoir-faire que l’agent ne doit pas avoir à reconstruire à chaque interaction.
D’une fonctionnalité Claude à un standard ouvert
timeline
title Évolution du standard Agent Skills
2025-10 : Présentation par Anthropic
: Skills pour l'écosystème Claude
2025-12 : Publication comme standard ouvert
: Objectif de portabilité
2026-10 : Don annoncé à l'Agentic AI Foundation
: Gouvernance ouverte
Développé initialement par Anthropic.
Publié comme standard ouvert en décembre 2025.
Don du standard à l’Agentic AI Foundation (AAIF) annoncé le 22 octobre 2026.
Question directrice : qu’impose réellement le format, et que laisse-t-il libre ?
Une Skill est un répertoire
Une Skill est un répertoire contenant au minimum un fichier SKILL.md.
skill-name/├── SKILL.md # Required: metadata + main instructions for the agent├── scripts/ # Optional: executable code├── references/ # Optional: complementary documentation├── assets/ # Optional: templates, static resources└── ... # Any additional files or directories
Seul le fichier SKILL.md est obligatoire. Tout le reste est convention d’organisation.
Source Specification › Directory structure
Une Skill est un fichier SKILL.md
Le fichier doit contenir un frontmatter au format YAML, suivi d’un corps au format Markdown.
---name: pdf-processingdescription: Extract PDF text, fill forms, merge files. Use when handling PDFs.---## Extract PDF textUse pdfplumber. For scanned documents, fall back to pdf2image + pytesseract.## Gotchas- When reading multi-column layouts or text boxes, flag any risk of the reading order being reversed.## Form filling workflow <!-- plan-validate-execute + checklist -->Progress:-[] 1. `python scripts/analyze_form.py input.pdf` → `form_fields.json`-[] 2. Create `field_values.json`-[] 3. `python scripts/validate_fields.py form_fields.json field_values.json`-[]4. Fill: `python scripts/fill_form.py input.pdf field_values.json output.pdf`If step 3 fails, revise `field_values.json` and re-validate.Read `references/FORMS.md` for non-standard form formats.
Cours Assemblage à partir des exemples de Specification (frontmatter) et de Best practices (extraction, gotchas, workflow de formulaire)
Le champ name
Règles
1 à 64 caractères
lettres minuscules unicode alphanumériques (a-z, 0-9) et tirets
décrit ce que fait la Skill, pour quel objectifetquand l’utiliser ;
inclut des mots-clés qui aident l’agent à déclencher le chargement de la Skill ;
non vide, 1 à 1024 caractères ;
chargé au démarrage, vient peupler le catalogue des descriptions de Skills disponibles.
Bon exemple PDF
description: Extracts text and tables from PDF files, fills PDF forms, and merges multiple PDFs. Use when working with PDF documents or when the user mentions PDFs, forms, or document extraction.
1–500 car. ; seulement en cas d’exigences spécifiques
Requires git, docker, jq, and access to the internet
metadata
Table chaîne → chaîne ; noms de clés plutôt uniques
author: example-org, version: "1.0"
allowed-tools
Liste séparée par des espaces ; support variable
Bash(git:*) Bash(jq:*) Read
---name: pdf-processingdescription: Extract PDF text, fill forms, merge files. Use when handling PDFs.license: Apache-2.0metadata:author: example-orgversion:"1.0"---
Corps : aucune restriction de format. Sections recommandées :
des instructions étape par étape ;
des exemples d’entrées et de sorties ;
des cas limites et des erreurs fréquentes.
Le fichier est chargé en entier dès l’activation (identification d’une référence à une Skill sur la base de sa description).
moins de 500 lignes et moins de 5 000 tokens recommandés ;
Une instruction vague
Analyze the ML experiment results.
Une procédure opérationnelle
1. Inspect the experiment configuration files.2. Verify that runs follow the same evaluation protocol.3. Check that all expected metrics are available.4. Aggregate comparable runs.5. Report missing data and inconsistencies.6. Produce a structured experiment report.Never infer missing metric values.
Répertoires optionnels
Références ciblées dans le corps de la Skill chargées à la demande.
Répertoire
Contenu
Exigences
scripts/
Code exécutable (Python, Bash, JavaScript… selon le client)
Autonome ou dépendances documentées ; messages d’erreur utiles ; cas limites gérés
references/
REFERENCE.md, FORMS.md, fichiers par domaine (finance.md, legal.md…)
Fichiers focalisés : chargés à la demande, donc petits = moins de contexte
assets/
Templates, images, données (tables de correspondance, schémas)
Source : Best practices for skill creators — Start from real expertise, Refine with real execution.
Question directrice : d’où vient la valeur d’une Skill, et comment la faire mûrir ?
Le piège : générer une Skill sans contexte
Demander à un LLM de produire une Skill à partir de ses seules connaissances générales donne des procédures vagues et génériques.
Ce qu’on obtient
« handle errors appropriately »
« follow best practices for authentication »
Ce qui fait la valeur
les patterns d’API précis
les cas limites
les conventions de projet
Une Skill efficace est ancrée dans une expertise réelle : l’enjeu est d’alimenter sa création en contexte spécifique au domaine.
Source Best practices › Start from real expertise
Voie 1 : extraire d’une tâche réalisée
Réaliser une vraie tâche en conversation avec un agent (en fournissant contexte, corrections et préférences), puis extraire le schéma réutilisable.
Quatre éléments à repérer :
Élément
Question à se poser
Steps that worked
Quelle séquence d’actions a mené au succès ?
Corrections you made
Où ai-je recadré l’agent ? (« utilise la bibliothèque X plutôt que Y », « vérifie le cas Z »)
Input/output formats
À quoi ressemblaient les données en entrée et en sortie ?
Context you provided
Quels faits, conventions ou contraintes de projet l’agent ne connaissait-il pas ?
Source Best practices › Start from real expertise › Extract from a hands-on task
Voie 2 : synthétiser à partir d’artefacts existants
Fournir à un LLM un corpus de connaissances propre au projet et lui demander de synthétiser la Skill.
Bonnes sources
documentation interne, runbooks, guides de style ;
spécifications d’API, schémas, fichiers de configuration ;
commentaires de revue de code et issue trackers (préoccupations récurrentes) ;
historique de versions, surtout les correctifs ;
cas d’échec réels et leur résolution.
Exemple de la documentation
Une Skill de data pipeline synthétisée à partir de vos rapports d’incident et runbooks fera mieux qu’une Skill issue d’un article générique « data engineering best practices » : elle capture vos schémas, vos modes de défaillance et vos procédures de reprise.
Le critère n’est pas la quantité de sources, mais leur spécificité au projet.
Source Best practices › Start from real expertise › Synthesize from existing project artifacts
Raffiner par l’exécution
Le premier jet d’une Skill nécessite en général des ajustements. Procédure :
Exécuter la Skill sur de vraies tâches.
Réinjecter dans le processus de création tous les résultats, pas seulement les échecs.
Se demander : qu’est-ce qui a déclenché des faux positifs ? Qu’a-t-on manqué ? Que peut-on supprimer ?
Une seule passe exécuter-puis-réviser améliore déjà nettement la qualité ; les domaines complexes en demandent plusieurs.
Lire les traces d’exécution, pas seulement les sorties finales. Un agent qui perd du temps révèle souvent : des instructions trop vagues, des instructions inapplicables suivies quand même, ou trop d’options sans défaut clair.
Source Best practices › Refine with real execution
Cycle de développement d’une Skill
flowchart LR
A["Tâche réelle<br/>ou artefacts de projet"] --> B["Skill v0<br/>(synthèse)"]
B --> C["Exécution<br/>sur tâches réelles"]
C --> D["Lecture des traces<br/>faux positifs, oublis,<br/>contenu inutile"]
D --> E["Révision :<br/>ajouter / couper /<br/>préciser"]
E --> C
Observation dans les traces
Correction envisageable
L’agent essaie plusieurs approches
Préciser l’instruction ; ajouter un exemple
L’agent suit une consigne inutile
Couper ou conditionner la consigne
L’agent hésite entre outils
Imposer un défaut
L’agent réinvente chaque fois la même logique
Écrire un script (partie VI)
Cours Synthèse du cycle à partir de Best practices › Refine with real execution
Question directrice : que mettre dans SKILL.md, et que déporter ailleurs ?
Le contexte est une ressource partagée
Quand une Skill s’active, tout le corps de SKILL.md entre dans la fenêtre de contexte, avec :
l’historique de la conversation ;
le contexte système ;
les autres Skills actives.
Chaque token de la Skill entre en concurrence pour l’attention avec tout le reste.
Concevoir une Skill, c’est arbitrer : ce qui est lu à chaque exécution, et ce qui est lu à la demande.
Source Best practices › Spending context wisely
Ajouter ce que l’agent ignore, omettre ce qu’il sait
Trop verbeux à éviter
## Extract PDF textPDF (Portable Document Format) filesare a common file format that containstext, images, and other content. Toextract text from a PDF, you'll need touse a library. pdfplumber is recommendedbecause it handles most cases well.
Direct recommandé
## Extract PDF textUse pdfplumber for text extraction.For scanned documents, fall back topdf2image with pytesseract.```pythonimport pdfplumberwith pdfplumber.open("file.pdf") as pdf: text = pdf.pages[0].extract_text()```
Test : « L’agent se tromperait-il sans cette instruction ? » Si non, couper. Si doute, tester.
Source Best practices › Spending context wisely › Add what the agent lacks, omit what it knows
Délimiter l’unité et rester modéré
Des unités cohérentes
Choisir le périmètre comme on choisit ce que fait une fonction.
Périmètre
Conséquence
Trop étroit
Plusieurs Skills à charger pour une seule tâche : surcoût et risque d’instructions conflictuelles
Trop large
Activation difficile à déclencher avec précision
Cohérent
Interroger une base de données et mettre en forme les résultats peut former une unité ; y ajouter l’administration de la base est probablement trop
Un niveau de détail modéré
Une Skill exhaustive peut nuire : l’agent peine à extraire ce qui est pertinent et peut suivre des pistes inutiles. Des consignes concises, par étapes, avec un exemple fonctionnel surpassent souvent une documentation exhaustive.
Source Best practices › Design coherent units ; Aim for moderate detail
Découper : dire à l’agent quand charger chaque fichier
Règle : SKILL.md contient les instructions nécessaires à chaque exécution ; le reste va dans references/, assets/ ou scripts/.
Efficace conditionnel
Read `references/api-errors.md`if the API returns a non-200status code.
Peu utile générique
See references/ for details.
L’agent charge ainsi le contexte à la demande plutôt qu’en amont : c’est l’esprit de la progressive disclosure.
Source Best practices › Structure large skills with progressive disclosure
Application : architecture d’une Skill de traitement de PDF
Cours Arborescence assemblée à partir des noms de fichiers cités dans Specification (REFERENCE.md, FORMS.md) et Best practices (scripts du workflow de formulaire)
Atelier 1 — Assembler une Skill organise-voyage
15 minutesBinômesnom conçu pour le cours
Matériau (extraits de la documentation)
Soit le prompt
ROLE : agent de voyage spécialisé dans les séjours insolites en Islande.
CONTEXT : 7 jours · budget maximum 2 000 € · randonnée modérée.
TASK : propose 3 itinéraires insolites.
STEPS : 1. Extrait les contraintes. 2. Génère les itinéraires. 4. Contrôle.
OUTPUT : tableau Markdown + total par itinéraire.
Gotcha 1 : incompatibilité entre les contraintes
Gotcha 2 : des informations manquantes
Livrable
Un frontmatter valide (name, description ≤ 1024 car.).
Un SKILL.md de moins de 500 lignes : procédure + gotchas.
Une décision argumentée : que mettre dans references/ et assets/ ?
Une phrase qui borne le périmètre (qu’exclut la Skill ?).
Correction
IV. Écrire et optimiser la description
Séance 230 min
Source : Optimizing skill descriptions — How skill triggering works, Writing effective descriptions, Designing trigger eval queries, Testing whether a description triggers, Avoiding overfitting, The optimization loop, Applying the result.
Question directrice : comment s’assurer que la Skill est appelée au bon moment, et seulement alors ?
Comment fonctionne le déclenchement
flowchart LR
A["Démarrage :<br/>name + description<br/>de chaque Skill"] --> B["Requête<br/>utilisateur"]
B --> C{"La tâche correspond<br/>à une description ?"}
C -->|"oui"| D["Lecture du<br/>SKILL.md complet"]
C -->|"non"| E["Travail sans la Skill"]
La description porte toute la charge du déclenchement.
Description sous-spécifiée → la Skill ne se déclenche pas quand il le faudrait.
Description trop large → elle se déclenche quand elle ne devrait pas.
Nuance : un agent ne consulte en général une Skill que pour les tâches hors de portée de ses outils de base. Un simple « lis ce PDF » peut ne pas la déclencher, même avec une description parfaite.
Source Optimizing descriptions › How skill triggering works
Quatre principes d’écriture
Principe
Application
Impératif
Écrire « Use this skill when… » plutôt que « This skill does… » : l’agent décide d’agir, dis-lui quand agir
Intention utilisateur
Décrire ce que l’utilisateur veut obtenir, pas la mécanique interne de la Skill
Insistance
(plutôt en faire trop que pas assez) Lister explicitement les contextes d’usage, y compris quand l’utilisateur ne nomme pas le domaine
Concision
Quelques phrases à un court paragraphe ; limite dure de 1024 caractères
Formule « insistante » (voir l’avant/après CSV)
Ajouter une clause du type « même si l’utilisateur ne nomme pas explicitement le domaine » pour couvrir les requêtes qui décrivent le besoin sans le nommer.
description: > Analyze CSV and tabular data files — compute summary statistics, add derived columns, generate charts, and clean messy data. Use this skill when the user has a CSV, TSV, or Excel file and wants to explore, transform, or visualize the data, even if they don't explicitly mention "CSV" or "analysis."
Plus spécifique sur ce que fait la Skill (statistiques, colonnes dérivées, graphiques, nettoyage) et plus large sur le moment où elle s’applique (CSV, TSV, Excel, même sans mot-clé).
Source Optimizing descriptions › Applying the result (Before and after)
Construire le jeu de requêtes d’évaluation
Un jeu de requêtes réalistes, étiquetées should_trigger: true / false.
[{"query":"I've got a spreadsheet in ~/data/q4_results.xlsx with revenue in col C and expenses in col D — can you add a profit margin column and highlight anything under 10%?","should_trigger":true},{"query":"whats the quickest way to convert this json file to yaml","should_trigger":false}]
Taille cible : environ 20 requêtes, dont 8 à 10 qui doivent déclencher et 8 à 10 qui ne le doivent pas.
Domaine nommé (« analyse ce CSV ») ou besoin décrit sans le nommer (« mon chef veut un graphique à partir de ce fichier de données »)
Détail
Prompts brefs et messages riches (chemins de fichiers, noms de colonnes, contexte)
Complexité
Tâches à une étape et workflows à plusieurs étapes où la tâche concernée est noyée dans une chaîne plus longue
Les requêtes les plus utiles sont celles où la Skill aiderait, mais où le lien n’est pas évident : si la requête demande exactement ce que fait la Skill, toute description raisonnable déclenchera.
Requêtes négatives : privilégier les quasi-erreurs
Une bonne requête négative partage des mots-clés ou concepts avec la Skill mais demande autre chose : elle teste la précision de la description, pas sa seule largeur.
Négatifs faibles sans intérêt
« Write a fibonacci function » : manifestement hors sujet
« What’s the weather today? » : aucun recouvrement de mots-clés
Négatifs forts utiles
Mettre à jour les formules d’un budget Excel : partage « tableur » et « données », mais c’est de l’édition Excel, pas de l’analyse CSV
Écrire un script Python qui lit un CSV et insère chaque ligne dans PostgreSQL : implique du CSV, mais c’est de l’ETL de base de données
Réalisme
Inclure des chemins de fichiers, du contexte personnel, des détails précis (noms de colonnes, d’entreprises), un langage familier, des fautes occasionnelles.
Source Optimizing descriptions › Should-not-trigger queries ; Tips for realism
Tester : le déclenchement est-il observé ?
Installer la Skill de façon qu’elle soit découvrable par le client (le mécanisme varie : répertoire de Skills, fichier de configuration, option de ligne de commande).
Lancer chaque requête et observer si l’agent a chargé le SKILL.md (journaux d’exécution, historique d’appels d’outils).
Une requête « passe » si :
should_trigger = true et la Skill a été invoquée, ou
should_trigger = false et elle ne l’a pas été.
Plusieurs exécutions : le taux de déclenchement
Le comportement du modèle est non déterministe. Lancer chaque requête plusieurs fois (3 pour commencer) et calculer trigger rate = déclenchements / exécutions. Seuil par défaut : 0,5.
Source Optimizing descriptions › Testing whether a description triggers › Running multiple times
Éviter le surapprentissage : train / validation
Si on optimise sur toutes les requêtes, on obtient une description qui fonctionne pour ces formulations mais échoue sur de nouvelles.
Jeu
Part
Rôle
Train
≈ 60 %
Identifier les échecs et guider les révisions
Validation
≈ 40 %
Vérifier que les améliorations généralisent
Contraintes :
chaque jeu contient un mélange proportionnel de positifs et de négatifs ;
mélanger aléatoirement, puis figer la répartition entre les itérations ;
n’utiliser que les échecs du train pour réviser (que ce soit à la main ou en sollicitant un LLM).
Source Optimizing descriptions › Avoiding overfitting with train/validation splits
La boucle d’optimisation
flowchart TD
A["1. Évaluer la description<br/>sur train ET validation"] --> B["2. Identifier les échecs<br/>du TRAIN uniquement"]
B --> C["3. Réviser la description<br/>en généralisant"]
C --> D{"Tous les train passent<br/>ou plus de progrès ?"}
D -->|"non"| A
D -->|"oui"| E["5. Choisir l'itération<br/>au meilleur taux de réussite<br/>en VALIDATION"]
Révision (étape 3) :
positifs qui échouent → description trop étroite : élargir ou ajouter du contexte ;
négatifs qui déclenchent → trop large : préciser ce que la Skill ne fait pas, clarifier la frontière avec les capacités voisines ;
ne pas recopier les mots-clés des requêtes échouées (surapprentissage) : viser la catégorie générale qu’elles représentent.
Source Optimizing descriptions › The optimization loop
Appliquer le résultat et contrôler
Mettre à jour le champ description du frontmatter.
Vérifier la limite de 1024 caractères.
Vérifier le déclenchement : quelques prompts manuels, puis, pour plus de rigueur, 5 à 10 requêtes neuves (positives et négatives) jamais utilisées pendant l’optimisation.
Automatisation : la Skill skill-creator automatise la boucle : elle découpe le jeu de requêtes, évalue les taux de déclenchement en parallèle, propose des améliorations de description avec Claude et génère un rapport HTML en direct.
Une fois le déclenchement fiable, on évalue la qualité des sorties : voir le guide « Evaluating skill output quality ».
Source Optimizing descriptions › Applying the result ; Next steps
V. Calibrer le contrôle donné à l’agent
Séance 215 min
Source : Best practices › Calibrating control — Match specificity to fragility, Provide defaults not menus, Favor procedures over declarations.
Question directrice : quand laisser l’agent libre, et quand lui imposer une séquence exacte ?
Spécificité des consignes ↔︎ sensibilité de la tâche
Toutes les parties d’une Skill n’ont pas besoin du même degré de directivité. Calibrer chaque partie séparément ; la plupart des Skills mélangent les deux régimes.
Donner de la liberté
Quand plusieurs approches sont valides et que la tâche tolère la variation.
Expliquer le pourquoi : un agent qui comprend l’intention prend de meilleures décisions selon le contexte.
## Code review process1. Check all database queries for SQL injection (use parameterized queries)2. Verify authentication checks on every endpoint3. Look for race conditions in concurrent code paths4. Confirm error messages don't leak internal details
Être prescriptif
Quand l’opération est sensible, que la cohérence compte ou qu’une séquence précise s’impose.
## Database migrationRun exactly this sequence:```bashpython scripts/migrate.py --verify--backup```Do not modify the command or addadditional flags.
Source Best practices › Calibrating control › Match specificity to fragility
Fournir des défauts, pas des menus
Quand plusieurs outils peuvent convenir : choisir un défaut, mentionner brièvement les alternatives.
Menu à éviter
You can use pypdf, pdfplumber,PyMuPDF, or pdf2image...
Défaut + issue de secours recommandé
Use pdfplumber for text extraction:```pythonimport pdfplumber```For scanned PDFs requiring OCR, usepdf2image with pytesseract instead.
Un menu d’options égales retire à l’agent la décision que la Skill devrait trancher.
Source Best practices › Calibrating control › Provide defaults, not menus
Privilégier les procédures aux déclarations
Enseigner comment aborder une classe de problèmes, pas quoi produire pour une instance.
Réponse ponctuelle peu réutilisable
Join the `orders` table to`customers` on `customer_id`,filter where `region = 'EMEA'`,and sum the `amount` column.
Méthode réutilisable généralisable
1. Read the schema from`references/schema.yaml` to find relevant tables2. Join tables using the `_id` foreign key convention3. Apply any filters from the user's request as WHERE clauses4. Aggregate numeric columns as needed and format as a markdown table
Les détails spécifiques restent utiles : templates de sortie, contraintes (« never output Personnal Identifiable Information »), instructions propres à un outil. C’est l’approche qui doit généraliser.
Source Best practices › Calibrating control › Favor procedures over declarations
Grille de décision : quel niveau de contrôle ?
Question à se poser
Si oui
Forme d’instruction
Plusieurs approches sont-elles valides ?
Liberté
Objectifs + pourquoi
L’opération est-elle fragile ou irréversible ?
Prescriptif
Commande exacte, « ne pas modifier »
La cohérence entre exécutions est-elle critique ?
Prescriptif / script
Séquence fixe, template de sortie
Plusieurs outils conviennent-ils ?
Défaut
Un choix + une issue de secours
L’agent se trompera-t-il sans consigne ?
Instruction ciblée
Gotcha
L’agent le fait-il déjà bien ?
Aucune
Calibrer, c’est décider pour chaque bloc de la Skill : liberté, séquence imposée ou silence.
Cours Synthèse de Best practices › Calibrating control et Spending context wisely
VI. Techniques qui rendent une Skill efficace
Séance 215 min
Source : Best practices › Patterns for effective instructions — Gotchas, Templates, Checklists, Validation loops, Plan-validate-execute, Bundling reusable scripts.
L’agent fait une erreur raisonnable faute de connaître un fait d’environnement
SKILL.md
Templates de sortie
Format de sortie à respecter
Inline ou assets/
Checklists
Étapes sautées, dépendances
SKILL.md
Boucles de validation
Erreurs non détectées
SKILL.md + script ou référence
Plan-validate-execute
Opérations par lots ou destructives
SKILL.md + script de validation
Scripts embarqués
Logique réinventée à chaque exécution
scripts/
Tous les motifs ne sont pas nécessaires à chaque Skill : utiliser ceux qui correspondent à la tâche.
Source Best practices › Patterns for effective instructions
Gotchas : le contenu à plus forte valeur
Des faits d’environnement qui défient les hypothèses raisonnables : pas de conseils généraux, mais des corrections concrètes d’erreurs que l’agent commettra sinon.
## Gotchas- The `users` table uses soft deletes. Queries must include`WHERE deleted_at IS NULL` or results will include deactivated accounts.- The user ID is `user_id` in the database, `uid` in the auth service, and `accountId` in the billing API. All three refer to the same value.- The `/health` endpoint returns 200 as long as the web server is running, even if the database connection is down. Use `/ready` to check full service health.
Où ? Dans SKILL.md, là où l’agent les lit avant la situation. Un fichier séparé exige qu’on dise quand le charger, et pour un piège non évident l’agent peut ne pas reconnaître le déclencheur.
Source Best practices › Patterns › Gotchas sections
Templates de sortie
Un template concret est plus fiable qu’une description en prose : les agents font bien du pattern matching sur des structures concrètes.
## Report structureUse this template, adapting sections as needed for the specific analysis:```markdown# [Analysis Title]## Executive summary[One-paragraph overview of key findings]## Key findings- Finding 1 with supporting data- Finding 2 with supporting data## Recommendations1. Specific actionable recommendation2. Specific actionable recommendation```
Template court → inline dans SKILL.md.
Template long ou conditionnel → assets/, référencé depuis SKILL.md, chargé seulement au besoin.
Source Best practices › Patterns › Templates for output format
Checklists et boucles de validation
Checklist de workflow
Aide l’agent à suivre sa progression et à ne pas sauter d’étapes, surtout avec dépendances ou points de contrôle.
Progress:- [ ] Step 1: Analyze the form (run `scripts/analyze_form.py`)- [ ] Step 2: Create field mapping (edit `fields.json`)- [ ] Step 3: Validate mapping (run `scripts/validate_fields.py`)- [ ] Step 4: Fill the form (run `scripts/fill_form.py`)- [ ] Step 5: Verify output (run `scripts/verify_output.py`)
Boucle de validation
Faire le travail → lancer un validateur (script, checklist de référence ou auto-contrôle) → corriger → répéter.
1. Make your edits2. Run validation:`python scripts/validate.py output/`3. If validation fails: - Review the error message - Fix the issues - Run validation again4. Only proceed when validation passes
Source Best practices › Patterns › Checklists for multi-step workflows ; Validation loops
Plan-validate-execute
Pour les opérations par lots ou destructives : produire un plan intermédiaire structuré, le valider contre une source de vérité, puis seulement exécuter.
flowchart LR
A["1. Extraire les champs<br/>analyze_form.py<br/>→ form_fields.json"] --> B["2. Écrire le plan<br/>field_values.json"]
B --> C["3. Valider<br/>validate_fields.py<br/>plan vs source de vérité"]
C -->|"échec"| B
C -->|"succès"| D["5. Remplir<br/>fill_form.py<br/>→ output.pdf"]
L’ingrédient clé est l’étape 3 : un script qui compare le plan à la source de vérité. Son message d’erreur doit permettre l’auto-correction, par exemple en indiquant le champ inconnu et la liste des champs disponibles.
Source Best practices › Patterns › Plan-validate-execute
Embarquer des scripts réutilisables
Signal déclencheur : en comparant les traces d’exécution de plusieurs cas de test, on constate que l’agent réinvente la même logique à chaque exécution (construire des graphiques, analyser un format précis, valider une sortie).
Réponse : écrire une fois un script testé et l’embarquer dans scripts/.
Assemblage : squelette d’une Skill de formulaire PDF
---name: pdf-processingdescription: Extract PDF text, fill forms, merge files. Use when handling PDFs.---## Extract PDF textUse pdfplumber. For scanned documents, fall back to pdf2image + pytesseract.## Gotchas- (corrections accumulées lors des exécutions)## Form filling workflow <!-- plan-validate-execute + checklist -->Progress:-[] 1. `python scripts/analyze_form.py input.pdf` → `form_fields.json`-[] 2. Create `field_values.json`-[] 3. `python scripts/validate_fields.py form_fields.json field_values.json`-[]4. Fill: `python scripts/fill_form.py input.pdf field_values.json output.pdf`If step 3 fails, revise `field_values.json` and re-validate.Read `references/FORMS.md` for non-standard form formats.
Cours Assemblage à partir des exemples de Specification (frontmatter) et de Best practices (extraction, gotchas, workflow de formulaire)
Atelier 2 — Optimiser la description de organise-voyage
15 minutesBinômes
Consigne
Partir de la description de la spécification :
description: Extraire les contraintes, génère une proposition, contrôle. A utiliser quand un utilisateur parle de voyage.
Rédiger 8 requêtes (4 positives, 4 négatives) en respectant les axes de variation et en incluant au moins 2 quasi-erreurs (négatifs forts).
Répartir : 5 en train, 3 en validation (mélange de positifs et négatifs dans chaque jeu).
Réécrire la description en appliquant les quatre principes (impératif, intention, insistance, concision).
Prédire le comportement : quelles requêtes de train échouent encore ?
La description réécrite est-elle sous 1024 caractères ? Une requête de validation vous a-t-elle fait changer de description ? (Si oui : surapprentissage.)
Synthèse
Une Skill est une procédure ancrée dans l’expertise, pas un prompt générique
Question de conception
Réponse de la documentation
D’où vient la valeur ?
Expertise réelle : tâche vécue, artefacts de projet
Comment progresser ?
Exécuter, lire les traces, réviser
Que mettre dans la Skill ?
Ce que l’agent ignore ; le reste est coupé
Comment l’organiser ?
Progressive disclosure : 3 niveaux, < 500 lignes, renvois conditionnels à un niveau
Comment la déclencher ?
Description impérative, orientée intention, testée sur ~20 requêtes (train/validation)
Quel contrôle ?
Liberté si plusieurs approches valides ; prescriptif si fragile ; défauts plutôt que menus
Quelles techniques ?
Gotchas, templates, checklists, boucles de validation, plan-validate-execute, scripts
Une bonne Skill apporte à l’agent ce qu’il ne sait pas, au moment où il en a besoin, avec le degré de contrôle que la tâche exige.
Comment fonctionne le déclenchement
flowchart LR A["Démarrage :<br/>name + description<br/>de chaque Skill"] --> B["Requête<br/>utilisateur"] B --> C{"La tâche correspond<br/>à une description ?"} C -->|"oui"| D["Lecture du<br/>SKILL.md complet"] C -->|"non"| E["Travail sans la Skill"]Nuance : un agent ne consulte en général une Skill que pour les tâches hors de portée de ses outils de base. Un simple « lis ce PDF » peut ne pas la déclencher, même avec une description parfaite.