Comment ecrire votre premier SKILL.md — Guide complet pour les agents de codage IA

Si vous avez deja copie les memes instructions dans CLAUDE.md, .cursorrules et les fichiers de configuration Copilot, vous comprenez deja le probleme que resolvent les Agent Skills. Un seul fichier SKILL.md modulaire remplace tout cela — et il fonctionne sur plus de 30 outils de codage IA sans modification.

Ce tutoriel vous guide etape par etape, depuis un repertoire vide jusqu'a une competence pleinement fonctionnelle et compatible multiplateforme.

Prerequis

Avant de commencer, assurez-vous de disposer de :

• Un outil de codage IA installe (Claude Code, GitHub Copilot, Cursor, OpenAI Codex ou Google Gemini CLI)
• Un depot de projet ou vous souhaitez ajouter des competences
• Une connaissance de base de la syntaxe YAML et Markdown
• Un terminal et un editeur de texte

Si vous decouvrez le standard Agent Skills, lisez d'abord notre article de presentation sur les Agent Skills et la specification SKILL.md.

Ce que vous allez construire

A la fin de ce tutoriel, vous disposerez de deux Agent Skills fonctionnelles :

1. Une competence de revue de code qui s'active lorsque vous demandez des revues de PR, des audits de code ou des controles de qualite
2. Une competence de verification de deploiement qui execute une validation pre-deploiement avec un script integre

Les deux competences fonctionneront sur Claude Code, Codex, Copilot, Cursor, Gemini CLI et JetBrains Junie.

Etape 1 : Creer le repertoire des competences

Les Agent Skills resident dans un repertoire .agents/skills/ a la racine de votre depot. C'est la convention multiplateforme reconnue par tous les outils compatibles.

mkdir -p .agents/skills/code-review
mkdir -p .agents/skills/deploy-checker

Chaque competence possede son propre repertoire. Le nom du repertoire sert a l'organisation humaine — l'agent lit le champ name du fichier SKILL.md, pas le nom du dossier.

La structure de votre projet ressemble maintenant a ceci :

your-project/
├── .agents/
│   └── skills/
│       ├── code-review/
│       │   └── (SKILL.md se place ici)
│       └── deploy-checker/
│           └── (SKILL.md se place ici)
├── src/
└── package.json

Les repertoires specifiques aux outils fonctionnent egalement. Claude Code lit depuis .claude/skills/, Cursor depuis .cursor/skills/, et ainsi de suite. Mais .agents/skills/ est l'emplacement universel que chaque outil reconnait. Utilisez-le pour une portabilite maximale.

Etape 2 : Ecrire les metadonnees YAML (Frontmatter)

Chaque fichier SKILL.md commence par des metadonnees YAML encadrees par des triples tirets. Ce sont les metadonnees que l'agent lit au demarrage.

Creez .agents/skills/code-review/SKILL.md et ajoutez :

---
name: code-review
description: >
  Reviews code changes for quality, security, and adherence to project
  conventions. Use when the user asks to 'review code', 'check this PR',
  'audit this change', 'look at my diff', or 'review my changes'.
---

Champs obligatoires

Champs optionnels

Le champ description merite une attention particuliere — c'est le mecanisme de declenchement qui determine si votre competence s'activera un jour.

Etape 3 : Ecrire une description de declenchement efficace

La description n'est pas de la documentation pour les humains. C'est le signal principal qu'un agent IA utilise pour decider s'il doit charger cette competence pour une requete donnee.

