Agent Skills

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 :

  1. Concevoir une Skill dans le format standard Agent Skill
  2. Développer une Skill à partir d’une expertise réelle, puis la raffiner par l’exécution.
  3. Optimiser une description : comprendre son rôle dans le déclenchement, construire un jeu de requêtes d’évaluation, éviter le surapprentissage.
  4. Mobiliser les techniques d’instruction : gotchas, templates, checklists, boucles de validation, plan-validate-execute, scripts embarqués.
  5. Structurer le contenu : répartir l’information entre SKILL.md, references/, scripts/ et assets/ en exploitant la progressive disclosure.
  6. 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.
  • Adoption annoncée dans différents environnements : Claude, ChatGPT, Cursor, GitHub Copilot
  • Spécification consultable sur https://agentskills.io/specification

Standard commun ≠ comportement identique

La spécification décrit un format. Chaque plateforme possède son propre mécanisme d’intégration et d’exécution. Aucune spécification sur le contenu.

I. Le format d’une Skill (définition technique)

Séance 1 20 min

Source : Specification — Directory structure, SKILL.md format, Optional directories, Progressive disclosure, File references, Validation.

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-processing
description: Extract PDF text, fill forms, merge files. Use when handling PDFs.
---

## Extract PDF text
Use 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
  • ni tiret initial, ni tiret final
  • pas de tirets consécutifs --
  • identique au nom du répertoire parent

Valides

name: pdf-processing
name: data-analysis
name: code-review

Invalides

name: PDF-Processing  # majuscules
name: -pdf            # tiret initial
name: pdf--processing # tirets consécutifs
Source Specification › Frontmatter › name field

Le champ description : spécification

Règles

  • décrit ce que fait la Skill, pour quel objectif et quand 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.

Mauvais exemple

description: Helps with PDFs.

Pourquoi ? Aucune capacité précise, aucune situation de déclenchement, aucun mot-clé.

Source Specification › Frontmatter › description field (la partie IV y consacre 30 minutes)

Champs optionnels : license, compatibility, metadata, allowed-tools

Champ Règle Exemple de la spécification
license Court : nom de licence ou fichier embarqué Proprietary. LICENSE.txt has complete terms
compatibility 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-processing
description: Extract PDF text, fill forms, merge files. Use when handling PDFs.
license: Apache-2.0
metadata:
  author: example-org
  version: "1.0"
---
Source Specification › Frontmatter › license, compatibility, metadata, allowed-tools

Corps de SKILL.md

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 Specification › Body content ; Optional directories › scripts/, references/, assets/

Progressive disclosure (divulgation progressive) : charger au bon moment

Trois niveaux de chargement

flowchart TD
    A["Niveau 1 : Découverte<br/>name + description"]
    B["Niveau 2 : Activation<br/>instructions SKILL.md"]
    C["Niveau 3 : Ressources<br/>scripts, références, assets"]

    A -->|"Skill pertinente identifiée"| B
    B -->|"Besoin complémentaire<BR/> chargé à la demande"| C

  1. Découverte : Prise de connaissance des métadonnées disponibles pour identifier les Skills pertinentes.
  2. Activation : corps complet de SKILL.md chargé lorsque la Skill est retenue.
  3. Ressources : fichiers complémentaires consultés seulement si nécessaire.

Le coût réel d’une Skill apparaît à l’activation.

Source Specification › Progressive disclosure

Références internes et validation

Références entre fichiers

  • chemins relatifs à la racine de la Skill ;
  • références à un seul niveau de profondeur depuis SKILL.md ; éviter les chaînes de renvois imbriquées.
See [the reference guide](references/REFERENCE.md) for details.

Run the extraction script:
scripts/extract.py

Validation

skills-ref validate ./my-skill

La bibliothèque de référence skills-ref vérifie que le frontmatter est valide et que les conventions de nommage sont respectées.

https://github.com/agentskills/agentskills/tree/main/skills-ref

Source Specification › File references ; Validation

II. Concevoir et développer une Skill

Séance 1 20 min

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 :

  1. Exécuter la Skill sur de vraies tâches.
  2. Réinjecter dans le processus de création tous les résultats, pas seulement les échecs.
  3. 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

III. Structurer le contenu d’une Skill

Séance 1 20 min + atelier 15 min

Sources : Best practices › Spending context wisely ; Specification › Optional directories, Progressive disclosure.

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 text

PDF (Portable Document Format) files
are a common file format that contains
text, images, and other content. To
extract text from a PDF, you'll need to
use a library. pdfplumber is recommended
because it handles most cases well.

Direct recommandé

## Extract PDF text

Use pdfplumber for text extraction.
For scanned documents, fall back to
pdf2image with pytesseract.

