Transformez vos tâches répétitives en skills IA clairs, versionnés et réutilisables pour accélérer votre flux de développement au quotidien avec Claude Code.
Qu'est-ce qu'un skill IA ?
Un skill IA est une recette d'exécution encapsulée : il regroupe en un seul endroit l'objectif, le contexte métier, les règles de comportement, les entrées attendues, la sortie cible et les étapes de traitement. Là où un prompt libre est rédigé à la volée et oublié après usage, un skill est stable, partageable, versionnable et mesurable dans le temps.
L'idée n'est pas nouvelle : c'est exactement ce que fait une fonction bien définie par rapport à du code copié-collé. Un skill IA applique ce même principe aux interactions avec un LLM.
Différence entre skill, prompt, agent et template
Ces quatre termes sont souvent confondus. Voici une comparaison claire :
| Concept | Définition | Réutilisable ? | Versionnable ? | Usage typique |
|---|---|---|---|---|
| Prompt | Texte libre envoyé au LLM | Rarement | Non | Exploration, tests rapides |
| Template | Prompt avec variables à remplir | Oui | Rarement | Génération de contenu standard |
| Skill | Recette complète avec règles, I/O et contexte | Oui | Oui | Tâches répétitives d'équipe |
| Agent | Système autonome orchestrant plusieurs skills | Oui | Oui | Workflows complexes multi-étapes |
Pourquoi encapsuler dans un skill ?
- Cohérence : tous les développeurs obtiennent des résultats comparables pour la même tâche.
- Traçabilité : chaque version est datée et documentée — le débogage devient possible.
- Amélioration continue : on mesure la qualité des sorties et on itère sur les règles.
- Onboarding rapide : un nouveau développeur utilise les skills sans maîtriser le prompting avancé.
Anatomie d'un skill bien conçu
Un skill efficace repose sur six composants indissociables. Omettre l'un d'eux produit des résultats incohérents ou difficiles à déboguer.
Les 6 composants fondamentaux
- Nom — identifiant unique et lisible :
review.pr.security,generate.test.unit. - Objectif — une phrase décrivant exactement ce que le skill accomplit.
- Contexte — contraintes métier, stack technique, conventions de l'équipe.
- Entrées — liste typée des paramètres requis et optionnels.
- Sortie attendue — format précis de la réponse (JSON, Markdown, liste, etc.).
- Règles de comportement — ce que le skill doit faire, ne pas faire, et comment gérer les cas limites.
Exemple de skill minimal en YAML
Voici un skill complet pour la revue de sécurité d'une pull request. Chaque champ est rempli et commenté :
# skill: review.pr.security
# Version : 1.0.0
# Owner : @team-security
# Modifié : 2026-04-14
name: review.pr.security
# Objectif : ce que le skill produit exactement
objective: "Analyser le diff d'une PR pour détecter les risques de sécurité courants (injection,
secrets exposés, mauvaise gestion des erreurs, XSS, CSRF)."
# Contexte : stack et contraintes de l'équipe
context:
stack: ["Angular 17", "Node.js 20", "PostgreSQL"]
conventions: "OWASP Top 10, règles ESLint security"
language: "TypeScript"
# Entrées requises et optionnelles
input:
required:
- git_diff: string # Diff complet de la PR
- pr_title: string # Titre de la PR
optional:
- max_findings: number # Limite le nombre de findings (défaut: 10)
- severity_min: string # Filtre par sévérité (low|medium|high|critical)
# Format de sortie attendu
output:
format: JSON
schema:
status: "success | warning | failed | needs_review"
findings:
- file: string
line: number
severity: "low | medium | high | critical"
category: string
description: string
suggestion: string
summary: string
# Règles de comportement
rules:
- "Toujours citer le fichier ET la ligne concernée"
- "Ne jamais halluciner du code non présent dans le diff"
- "Si aucun risque détecté, retourner status: success avec findings vide"
- "Prioriser les findings par sévérité Descendante"
- "Limiter les descriptions à 2 phrases maximum"Quand créer un skill ?
Tous les prompts ne méritent pas d'être transformés en skill. Créer un skill a un coût réel : temps de conception, maintenance, documentation. Il faut donc choisir avec discernement.
Les trois critères de qualification
- Tâche répétitive : si la même interaction est exécutée plus de 3 fois par semaine par l'équipe, elle est candidate à la « skillification ».
- Besoin d'homogénéité : si plusieurs développeurs doivent obtenir des résultats comparables (revue de code, génération de tests), un skill garantit la cohérence.
- Audit requis : si les sorties IA sont intégrées dans un processus métier (merge de PR, déploiement, documentation officielle), la traçabilité devient obligatoire.
Tableau décisionnel : skill vs prompt libre
| Situation | Prompt libre | Skill dédié |
|---|---|---|
| Exploration / prototype rapide | Adapté | Surcharge |
| Tâche exécutée 1 à 2 fois | Adapté | Surcharge |
| Tâche répétitive hebdomadaire | Risque d'incohérence | Recommandé |
| Plusieurs devs, même tâche | Résultats hétérogènes | Obligatoire |
| Résultat intégré en CI/CD | Non traçable | Obligatoire |
| Workflow multi-étapes automatisé | Impossible à chaîner | Obligatoire |
Exemples de tâches typiquement « skillifiables »
- Revue de PR : analyse des risques, style, performance — exécutée à chaque PR.
- Génération de tests unitaires : à partir d'une fonction TypeScript, produire les cas de test Jest.
- Migration de code : convertir des composants Angular avec NgModules en composants standalone.
- Documentation automatique : générer un JSDoc ou un README à partir d'un module ou d'une API.
- Analyse de dépendances : détecter les packages obsolètes ou vulnérables et proposer des alternatives.
Décomposition et chaînage de skills
L'erreur la plus fréquente lors de la conception d'un skill est de vouloir tout faire en une seule étape. Un skill « couteau suisse » qui analyse, génère, corrige ET documente est difficile à maintenir, à déboguer et à améliorer.
L'anti-pattern : le skill monolithique
Imaginons un skill unique create.article.full qui, en une seule exécution, collecte
les informations, génère les métadonnées JSON, rédige le contenu complet et crée le fichier PHP.
Ce skill est problématique pour quatre raisons :
- Il produit des sorties trop longues pour être fiables sur tous les LLMs.
- Il échoue entièrement si une seule étape pose problème.
- Il est impossible à tester partiellement.
- Il ne peut pas être réutilisé dans d'autres workflows.
La bonne pratique : skills courts et connectables
Découpez le même workflow en 3 skills spécialisés, chacun avec une responsabilité unique :
| Skill | Responsabilité unique | Entrée | Sortie |
|---|---|---|---|
collect.article.info |
Collecter et valider les métadonnées | Sujet brut, niveau, tags | JSON métadonnées validé |
generate.article.json |
Générer l'entrée front.json | JSON métadonnées | Objet JSON prêt à insérer |
generate.article.php |
Rédiger le contenu technique complet | JSON + plan de sections | Fichier PHP complet |
Diagramme du chaînage de skills
# Workflow "Créer un article" — chaînage de 3 skills indépendants
# ─────────────────────────────────────────────────────────────────
# Entrée initiale
# └── Sujet brut (titre, niveau, technos)
# [Skill 1] collect.article.info
# Entrée : sujet brut
# Sortie : { id, name, slug, tags, category, description }
# │
# ▼
# [Skill 2] generate.article.json
# Entrée : métadonnées validées du Skill 1
# Sortie : objet JSON insérable dans front.json
# │
# ▼
# [Skill 3] generate.article.php
# Entrée : métadonnées + plan de sections
# Sortie : fichier PHP complet avec TOC, sections, code
# Chaque skill peut être :
# - Rejoué indépendamment en cas d'erreur partielle
# - Testé de façon isolée
# - Remplacé sans toucher aux skills adjacentsContrat d'entrée/sortie
Le contrat I/O est le document le plus important d'un skill. Il définit précisément ce que le skill consomme et ce qu'il produit. Sans contrat clair, les skills ne peuvent pas être chaînés, testés ou améliorés de façon fiable.
Typage des entrées et sorties en TypeScript
Pour les équipes TypeScript, définir le contrat I/O avec des interfaces permet de valider les entrées avant l'exécution et de documenter le skill de façon exploitable par les outils :
// Contrat d'entrée/sortie pour le skill review.pr.security
// Fichier : skills/review-pr-security/contract.ts
// ─── Types partagés ─────────────────────────────────────────────────────────
// Niveaux de sévérité possibles pour un finding de sécurité
export type SeverityLevel = 'low' | 'medium' | 'high' | 'critical';
// Statuts possibles d'une exécution de skill
export type SkillStatus = 'success' | 'warning' | 'failed' | 'needs_review';
// ─── Entrées (Input) ────────────────────────────────────────────────────────
export interface ReviewPrInput {
/** Diff complet de la pull request (sortie de git diff) */
gitDiff: string;
/** Titre de la PR pour contextualiser l'analyse */
prTitle: string;
/** Nombre maximum de findings à retourner (optionnel, défaut: 10) */
maxFindings?: number;
/** Sévérité minimale à inclure dans les résultats */
severityMin?: SeverityLevel;
}
// ─── Sortie (Output) ────────────────────────────────────────────────────────
export interface SecurityFinding {
file: string; // Chemin relatif du fichier concerné
line: number; // Numéro de ligne dans le diff
severity: SeverityLevel;
category: string; // Ex: "XSS", "Injection SQL", "Secret exposé"
description: string; // Explication du problème (2 phrases max)
suggestion: string; // Action corrective recommandée
}
export interface ReviewPrOutput {
/** Statut global de l'exécution du skill */
status: SkillStatus;
/** Liste des problèmes détectés, triés par sévérité Descendante */
findings: SecurityFinding[];
/** Résumé textuel de l'analyse en 2-3 phrases */
summary: string;
/** Horodatage de l'exécution (ISO 8601) */
executedAt: string;
}Validation de la sortie avec JSON Schema
En complément du typage TypeScript, un JSON Schema permet de valider automatiquement les sorties du LLM avant de les consommer dans un workflow :
{
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "ReviewPrOutput",
"type": "object",
"required": ["status", "findings", "summary", "executedAt"],
"properties": {
"status": {
"type": "string",
"enum": ["success", "warning", "failed", "needs_review"],
"description": "Statut global de l'exécution"
},
"findings": {
"type": "array",
"items": {
"type": "object",
"required": ["file", "line", "severity", "category", "description", "suggestion"],
"properties": {
"file": { "type": "string" },
"line": { "type": "number", "minimum": 1 },
"severity": { "type": "string", "enum": ["low", "medium", "high", "critical"] },
"category": { "type": "string" },
"description": { "type": "string", "maxLength": 300 },
"suggestion": { "type": "string", "maxLength": 300 }
}
}
},
"summary": { "type": "string", "maxLength": 500 },
"executedAt": { "type": "string", "format": "date-time" }
}
}Gestion des erreurs et fallback
- Valider la sortie : toujours valider le JSON retourné contre le schéma avant de l'utiliser.
- Statut
failed: si la validation échoue, retourner un statut d'erreur structuré avec le détail. - Statut
needs_review: si la confiance est basse ou les entrées incomplètes, signaler qu'une vérification humaine est nécessaire. - Fallback : en cas d'erreur répétée, logger l'échec et alerter l'owner du skill.
needs_review est le signal le plus précieux
pour améliorer un skill. Il indique exactement les cas limites que les règles actuelles
ne couvrent pas encore.
Versionning et catalogue de skills
Un skill sans versionning est ingérable dès que l'équipe grandit ou que le skill est utilisé dans plusieurs workflows. Il faut un système clair pour nommer, stocker et faire évoluer chaque skill.
Convention de nommage : verbe + objet + contexte
La convention verbe.objet.contexte rend les skills immédiatement lisibles et
facilite la recherche dans un catalogue :
review.pr.security— revue de PR axée sécuritégenerate.test.unit— génération de tests unitaires Jestmigrate.component.standalone— migration vers composant Angular standalonedocument.function.jsdoc— documentation JSDoc d'une fonctionanalyze.deps.vulnerabilities— analyse des dépendances vulnérablesgenerate.article.php— génération d'un article PHP pour le blog
Structure de dossiers d'un catalogue
# Structure recommandée pour un catalogue de skills d'équipe
# Chaque skill possède son propre dossier avec 4 fichiers standardisés
skills/
├── README.md # Index du catalogue avec descriptions
├── _templates/
│ └── skill-template.yaml # Modèle vide pour créer un nouveau skill
│
├── review.pr.security/
│ ├── skill.yaml # Définition complète du skill (v1.2.0)
│ ├── contract.ts # Interfaces TypeScript I/O
│ ├── examples/
│ │ ├── input-01.json # Exemple d'entrée valide
│ │ └── output-01.json # Sortie attendue correspondante
│ └── CHANGELOG.md # Historique des modifications
│
├── generate.test.unit/
│ ├── skill.yaml # (v2.0.1)
│ ├── contract.ts
│ ├── examples/
│ └── CHANGELOG.md
│
└── migrate.component.standalone/
├── skill.yaml # (v1.0.0)
├── contract.ts
├── examples/
└── CHANGELOG.mdFichier de métadonnées skill.yaml
# skill.yaml — définition et métadonnées complètes d'un skill
# Convention semver : MAJEUR.MINEUR.PATCH
# MAJEUR : changement incompatible du contrat I/O
# MINEUR : nouvelle fonctionnalité rétrocompatible
# PATCH : correction de règles ou de formulation
version: "1.2.0"
name: review.pr.security
status: stable # stable | beta | deprecated
owner: "@alice-sec"
created: "2026-01-10"
updated: "2026-04-12"
# Description affichée dans le catalogue
description: "Analyse un diff de pull request et détecte les risques de sécurité selon OWASP Top 10."
# Tags pour la recherche dans le catalogue
tags: ["security", "pr", "review", "owasp"]
# Compatibilité LLM testée et documentée
llm_compat:
- provider: "openai"
models: ["gpt-4o", "gpt-4-turbo"]
tested: true
- provider: "anthropic"
models: ["claude-3-5-sonnet"]
tested: true
# Métriques de qualité observées sur 100 exécutions
metrics:
precision_avg: 0.87 # Taux de vrais positifs
recall_avg: 0.79 # Taux de détection des vrais problèmes
needs_review_rate: 0.08 # Taux de sorties nécessitant revue humaineWorkflow d'adoption en équipe
Introduire les skills IA dans une équipe nécessite un processus d'adoption progressif. Un skill publié trop tôt sans validation génère de la méfiance ; publié trop tard, il n'apporte pas de valeur.
Les 4 étapes du cycle de vie d'un skill
| Étape | Version | Qui ? | Objectif | Critère de passage |
|---|---|---|---|---|
| 1. Prototype | v0.1.0 |
1 dev (owner) | Valider le concept sur un cas réel | 3 exécutions concluantes |
| 2. Collecte d'erreurs | v0.2.x |
2-3 bêta-testeurs | Identifier faux positifs et cas limites | 10+ exécutions documentées |
| 3. Itération | v0.x.y |
Owner + feedback équipe | Affiner les règles et le format de sortie | Taux needs_review inf. à 15 % |
| 4. Publication | v1.0.0 |
Toute l'équipe | Intégrer au catalogue officiel | Revue + checklist validée |
Rôle de l'owner de skill
Chaque skill doit avoir un owner identifié. Ce rôle est léger mais essentiel :
- Il est la personne de référence pour toute question sur le skill.
- Il valide les pull requests qui modifient le skill.
- Il met à jour le CHANGELOG à chaque évolution.
- Il surveille les métriques et déclenche les itérations d'amélioration.
- Il décide du passage en statut
deprecatedsi le skill n'est plus pertinent.
Checklist de validation avant publication v1.0.0
- Le nom respecte la convention
verbe.objet.contexte. - Le contrat I/O est documenté (TypeScript + JSON Schema ou YAML).
- Au moins 3 exemples d'entrée/sortie fournis dans
examples/. - Le CHANGELOG contient la description de la v1.0.0.
- Le taux de
needs_reviewest inférieur à 15 % sur 20+ exécutions test. - Au moins 2 développeurs ont testé le skill indépendamment.
- Compatibilité vérifiée sur au moins 2 modèles LLM différents.
- L'owner est identifié dans
skill.yaml.
Gouvernance minimale
La gouvernance d'un catalogue de skills n'a pas besoin d'être lourde. L'objectif est de maintenir la qualité sans créer une bureaucratie qui freine l'adoption.
Les 4 piliers de la gouvernance légère
- Owner par skill : une personne responsable, pas un comité. La décision est rapide, la responsabilité est claire.
- Changelog obligatoire : chaque modification inclut une ligne de changelog. Pas besoin d'un document de 10 pages — 2 à 3 lignes suffisent.
- Exemples versionnés : les exemples I/O doivent correspondre à la version actuelle. Un exemple obsolète est pire qu'aucun exemple.
-
Revue de pair : toute modification d'un skill en statut
stablenécessite une revue par un autre développeur.
Responsabilités selon la taille d'équipe
| Taille | Organisation | Gouvernance recommandée | Outillage |
|---|---|---|---|
| 1-3 devs | Solo / startup | Owner = créateur, changelog dans le YAML | Dossier Git simple |
| 4-10 devs | Petite équipe | Owner désigné + revue simple (1 reviewer) | Repo Git + PR process |
| 11-30 devs | Équipe moyenne | Guild IA, 2 reviewers, catalogue partagé | Repo Git + CI validation schéma |
| 30+ devs | Grande équipe | Équipe platform dédiée, SLA de maintenance | Catalogue interne avec interface UI |
Ce qu'il faut absolument éviter
- Sur-documentation : si rédiger la documentation prend plus de temps qu'utiliser le skill, quelque chose ne va pas.
- Lock-in sur un seul LLM : évitez les skills qui ne fonctionnent qu'avec un seul fournisseur. Testez sur au moins deux modèles.
- Trop de skills bêta en production : un skill non validé produit des résultats imprévisibles. Respectez le cycle de validation.
- Absence de dépréciation : planifiez des revues trimestrielles. Un catalogue qui ne déprécie jamais ses skills devient un musée.
Mesures et KPIs à 30 jours
Adopter des skills IA sans mesurer leur impact est une erreur courante. Voici les 5 métriques clés à suivre dès le premier mois pour piloter l'amélioration continue.
| Métrique | Formule / Mesure | Valeur cible | Signal d'alerte |
|---|---|---|---|
| Taux de succès | success / total_exécutions |
Sup. à 80 % | Inf. à 60 % → revoir les règles |
| Taux needs_review | needs_review / total_exécutions |
Inf. à 15 % | Sup. à 25 % → ajouter exemples et règles |
| Taux de reprise manuelle | % de sorties modifiées avant usage | Inf. à 20 % | Sup. à 40 % → contrat I/O à revoir |
| Temps gagné par tâche | Durée sans skill − Durée avec skill | Sup. à 30 % | Inf. à 10 % → réévaluer la pertinence |
| Satisfaction équipe | Score sur 5 (sondage mensuel) | Sup. à 3,5 / 5 | Inf. à 3 → recueillir retours qualitatifs |
Comment améliorer un skill sur la base des données
Chaque métrique pointe vers un axe d'amélioration spécifique :
-
Trop de
needs_review: analysez les cas déclencheurs. Souvent, il manque un exemple d'entrée limite ou une règle explicite pour un cas non prévu. - Trop de reprises manuelles : le format de sortie n'est pas assez précis. Ajoutez des contraintes dans le schéma ou des exemples de sorties idéales.
- Temps gagné insuffisant : le skill est peut-être trop générique. Découpez-le en skills plus spécialisés ou affinez le contexte.
- Satisfaction basse : organisez un retour qualitatif de 15 minutes avec les utilisateurs pour identifier les frictions non capturées par les métriques quantitatives.
Conclusion
Les skills IA réutilisables représentent le passage obligé entre l'usage improvisé des LLMs et une intégration professionnelle dans le workflow de développement. En encapsulant chaque tâche répétitive dans une unité claire — avec son contrat I/O, ses règles et son versionning — vous transformez des interactions ponctuelles en un véritable actif d'équipe, mesurable et améliorable dans le temps.
La clé est de commencer petit : un seul skill, sur la tâche la plus répétitive de votre quotidien, avec une équipe restreinte de bêta-testeurs. Mesurez, itérez, publiez. Puis répétez.
Roadmap d'adoption : 3 phases
| Phase | Durée | Objectif | Livrable |
|---|---|---|---|
| Phase 1 | Semaines 1-2 | Créer et valider 1 skill à fort impact | 1 skill v1.0.0 en production |
| Phase 2 | Semaines 3-6 | Étendre à 5 skills, stabiliser les conventions | Catalogue de 5 skills + conventions d'équipe |
| Phase 3 | Mois 2-3 | Chaîner les skills en workflows automatisés | 2-3 workflows complets + métriques stabilisées |
