Il y a quelque temps, on a posé une distinction simple sur ce média : les tools, c'est la caisse à outils de l'agent IA, et les skills, c'est son savoir-faire. Le tournevis électrique d'un côté, la compétence "réparer une panne moteur" de l'autre.
Juste après, on a vu comment construire concrètement un tool, avec un serveur MCP en Spring Boot capable d'interroger sfeir.dev. Un outil précis, qui sait faire une chose : appeler l'API Ghost, récupérer des articles, lister des auteurs.
Mais on n'a pas encore ouvert le capot du second concept. Qu'est-ce qu'un skill, concrètement ? À quoi ça ressemble dans un projet réel ? Et surtout, comment en écrire un qui soit réellement utile, et pas juste un fichier markdown qui prend la poussière ?
C'est le sujet du jour.
Une skill, c'est quoi exactement ?
Reprenons l'analogie du garage. Le mécanicien a une clé à molette, un cric, une valise de diagnostic : ce sont ses tools. Mais ce qui fait de lui un mécanicien, et pas juste quelqu'un qui possède des outils, c'est sa capacité à savoir dans quel ordre les utiliser, pourquoi, et dans quel contexte.
Un skill, c'est exactement ça pour un agent IA : un paquet de savoir-faire que l'agent va consulter au bon moment, pour orienter la manière dont il aborde un problème.
Concrètement, ce format n'est pas propre à un seul outil : que ce soit dans l'écosystème Claude ou dans Codex, une skill prend la forme d'un dossier contenant a minima un fichier SKILL.md. Ce fichier porte un entête au format YAML avec deux informations essentielles :
---
name: dev-app-java
description: "Cross-cutting Java application development and quality improvement..."
---
Le name identifie le skill. La description, elle, joue un rôle bien plus important qu'il n'y paraît : c'est elle que l'agent va lire pour décider, ou non, de charger le skill.
Si la description est vague, l'agent risque de passer à côté au moment où il aurait justement été utile. On retrouve ici, presque mot pour mot, ce qu'on disait sur les descriptions de tools dans l'article précédent : pour le modèle, c'est une partie de son interface de décision.
La différence fondamentale avec un tool reste celle-ci : un tool exécute une action technique précise (appeler une API, lire un fichier). Un skill, lui, ne fait rien par lui-même. Il informe la manière dont l'agent va utiliser ses tools, structurer son raisonnement, et appliquer un standard de qualité.
Il existe d'ailleurs une subtilité intéressante du côté de Codex : à côté du SKILL.md, on peut ajouter un fichier agents/openai.yaml qui ne contient aucune logique métier, uniquement de la présentation :
interface:
display_name: "Dev App Java"
short_description: "Java app development + best practices."
icon_large: "./assets/logo-java-coffee-cup.png"
default_prompt: "Help me create or improve a Java application (Vanilla, Spring Boot, Quarkus, Struts) with best practices..."
Il définit le nom affiché, une courte description, et une icône, pour habiller le skill sous forme de carte dans l'interface :
Ce fichier est entièrement ignoré côté Claude, qui n'a pas de surface d'affichage équivalente et se contente de lire le SKILL.md en arrière-plan. Les deux fichiers cohabitent donc sans se gêner dans le même dossier : chaque outil pioche ce qu'il sait lire, et ignore le reste.
Pourquoi un skill plutôt qu'un simple prompt ?
À ce stade, une question vient naturellement : pourquoi créer un skill, alors qu'on pourrait simplement copier toutes ces consignes dans un prompt ?
Pour une démonstration ponctuelle, un prompt peut effectivement suffire. Mais dès que les mêmes règles doivent être appliquées régulièrement, il montre rapidement ses limites.
Un skill est d'abord réutilisable. Une fois installée, plus besoin de recopier les mêmes dizaines de lignes d'instructions à chaque nouvelle conversation : l'agent sait qu'elles existent et peut les activer lorsque leur description correspond au contexte.
Il est aussi versionnable. Comme n'importe quel fichier du projet, un SKILL.md peut vivre dans un dépôt Git, évoluer au fil des revues de code et être partagé avec toute une équipe. Le savoir-faire ne reste plus enfermé dans le prompt d'une seule personne.
Enfin, un skill est chargé à la demande. Contrairement à un énorme prompt qui impose toutes les règles en permanence, l'agent ne consulte que les skills pertinents pour la tâche en cours, ainsi que les fichiers de référence dont il a réellement besoin. On évite ainsi de surcharger inutilement son contexte tout en conservant des consignes précises lorsqu'elles sont utiles.
En d'autres termes, un prompt décrit ce que vous attendez pour une conversation. Un skill formalise un savoir-faire réutilisable, que l'agent pourra appliquer de manière cohérente d'une tâche à l'autre.
Les bonnes pratiques pour écrire un skill utile
Après quelques allers-retours sur ce type de fichier, plusieurs principes se dégagent assez naturellement.
- Une description qui se suffit à elle-même. L'agent décide de charger un skill avant même d'avoir lu son contenu complet, uniquement sur la base de sa description. Elle doit donc indiquer précisément le périmètre couvert et les déclencheurs attendus, sans présumer du contexte.
- Un contenu structuré en étapes, pas en liste de conseils en vrac. Un bon
SKILL.mdressemble davantage à un processus qu'à un mémo. Clarifier le contexte, diagnostiquer le besoin, appliquer les bonnes pratiques ciblées, valider le résultat : ce découpage donne à l'agent une trajectoire claire plutôt qu'un nuage de recommandations. - Le détail dans des fichiers de référence, pas dans le fichier principal. Tout charger d'un coup serait contre-productif. La bonne pratique consiste à garder le
SKILL.mdsynthétique, et à renvoyer vers des fichiersreferences/*.mdplus détaillés, consultés uniquement quand le contexte le justifie. C'est le même réflexe que pour les tools : éviter d'exposer trop d'informations en une seule fois pour ne pas diluer la décision. - Rester explicite plutôt qu'exhaustif. Un skill qui tente de couvrir tous les cas possibles devient illisible et finit par contredire sa propre logique. Mieux vaut une portée resserrée, avec des règles claires sur quand agir, que d'innombrables règles génériques.
- Composer plusieurs skills plutôt qu'en créer un géant. Si un sujet touche plusieurs domaines distincts (par exemple le code Java d'un côté, la génération de documents Word de l'autre), il vaut mieux deux skills bien délimités qu'un seul qui mélange tout.
Un exemple concret : le skill dev-app-java
Pour illustrer tout ça sans rester dans la théorie, prenons un skill bien réel : dev-app-java, pensée pour le développement d'applications Java (Vanilla, Spring Boot, Quarkus, Struts).
Sa description annonce clairement son périmètre :
Cross-cutting Java application development and quality improvement (structure, refactoring, tests, documentation) for Vanilla Java, Spring Boot, Quarkus, or Struts.
Son corps suit exactement la logique en étapes évoquée plus haut. Extrait direct du SKILL.md :
## Workflow
1. **Clarify Context**
- Identify the application type (Vanilla Java, Spring Boot, Quarkus, Struts)
- Identify the concrete goal (feature, refactoring, bug fix, review).
- Do not assume frameworks or libraries beyond what is explicitly stated.
2. **Diagnose Needs**
- Javadoc: missing contracts, ambiguities, undocumented edge cases.
- Tests: missing coverage (edge cases, errors), weak or brittle assertions.
- Design: duplicated logic, mixed responsibilities, lack of clarity.
3. **Apply Targeted Best Practices**
- Apply only necessary changes.
- Prefer simple and explicit solutions over generic or abstract ones.
- Avoid over-engineering; introduce patterns only when they solve a concrete problem.
4. **Validate**
- Ensure readability and consistency.
- Verify impact on existing code.
- Add or adapt unit tests if behavior changes.
Le fichier détaille ensuite des principes transverses (nommage orienté métier, usage des records et du pattern matching de Java 17/21, règles de Javadoc, design patterns à n'introduire que s'ils résolvent un problème concret), avant de renvoyer vers des fichiers de référence dédiés :
references/java-best-practices.md → règles et checklists détaillées
references/modern-java.md → spécificités Java 17/21
references/build-and-logs.md → build systems et logging
references/spring-boot.md → si le projet est Spring Boot
references/quarkus.md → si le projet est Quarkus
references/struts.md → si le projet est StrutsCette dernière section illustre bien le principe de chargement contextuel : si le projet en question est du Quarkus, seul references/quarkus.md sera consulté. Le reste demeure de côté, inutile de l'encombrer.
À quoi ressemble ce niveau de détail ? Voici un extrait de java-best-practices.md, sur la règle Javadoc :
## Javadoc Rules
- Document the functional contract: what the method does, not how.
- Describe parameters with constraints (nullability, formats, units).
- Describe the return value (business meaning, sentinel values).
- List exceptions and trigger conditions.
- Add a usage example if the method is non-trivial.
- Avoid repetition with the method name; explain side effects.
Et un extrait de spring-boot.md, chargé uniquement si le projet détecté est du Spring Boot, sur la séparation des couches :
## Architecture & Layers
- Clearly separate:
- **Controller** → HTTP exposure
- **Service** → business logic
- **Repository** → data access
- Controllers should remain **thin**
- Business logic belongs in services
- Repositories should only contain data access logic
**When to act:**
- Business logic in controllers
- Overly large services
- Strong coupling between layers
Et c'est précisément là que la distinction avec les tools redevient limpide. Quand ce skill est actif sur un projet Spring Boot, il ne va pas lui-même lire le pom.xml ou lancer les tests : il s'appuie sur les tools habituels (lecture de fichier, exécution de commandes) pour le faire.
Ce qu'il apporte, c'est la méthode : quoi regarder en premier, quoi diagnostiquer, quand s'arrêter pour ne pas sur-ingénierer une solution.
Ce qu'il faut retenir
Un skill n'est pas un super-tool déguisé, et ce n'est pas non plus un simple recueil de bonnes pratiques jeté dans un fichier. C'est un cadre de décision, qui s'active quand le contexte le justifie, et qui transforme un agent généraliste en quelque chose qui se comporte davantage comme un collègue senior sur un domaine précis.
Les tools donnent les moyens d'agir. Les skills donnent la méthode pour bien agir. Et comme on l'a vu avec dev-app-java, le meilleur signe qu'un skill est bien écrit, c'est qu'on pourrait presque la donner à un junior comme guide de revue de code, sans rien y changer.
La prochaine fois qu'un agent IA semble "comprendre" votre métier mieux que prévu, il y a de bonnes chances qu'un skill bien pensé tourne discrètement en arrière-plan.
Et si vous êtes à la recherche de skills pour vous faciliter la tâche lors de développement d'applications Java, je vous ai créé un repository dédié :
ErwanLT
