# Notes Claude Skills en production

Brouillon perso — observations après 3 mois de déploiement (12 skills en prod).
Sources : retours user, logs Sentry, conversations Slack équipe.

## Ce qui marche vraiment

### 1. Skill atomique > skill monolithique
Mes premiers skills faisaient 800 lignes de prompt avec 15 conditions. Catastrophe maintenable.
Refactor : chaque skill ≤ 200 lignes, une seule responsabilité. Composer via chaining.
Résultat : -60% latence, +40% précision sur les classes les plus utilisées.

### 2. Le nom du skill est l'API
Claude lit le titre + 1ère ligne pour décider d'invoquer. Si flou → skill jamais déclenché.
Bonnes patterns observées :
- "format-monetary-amount" (verbe-objet)
- "detect-pii-in-text" (verbe-objet-contexte)
Mauvais : "helper", "utility", "data-processor"

### 3. Une instruction de déclenchement OU rien
Sans guard explicite, Claude invoque le skill à des moments aléatoires.
Pattern : "Use this skill WHEN the user asks for X. Do NOT use for Y or Z."

## Erreurs récurrentes (vues 3+ fois)

### A. Skills qui se chevauchent
Deux skills "format-currency" et "format-money" → Claude alterne aléatoirement.
Fix : audit lexical mensuel, fusionner ou différencier sémantiquement.

### B. Output non contractuel
Un skill renvoie tantôt du JSON, tantôt du markdown. Le caller suivant casse.
Fix : `<output_format>` strict en bas du skill. Tester via 20 cas avant prod.

### C. Skill qui appelle un skill qui appelle un skill (3 niveaux)
Latence x3, et un debug nightmare. Logs perdus.
Fix : max 2 niveaux. Au-delà → composer un workflow explicite côté code.

## Mesures opérationnelles

- Coût moyen par invocation : 0.012€ (Sonnet 4.6)
- Latence p95 : 1.8s
- Taux d'auto-trigger correct : 87% (objectif 95%)
- Skills mort-nés en 30 jours : 4 sur 16 créés

## Questions ouvertes

1. Comment versionner sans casser les callers existants ?
   → SemVer dans le nom : `extract-receipt-v1` ? Trop lourd.
2. Faut-il un registry centralisé des skills ?
   → Pour 12 skills non, pour 50+ oui. Threshold à valider.
3. Quel KPI pour "skill mort" ?
   → < 5 invocations/30j ET pas dans workflow critique → deprecate.

## Action items

- [ ] Audit lexical octobre : éliminer les chevauchements
- [ ] Migration vers skills atomiques pour les 4 monolithes restants
- [ ] Setup dashboard Grafana (invocations / coût / latence par skill)
- [ ] Doc "Skill design guide" pour onboard les 2 nouveaux devs

---
Note pour plus tard : le module Captiv pourrait servir de skill `generate-resource-from-post` — à creuser semaine prochaine.