Description faible (s'active rarement) :

description: Aide a la qualite du code

Description forte (s'active de maniere fiable) :

description: >
  Reviews code changes for quality, security, and adherence to project
  conventions. Use when the user asks to 'review code', 'check this PR',
  'audit this change', 'look at my diff', or 'review my changes'.

Ce qui rend une description efficace

1. Indiquez ce que fait la competence dans la premiere phrase
2. Listez des phrases de declenchement specifiques que l'utilisateur pourrait prononcer — entre guillemets et separees par des virgules
3. Incluez des synonymes pour la meme action (review, audit, check, look at)
4. Restez sous 200 mots — ce contenu est charge a chaque debut de conversation

Tester votre description

Apres l'avoir ecrite, testez mentalement avec ces invites :

• "Can you review this PR?" — devrait s'activer
• "Check my code for security issues" — devrait s'activer
• "Write a new function" — ne devrait PAS s'activer
• "Deploy to production" — ne devrait PAS s'activer

Si un test echoue, affinez les phrases de declenchement.

Etape 4 : Ecrire le corps des instructions

Sous le frontmatter, redigez le corps en Markdown. C'est l'ensemble d'instructions reel qui est charge lorsque la competence s'active.

---
name: code-review
description: >
  Reviews code changes for quality, security, and adherence to project
  conventions. Use when the user asks to 'review code', 'check this PR',
  'audit this change', 'look at my diff', or 'review my changes'.
---
 
# Code Review
 
## Flux de travail
 
1. Lire le diff ou les fichiers modifies en utilisant `git diff` ou les chemins de fichiers fournis
2. Verifier les vulnerabilites de securite par rapport au OWASP Top 10
3. Verifier la gestion des erreurs — pas de blocs catch vides, pas d'erreurs avalees
4. Verifier le style de code par rapport aux conventions du projet (regles de linting, nommage)
5. Rechercher les problemes de performance — boucles inutiles, index manquants, requetes N+1
6. Verifier la couverture des tests — les nouvelles methodes publiques doivent avoir des tests
7. Fournir un retour structure
 
## Format de sortie
 
Structurez chaque revue en trois sections :
 
### Critique (a corriger avant la fusion)
- Vulnerabilites de securite
- Risques de perte de donnees
- Changements cassants sans migration
 
### Avertissement (a corriger de preference)
- Gestion des erreurs manquante
- Problemes de performance
- Couverture de tests incomplete
 
### Suggestion (amelioration souhaitable)
- Ameliorations du style de code
- Ameliorations de la lisibilite
- Lacunes dans la documentation
 
## Regles
 
- Referencez des numeros de ligne specifiques dans les retours
- Fournissez une suggestion de correction pour chaque probleme signale
- Si le changement est correct, dites-le — n'inventez pas de problemes
- N'approuvez jamais du code avec des vulnerabilites de securite connues

Conseils de redaction

• Utilisez la voix imperative. "Lire le diff" et non "Le diff devrait etre lu."
• Soyez specifique. "Verifier l'injection SQL dans les parametres de requete" et non "Verifier les problemes de securite."
• Restez sous 5 000 tokens. Si c'est plus long, divisez en plusieurs competences ou deplacez le materiel de reference dans des fichiers separes.
• Structurez avec des en-tetes. L'agent navigue entre les sections par en-tete.

Etape 5 : Comprendre la divulgation progressive

Les Agent Skills utilisent un systeme de chargement a trois niveaux qui economise les tokens :

Niveau 1 : Metadonnees (toujours chargees)

Au demarrage, l'agent lit uniquement les champs name et description du frontmatter — environ 100 tokens par competence. Avec 50 competences installees, cela represente environ 5 000 tokens au total. L'agent sait ce que fait chaque competence sans lire une seule instruction.

Niveau 2 : Instructions (chargees a l'activation)

Lorsque la requete d'un utilisateur correspond a la description d'une competence, le corps complet du SKILL.md est charge — generalement moins de 5 000 tokens. C'est la que vivent votre flux de travail, vos regles et votre format de sortie.

Niveau 3 : Ressources (chargees selon les besoins)

Les scripts, fichiers de reference et modeles dans le repertoire de la competence ne sont charges que lorsque les instructions y font reference. Une competence peut regrouper des megaoctets de documentation, mais seule la section pertinente entre dans la fenetre de contexte.

Cela signifie que 50 competences ciblees consomment moins de tokens qu'un seul fichier de configuration monolithique. Le fichier monolithique charge tout a chaque requete. Les competences ne chargent que ce qui est necessaire.

Etape 6 : Construire la competence de verification de deploiement

Construisons maintenant une competence plus avancee qui integre un script executable.

Creez .agents/skills/deploy-checker/SKILL.md :

---
name: deploy-checker
description: >
  Validates deployment readiness before pushing to staging or production.
  Use when the user says 'check deploy', 'pre-deploy check', 'is this
  ready to deploy', 'deployment readiness', or 'can we ship this'.
allowed-tools: Read, Grep, Glob, Bash
---
 
# Verification de la preparation au deploiement
 
## Flux de travail
 
1. Executez le script de verification de deploiement :
 
\`\`\`bash
bash .agents/skills/deploy-checker/scripts/check_deploy.sh
\`\`\`
 
2. Examinez la sortie du script pour tout resultat FAIL
3. Si toutes les verifications passent, confirmez la preparation au deploiement
4. Si une verification echoue, expliquez l'echec et suggerez une correction
 
## Interpretation des resultats
 
- **PASS** — verification reussie, aucune action necessaire
- **WARN** — non bloquant mais a noter
- **FAIL** — doit etre resolu avant le deploiement
 
## Escalade
 
Si le script ne peut pas determiner le statut d'une verification, verifiez manuellement :
- Les migrations de base de donnees sont a jour
- Les variables d'environnement sont definies pour l'environnement cible
- Pas de dependances non fusionnees dans package-lock.json ou yarn.lock

Creer le script integre

Creez .agents/skills/deploy-checker/scripts/check_deploy.sh :

#!/bin/bash
# Verifications de preparation au deploiement
 
echo "=== Verification de preparation au deploiement ==="
echo ""
 
# Verification 1 : Pas de modifications non commitees
if [ -z "$(git status --porcelain)" ]; then
  echo "PASS: Repertoire de travail propre"
else
  echo "FAIL: Modifications non commitees detectees"
  git status --short
fi
 
# Verification 2 : Les tests passent
if npm test --silent 2>/dev/null; then
  echo "PASS: Tests reussis"
else
  echo "FAIL: Tests en echec"
fi
 
# Verification 3 : Le build reussit
if npm run build --silent 2>/dev/null; then
  echo "PASS: Build reussi"
else
  echo "FAIL: Build casse"
fi
 
# Verification 4 : Pas de TODO/FIXME dans les changements indexes
if git diff --cached | grep -qi "TODO\|FIXME\|HACK"; then
  echo "WARN: TODO/FIXME trouves dans les changements indexes"
else
  echo "PASS: Pas de TODO/FIXME dans les changements indexes"
fi
 
# Verification 5 : Dependances a jour
if [ -f "package-lock.json" ]; then
  if git diff HEAD --name-only | grep -q "package.json"; then
    if git diff HEAD --name-only | grep -q "package-lock.json"; then
      echo "PASS: Fichier lock mis a jour avec package.json"
    else
      echo "FAIL: package.json modifie mais fichier lock non mis a jour"
    fi
  else
    echo "PASS: Dependances inchangees"
  fi
fi
 
echo ""
echo "=== Verification terminee ==="

Notez le champ allowed-tools dans le frontmatter. Cette competence a besoin de Bash pour executer le script, mais une competence en lecture seule comme un analyseur de code pourrait se restreindre a Read, Grep, Glob — limitant le rayon d'impact en cas de compromission de la competence.

Etape 7 : Ajouter des fichiers de reference (optionnel)

Pour les competences necessitant une documentation abondante, ajoutez des fichiers de reference plutot que de tout entasser dans SKILL.md.

code-review/
├── SKILL.md
├── references/
│   ├── owasp-top-10-checklist.md
│   └── style-guide-summary.md
└── assets/
    └── review-template.md

Dans votre SKILL.md, referencez-les selon les besoins :

## Verifications de securite
 
Pour la liste complete OWASP, lisez `references/owasp-top-10-checklist.md`.
Concentrez-vous sur ces cinq points pour les revues rapides :
1. Injection SQL dans les parametres de requete
2. XSS dans le contenu rendu par l'utilisateur
3. Flux d'authentification defaillants
4. Exposition de donnees sensibles dans les logs
5. Controles d'acces manquants

L'agent ne charge owasp-top-10-checklist.md que s'il a besoin de la liste complete — economisant des tokens lors des revues de routine.

Etape 8 : Tester vos competences

Test d'activation

Ouvrez votre outil de codage IA et testez ces invites :

Devrait activer code-review :

• "Review this PR"
• "Check my latest changes for issues"
• "Audit the auth module"
• "Look at my diff"

Devrait activer deploy-checker :

• "Are we ready to deploy?"
• "Run pre-deploy checks"
• "Can we ship this to production?"

Ne devrait activer aucune des deux :

• "Write a new API endpoint"
• "Explain how this function works"
• "Refactor the database layer"

Test de qualite des instructions

Apres l'activation, verifiez que l'agent suit vos instructions :

• La revue de code utilise-t-elle le format de sortie a trois niveaux (Critique / Avertissement / Suggestion) ?
• Le verificateur de deploiement execute-t-il le script shell ?
• Les numeros de ligne sont-ils references dans les retours de revue ?

Si la competence s'active mais que les instructions ne sont pas suivies, le corps a besoin d'un langage imperatif plus clair.

Etape 9 : Installer des competences personnelles (globales)

Les competences dans .agents/skills/ sont limitees au projet. Pour les competences que vous souhaitez avoir dans tous vos projets, installez-les dans votre repertoire personnel :

mkdir -p ~/.agents/skills/my-global-skill

Les competences globales sont utiles pour les flux de travail personnels — votre format de message de commit prefere, votre checklist de debogage, votre style de documentation. Les competences de projet sont destinees aux procedures partagees en equipe.

Priorite : Les competences de projet ecrasent les competences globales portant le meme nom.

Etape 10 : Verification multiplateforme

Vos competences doivent fonctionner sans modification sur tous les outils compatibles. Voici une liste de verification :

Si vous avez place vos competences dans .agents/skills/, les six outils les trouveront automatiquement. Aucune duplication necessaire.

Depannage

La competence ne s'active jamais

Cause : La description ne correspond pas assez precisement aux invites de l'utilisateur.

Solution : Ajoutez plus de phrases de declenchement. Incluez des variations formelles ("review code") et informelles ("check my stuff").

La competence s'active mais les instructions sont ignorees

Cause : Les instructions sont trop vagues ou utilisent la voix passive.

Solution : Reecrivez a la voix imperative avec des actions specifiques. "Executez npm test" au lieu de "Les tests devraient etre executes."

Budget de tokens depasse

Cause : Le corps du SKILL.md depasse 5 000 tokens.

Solution : Deplacez le materiel de reference dans des fichiers separes dans references/. Ne gardez que le flux de travail principal dans SKILL.md.

Permission refusee pour le script

Cause : Les scripts integres n'ont pas les permissions d'execution.

Solution : Executez chmod +x .agents/skills/deploy-checker/scripts/check_deploy.sh ou faites en sorte que les instructions de la competence invoquent avec bash explicitement.

Considerations de securite

Les competences sont des instructions privilegiees. Une competence malveillante peut diriger un agent pour :

• Executer des commandes shell arbitraires
• Exfiltrer du code ou des identifiants
• Modifier des fichiers en dehors du projet
• Recuperer du contenu depuis des URL externes (vecteur d'injection de prompt)

Avant d'installer des competences tierces :

1. Lisez chaque ligne du SKILL.md et tous les scripts integres
2. Verifiez l'absence d'appels reseau inattendus (curl, wget, fetch)
3. Recherchez tout acces a des fichiers en dehors du repertoire du projet
4. Verifiez la reputation de la source
5. Utilisez allowed-tools pour restreindre les capacites

Resume des bonnes pratiques

Prochaines etapes

• Lisez la vue d'ensemble de la specification Agent Skills pour les details d'architecture
• Explorez les Agent Skills pour les equipes metier pour deployer les competences dans votre organisation
• Parcourez le depot communautaire awesome-agent-skills sur GitHub pour trouver de l'inspiration
• Envisagez un audit professionnel de competences si vous souhaitez une optimisation experte de la bibliotheque de competences de votre equipe

Conclusion

Ecrire votre premier SKILL.md prend moins de dix minutes. Le retour sur investissement est immediat — votre agent de codage IA active les bonnes instructions pour la bonne tache, utilise moins de tokens et fonctionne de maniere identique sur chaque outil de votre stack.

Commencez par une competence pour votre flux de travail le plus repete. Testez-la, affinez la description et commitez-la dans votre depot. Puis construisez a partir de la.

Besoin d'aide pour construire une bibliotheque de competences personnalisee pour votre equipe d'ingenierie ? Noqta propose du conseil en Agent Skills — du developpement de competences individuelles a la gouvernance des competences a l'echelle de l'entreprise et aux audits de securite.