Construire : les skills comme savoir institutionnel

Objectifs

À l’issue de cette leçon, vous serez capable de :

• Transformer une politique appliquée inégalement en skill que Claude applique pendant l’écriture du code
• Adosser une skill à un contrôle déterministe quand la règle doit tenir sans exception

Ce qui change

Les standards de sécurité, les conventions d’API ou les règles de marque vivent dans des documents que l’on consulte quand on y pense. Une skill les met là où le travail se fait : un dossier avec un fichier SKILL.md, dont l’en-tête dit quand elle s’applique et dont le corps dit quoi faire. Claude la charge quand la tâche correspond, et applique la politique pendant qu’il écrit le code, pas en revue des semaines plus tard. Ce qui relève d’une consigne générale du projet a sa place dans CLAUDE.md ; ce qui est une procédure spécialisée, déclenchée par un type de tâche, a sa place dans une skill.

Pour démarrer

• Prérequis : aucun ; un CLAUDE.md aide, sans être nécessaire.
• Infrastructure : une politique, un responsable nommé, et une source de vérité écrite.

Mise en œuvre

1. Choisissez un savoir appliqué de façon inégale aujourd’hui : un standard de sécurité, une convention d’API, une règle de marque.
2. Un ingénieur écrit le SKILL.md à partir de la source de vérité du responsable de la politique, avec l’aide de Claude.
3. Placez-la dans .claude/skills/<nom>/ pour qu’elle accompagne le code, ou diffusez-la à toute l’organisation par un plugin.
4. Vérifiez qu’elle se déclenche : demandez la tâche concernée de plusieurs façons, et confirmez qu’elle se charge à chaque fois.
5. Quand la politique change, modifiez la skill et faites valider la modification par son responsable. Claude Code surveille les dossiers de skills : une modification arrivée dans le dépôt est prise en compte en cours de session, et au plus tard à la session suivante.

---
name: api-securisee
description: Applique le standard de sécurité des API. À utiliser dès qu'on crée ou modifie un point d'accès exposé, qu'on relit du code d'API ou qu'on génère une spécification OpenAPI.
---
# API sécurisée
Quand tu crées ou modifies un point d'accès :
1. Authentification : chaque point d'accès exige le jeton de la passerelle ; aucune route anonyme hors /health.
2. Validation : valide les corps de requête contre le schéma OpenAPI et rejette les champs inconnus.
3. Traçabilité : tout point d'accès qui modifie des données émet un événement d'audit (acteur, action, entité, horodatage).
4. Classification : un champ marqué « sante » ou « pii » dans le schéma n'apparaît jamais dans un journal ni un message d'erreur.
Lance scripts/verifier-points-acces.sh et joins sa sortie à ton résumé.

Une skill conseille ; un hook garantit

Une skill est un contrôle consultatif : elle rend l’application de la politique probable, mais rien n’oblige une session à s’y conformer. Une règle qui doit tenir toujours a besoin d’un contrôle déterministe derrière elle : un hook qui bloque ou signale l’action, ou une vérification qui repasse la règle sur la pull request. La skill rend les violations rares ; le hook les rend quasi impossibles ; la vérification en CI rattrape ce qui serait arrivé sur la branche par un autre chemin.

Pendant la construction, la plupart des actions de Claude sont des modifications de fichiers et des commandes : c’est là que les hooks se déclenchent le plus. Ils peuvent bloquer les modifications de chemins protégés (classes générées, paquet gelé), lancer le formateur et le linter après chaque édition, empêcher des identifiants d’entrer dans le diff, ou adosser une skill dont la règle doit tenir sans exception. Un hook s’exécute à chaque action qui lui correspond : gardez-le rapide et limité au fichier modifié ; les vérifications lourdes, comme toute la suite de tests, ont leur place au commit ou en CI.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/politique-api.sh" }
        ]
      }
    ]
  }
}

Un hook PostToolUse qui sort avec le code 2 montre son message d’erreur à Claude, qui doit alors corriger (la modification a déjà eu lieu) ; pour empêcher l’action elle-même, utilisez un hook PreToolUse, dont la sortie en code 2 bloque l’appel.

Gouvernance et mesure

Les invocations de skills sont tracées dans les sessions, et le responsable de la politique relit les modifications de la skill comme du code.

• Indicateur avancé : le délai entre l’approbation d’un changement de politique et la fusion de la skill mise à jour.
• Indicateur retardé : les remarques de revue qui citent la politique, qui devraient tendre vers zéro. Si ce n’est pas le cas, la skill ne se déclenche pas, ou son texte a dérivé de la politique officielle.

À vous de jouer

Une politique, une skill, un hook. Choisissez une politique appliquée de façon inégale dans votre équipe. Écrivez la skill avec son responsable : une description qui dit quand elle s’applique, un corps qui dit quoi faire. Vérifiez qu’elle se déclenche en demandant la tâche de trois façons différentes. Puis isolez la règle qui doit tenir sans exception, et décrivez le hook qui la garantirait : quel événement, quel filtre, quelle sortie.

Sources officielles : Skills as institutional knowledge (Claude Academy) · The AI-native SDLC playbook — Stage 3: Build · Skills · Hooks reference · Steering Claude Code: skills, hooks, rules, subagents and more

Points clés à retenir

• Une skill met une politique là où se fait le travail : quand elle s’applique, et quoi faire
• Elle accompagne le code dans .claude/skills/ ou se diffuse par plugin ; son responsable valide chaque changement
• Une skill est consultative ; une règle qui doit toujours tenir s’adosse à un hook et à une vérification en CI
• Des hooks rapides et ciblés pendant la construction ; les vérifications lourdes au commit ou en CI