```python
import pdfplumber

with 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-200
status 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

pdf-processing/
├── SKILL.md              # extraction, gotchas, workflow de remplissage
├── references/
│   ├── REFERENCE.md      # référence technique détaillée
│   └── FORMS.md          # modèles / formats de données de formulaires
├── scripts/
│   ├── analyze_form.py   # → form_fields.json
│   ├── validate_fields.py
│   ├── fill_form.py
│   └── verify_output.py
└── assets/               # modèles, schémas
Contenu Emplacement Justification
Choix pdfplumber + repli OCR SKILL.md Nécessaire à chaque exécution
Gotchas non évidents SKILL.md Doivent être lus avant la situation
Formats de formulaires détaillés references/FORMS.md Chargé seulement pour les formulaires
Analyse, validation, remplissage scripts/ Opérations déterministes
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 minutes Binômes nom 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

  1. Un frontmatter valide (name, description ≤ 1024 car.).
  2. Un SKILL.md de moins de 500 lignes : procédure + gotchas.
  3. Une décision argumentée : que mettre dans references/ et assets/ ?
  4. Une phrase qui borne le périmètre (qu’exclut la Skill ?).

Correction

IV. Écrire et optimiser la description

Séance 2 30 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.

Source Optimizing descriptions › Writing effective descriptions

Avant / après : une description CSV

Avant

description: Process CSV files.

Ce qui manque

  • les opérations réellement proposées ;
  • les situations d’usage ;
  • les cas où l’utilisateur ne dit pas « CSV ».

Après

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.

Source Optimizing descriptions › Designing trigger eval queries

Requêtes positives : varier quatre axes

Axe Variation à introduire
Formulation Formelle, familière, avec fautes ou abréviations
Explicitation 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.

Source Optimizing descriptions › Designing trigger eval queries › Should-trigger queries

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é ?

  1. 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).
  2. Lancer chaque requête et observer si l’agent a chargé le SKILL.md (journaux d’exécution, historique d’appels d’outils).
  3. 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.

20 requêtes × 3 exécutions = 60 invocations : à scripter.

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

  1. Mettre à jour le champ description du frontmatter.
  2. Vérifier la limite de 1024 caractères.
  3. 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 2 15 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 process

1. Check all database queries for
   SQL injection (use parameterized
   queries)
2. Verify authentication checks on
   every endpoint
3. Look for race conditions in
   concurrent code paths
4. 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 migration

Run exactly this sequence:

```bash
python scripts/migrate.py --verify --backup
```

Do not modify the command or add
additional 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.

You can use pypdf, pdfplumber,
PyMuPDF, or pdf2image...

Défaut + issue de secours recommandé

Use pdfplumber for text extraction:

```python
import pdfplumber
```

For scanned PDFs requiring OCR, use
pdf2image 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 tables
2. Join tables using the `_id`
   foreign key convention
3. Apply any filters from the user's
   request as WHERE clauses
4. 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 2 15 min

Source : Best practices › Patterns for effective instructions — Gotchas, Templates, Checklists, Validation loops, Plan-validate-execute, Bundling reusable scripts.

Question directrice : quels motifs réutilisables structurent une Skill robuste ?

Vue d’ensemble des six motifs

Motif Problème traité Où le placer
Gotchas 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 structure

Use 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

## Recommendations
1. Specific actionable recommendation
2. 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 edits
2. Run validation:
   `python scripts/validate.py output/`
3. If validation fails:
   - Review the error message
   - Fix the issues
   - Run validation again
4. 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/.

Exigence (Specification) Exemple dans le fil rouge PDF
Autonome ou dépendances documentées validate_fields.py précise ce qu’il importe
Messages d’erreur utiles Champ inconnu + champs disponibles
Cas limites gérés Champs obligatoires manquants, types incompatibles

Prolongement : guide « Using scripts in skills » (conception et embarquement de scripts).

Source Best practices › Patterns › Bundling reusable scripts ; Specification › scripts/

Assemblage : squelette d’une Skill de formulaire PDF

---
name: pdf-processing
description: Extract PDF text, fill forms, merge files. Use when handling PDFs.
---

## Extract PDF text
Use 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 minutes Binô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.
  1. 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).
  2. Répartir : 5 en train, 3 en validation (mélange de positifs et négatifs dans chaque jeu).
  3. Réécrire la description en appliquant les quatre principes (impératif, intention, insistance, concision).
  4. Prédire le comportement : quelles requêtes de train échouent encore ?
  5. Expérimenter votre skill dans Mistral Vibe https://chat.mistral.ai/skills
  6. Echanger vos requêtes entre binômes

Contrôle

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.

Références

Standard et bonnes pratiques

Contexte et écosystème