Skill Doctor —— Outil de Diagnostic de Compétences
Processus
- Lire le répertoire de la compétence spécifié
- Vérifier l'existence des fichiers essentiels (SKILL.md, gotchas.md, etc.)
- Appeler le script pour obtenir un rapport structuré :
python scripts/analyze_skill.py <skill_path> --output json, obtenir le score, les problèmes et les suggestions pour chaque élément - Pour chaque élément à faible score (<70), compléter les suggestions d'optimisation spécifiques basées sur le rapport du script + score attendu après amélioration + estimation de l'effort
- Lister tous les éléments optimisables et laisser l'utilisateur choisir lesquels accepter
- Optimiser un par un les éléments acceptés par l'utilisateur (modifier directement les fichiers)
- Une fois les optimisations terminées, relancer le diagnostic pour générer un rapport comparatif avant/après
L'agent gère la couche intelligente (suggestions d'optimisation, interaction utilisateur, exécution des modifications), le script gère la couche stable (calcul des scores, sortie structurée). Voir l'utilisation du script dans scripts/analyze_skill.py.
Neuf Dimensions du Diagnostic
| Élément | Contenu de la vérification | Critère de succès |
|---|---|---|
| Vérification description | Vérifier si elle est rédigée comme une condition de déclenchement, pas une description de fonctionnalité | Contient des mots-clés de déclenchement, longueur <100 caractères |
| Vérification gotchas | Vérifier l'existence de notes sur les pièges | gotchas.md existe et n'est pas vide |
| Vérification organisation des fichiers | Vérifier l'organisation selon les trois catégories standard | Le répertoire racine contient uniquement SKILL.md, gotchas.md, examples.md ; les documents de référence dans reference/, les scripts dans scripts/, les configurations dans config/ |
| Vérification sur-contrainte | Vérifier les chemins trop rigides | Pas de processus figés du type "première étape, deuxième étape" |
| Vérification connaissance connue | Vérifier si le contenu répète ce que l'agent connaît déjà | Pas de tutoriels du type "Qu'est-ce que X" ou "Comment utiliser Y" |
| Vérification configuration mémoire | Vérifier l'existence de config.json | config.json existe avec une configuration appropriée |
| Vérification scripts | Vérifier si un script est nécessaire mais manquant | Si une capacité stable est nécessaire, un répertoire scripts/ doit exister |
| Vérification hooks | Vérifier la configuration des hooks | Format correct de PreToolUse/PostToolUse |
| Vérification format markdown | Vérifier la conformité du format | YAML, tableaux, blocs de code correctement formatés |
Format du Rapport de Diagnostic
{
"skill_name": "xxx",
"overall_score": 55,
"grade": "D",
"check_results": {
"description": {"score": 50, "issues": ["Rédigé comme une description de fonctionnalité"], "suggestions": ["Remplacer par une formulation de condition de déclenchement"], "expected_gain": 40},
"gotchas": {"score": 40, "issues": ["gotchas.md est vide"], "suggestions": ["Ajouter au moins 3 vrais pièges"], "expected_gain": 50}
},
"optimization_options": [
{"id": 1, "item": "description", "current_score": 50, "expected_score": 90, "gain": 40,
"effort": "Faible", "action": "Réécrire la description en condition de déclenchement",
"token_saved_per_call": 50, "time_saved_per_call_sec": 0},
{"id": 2, "item": "gotchas", "current_score": 40, "expected_score": 90, "gain": 50,
"effort": "Moyen", "action": "Ajouter de vrais pièges",
"token_saved_per_call": 0, "time_saved_per_call_sec": 180}
],
"overall_after_accept_all": 85,
"total_benefits": {
"token_saved_per_call": 200,
"time_saved_per_call_sec": 300
}
}
Règles d'Estimation des Bénéfices
| Type d'optimisation | Économie de Tokens (par appel) | Économie de Temps (par appel) | Description |
|---|---|---|---|
| Réduction de description | ×1 token par caractère superflu | — | Réduire la charge du contexte |
| Complément gotchas | — | 2-5 minutes par piège | Éviter de répéter les erreurs de débogage |
| Découpage de fichiers | (lignes originales - nouvelles lignes)×3 tokens | — | Déplacer les documents de référence dans reference/, chargés à la demande hors contexte |
| Sur-contrainte→Cadre décisionnel | ×20 tokens par étape rigide | 10-30 secondes par étape | Réduire l'exécution d'étapes inutile |
| Suppression de connaissances connues | Longueur du paragraphe tuto en tokens | — | Ne pas répéter ce que l'agent connaît déjà |
| Encapsulation par script | — | 1-3 minutes par appel | Éviter que l'agent réécrive le même code à chaque fois |
Les bénéfices sont des estimations par appel. Les valeurs réelles varient selon le contenu et l'utilisation de la compétence.
À propos du 'temps perdu' : dans le rapport, le 'temps perdu' fait référence au gaspillage supplémentaire dû à des défauts de conception, et non à la durée totale d'exécution de la compétence. Cela inclut :
- gotchas manquants → L'agent répète les erreurs de débogage (2-5 minutes par occurrence)
- Sur-contrainte → L'agent exécute des étapes rigides et inutiles (10-30 secondes par étape)
- Script manquant → L'agent réécrit le même code à chaque appel (1-3 minutes par appel)
Logique de comparaison : La valeur avant optimisation = somme de ces gaspillages ; après optimisation, le gaspillage est éliminé → ~0 ; 'Économie' = quantité de gaspillage éliminée. Après optimisation, l'exécution de la compétence elle-même prend encore du temps, mais ces pertes supplémentaires disparaissent.
Présentation des Suggestions d'Optimisation
Après avoir généré le rapport, présenter les éléments optimisables sous forme de liste à l'utilisateur, chaque élément comprenant :
### 🔧 Éléments Optimisables
| # | Élément | Score actuel | Score attendu | Gain | Effort | Tokens/appel | Temps/appel | Action |
|---|---------|--------------|---------------|------|--------|--------------|-------------|--------|
| 1 | description | 50 | 90 | +40 | Faible | ~50 | — | Réécrire en condition de déclenchement |
| 2 | gotchas | 40 | 90 | +50 | Moyen | — | ~3min | Ajouter de vrais pièges |
| ... | ... | ... | ... | ... | ... | ... | ... | ... |
**Après avoir accepté toutes les optimisations** : 55 (D) → 85 (B), gain de 30 points
### 📈 Bénéfices Globaux (par appel)
- Économie de Tokens : ~200/appel
- Économie de Temps : ~5 minutes/appel
- Évitement de pièges : après ajout de gotchas, erreurs courantes évitées
> **Périmètre des statistiques de temps** : Ici, 'économie de temps' fait référence au **gaspillage supplémentaire dû à des défauts de conception**, et non à la durée totale d'exécution de la compétence :
> - gotchas manquants → L'agent répète les erreurs de débogage (2-5 minutes par occurrence)
> - Sur-contrainte → L'agent exécute des étapes rigides et inutiles (10-30 secondes par étape)
> - Script manquant → L'agent réécrit le même code à chaque appel (1-3 minutes par appel)
> - Valeur avant optimisation = somme des gaspillages, après optimisation le gaspillage est éliminé, 'Économie' = quantité de gaspillage éliminée
Veuillez choisir :
- **"Tout accepter"** — Optimiser tous les éléments en un clic
- **"Accepter 1,3"** — Optimiser uniquement les éléments spécifiés
- **"Ignorer"** — Afficher le rapport sans optimiser
Exécution après Confirmation de l'Utilisateur
- Après le choix de l'utilisateur, modifier les fichiers correspondants un par un
- Marquer l'état après chaque étape terminée
- Une fois toutes les étapes terminées, relancer le diagnostic pour générer un rapport comparatif
Format du Rapport Comparatif Avant/Après
## 📊 Comparaison Avant/Après
| Élément | Avant | Après | Changement |
|---------|-------|-------|------------|
| description | 50 (description fonction) | 90 (condition de déclenchement) | +40 ⬆️ |
| gotchas | 40 (vide) | 90 (complété) | +50 ⬆️ |
| ... | ... | ... | ... |
| **Score total** | **55 (D)** | **85 (B)** | **+30 ⬆️** |
### 📈 Bénéfices Globaux (par appel)
| Dimension | Avant | Après | Économie |
|-----------|-------|-------|----------|
| Tokens | ~800/appel | ~600/appel | ~200/appel |
| Temps perdu | ~5min | ~0 | ~5min |
| Fichier principal | 466 lignes | 75 lignes | -84% |
> Temps perdu = surcoût dû aux défauts de conception (débogage de pièges, étapes redondantes, etc.), pas la durée totale d'exécution de la compétence. Voir [Règles d'Estimation des Bénéfices](#règles-destimation-des-bénéfices).
### Fichiers Modifiés
- `SKILL.md` — Réécriture de la description
- `gotchas.md` — Ajout de 5 vrais pièges
Exemple d'Interaction Complet
Voir l'exemple 9 dans examples.md
Niveaux de Score
- A (90-100 points) : Excellent, suit toutes les bonnes pratiques
- B (75-89 points) : Bon, avec une marge d'optimisation mineure
- C (60-74 points) : Satisfaisant, avec des points d'amélioration évidents
- D (<60 points) : Insuffisant, nécessite une refonte
Liste de Vérification Détaillée
Voir checklists.md
Pièges Courants
Voir gotchas.md
Exemples d'Optimisation
Voir examples.md
Scripts
La logique centrale du diagnostic est encapsulée dans scripts/analyze_skill.py. L'agent l'appelle pour obtenir un score structuré :
python scripts/analyze_skill.py <skill_path> --output json # Étape 3 : obtenir un rapport de score
python scripts/analyze_skill.py <skill_path> --output markdown # Optionnel : générer un rapport lisible par l'homme
Le script est responsable : calcul des scores, détection des problèmes, attribution des niveaux (couche stable) L'agent est responsable : génération des suggestions d'optimisation, interaction utilisateur, exécution des modifications de fichiers (couche intelligente)