Débogage des compétences
Après avoir écrit un Skill, vous rencontrez souvent des problèmes tels que « non déclenché », « erreur d'exécution » ou « sortie incorrecte ».
Cet article présente les approches et méthodes de base pour dépanner ces problèmes.
Trois types courants de problèmes de débogage
| Type de problème | Symptôme | Vérification prioritaire |
|---|---|---|
| Non déclenché | Claude n'utilise pas du tout le Skill | formulation de la description, complexité de la tâche |
| Déclenché mais erreur d'exécution | La compétence est lue, mais le script ne s'exécute pas | Chemin du script, dépendances, format des paramètres |
| Déclenché et exécuté, mais le résultat ne correspond pas aux attentes | Le contenu de sortie diffère des attentes | Clarté des instructions dans SKILL.md |
Problème de débogage 1 : Compétence non déclenchée
C'est le problème le plus courant. Les étapes de dépannage sont les suivantes :
Étape 1 : Confirmez que le fichier de compétence est chargé correctement
Exemple
ls -la my-skill/
# Confirmer que SKILL.md existe et n'est pas vide
wc -l my-skill/SKILL.md
-rw-r--r-- 1 user user 842 May 18 10:00 SKILL.md
Étape 2 : Vérifier le format du frontmatter YAML
Un formatage incorrect du frontmatter peut empêcher la compétence d'être reconnue.
--- name: my-skill description: 这是一个示例 Skill，处理用户上传的文本文件。 --- # My Skill ...
frontmatter doit
---commencer et se terminer par,nameetdescriptionLes noms de champs ne doivent pas contenir d'espaces supplémentaires, et il doit y avoir un espace après le deux-points.
Étape 3 : Utiliser des prompts de test plus complexes
Les tâches simples (comme « lire ce fichier ») peuvent ne pas déclencher la compétence.
Remplacez le prompt de test par une requête complexe comportant plusieurs étapes et des exigences claires de format de sortie.
| Prompts moins susceptibles de déclencher | Prompts plus susceptibles de déclencher |
|---|---|
| "Analyser ce fichier" | "Analysez ce fichier CSV de données de ventes, identifiez les tendances de croissance mensuelles et générez un tableau récapitulatif statistique" |
| "Générer un PPT" | "À partir de ce rapport, créez une présentation d'introduction produit de 10 pages avec des graphiques et un résumé" |
Problème de débogage 2 : Erreurs d'exécution de script
Lorsqu'un script échoue, le message d'erreur apparaît dans la sortie de la ligne de commande.
Dans une session Claude, vous pouvez demander directement à Claude d'exécuter le script et d'afficher la sortie :
Exemple
python scripts/process.py /mnt/user-data/uploads/test.csv
# Ajouter le paramètre -v (verbose) pour afficher les journaux détaillés (si le script le prend en charge)
python scripts/process.py /mnt/user-data/uploads/test.csv --verbose
Types d'erreurs courantes et corrections
| Message d'erreur | Cause | Corriger |
|---|---|---|
ModuleNotFoundError: No module named 'pandas' |
Dépendance non installée | Exécutezpip install pandas --break-system-packages |
FileNotFoundError: [Errno 2] |
Chemin de fichier incorrect | Vérifiez si le fichier se trouve dans/mnt/user-data/uploads/ |
PermissionError: [Errno 13] |
Aucune permission d'écriture | Modifiez la cible de sortie vers/mnt/user-data/outputs/ |
SyntaxError |
Erreur de syntaxe du script | usepython -m py_compile 脚本名.pyVérifier |
Vérification rapide de la syntaxe
Exemple
python -m py_compile scripts/process.py && echo "La syntaxe est correcte" || echo "Erreur de syntaxe"
# Vérifier la syntaxe d'un script Shell
bash -n scripts/run.sh && echo "La syntaxe est correcte" || echo "Erreur de syntaxe"
Grammatically correct.
Problème de débogage 3 : la sortie ne correspond pas aux attentes
Ce type de problème provient généralement d'instructions peu claires ou ambiguës dans SKILL.md.
Méthode de dépannage : isoler le problème étape par étape
Ajoutez temporairement des instructions de sortie de débogage à SKILL.md pour observer la compréhension de Claude à chaque étape :
## 调试模式（开发时使用，发布前删除） 执行前，先输出以下信息供确认： 1. 识别到的输入文件路径 2. 用户期望的输出格式 3. 计划执行的步骤列表 等待用户确认后再继续执行。
Problèmes courants d'ambiguïté des instructions
| Formulation vague | Formulation claire |
|---|---|
| "Affichez les résultats une fois le traitement terminé" | "Enregistrez les résultats dans le répertoire /mnt/user-data/outputs/ et affichez le chemin du fichier dans la conversation" |
| "Analysez les données" | "Calculez la moyenne, la médiane et l'écart type de chaque colonne, puis affichez-les dans un tableau au format Markdown" |
| "Générez un rapport" | "Générer un fichier HTML contenant un paragraphe de résumé, un tableau de données et une conclusion, et l'enregistrer dans le répertoire de sortie" |
Utilisation de print pour le débogage dans le script
Ajouter des instructions print à des points clés du script est le moyen le plus direct de résoudre les problèmes de flux d'exécution.
Exemple
import sys
def process_file(file_path: str):
print(f"[DEBUG] Début du traitement du fichier : {file_path}") # Point de débogage 1
with open(file_path, "r", encoding="utf-8") as f:
content = f.read()
print(f"[DEBUG] Fichier lu avec succès, taille : {len(content)} bytes") # Point de débogage 2
lines = content.split("\n")
print(f"[DEBUG] Nombre total de lignes : {len(lines)}") # Point de débogage 3
# Logique de traitement réelle
result = [line.strip() for line in lines if line.strip()]
print(f"[DEBUG] Lignes valides après traitement : {len(result)}") # Point de débogage 4
return result
if __name__ == "__main__":
output = process_file(sys.argv[1])
print("\n"--- Résultat du traitement ---")
for line in output[:5]: # Afficher uniquement les 5 premières lignes
print(line)
[DEBUG] 开始处理文件：/mnt/user-data/uploads/sample.txt [DEBUG] 文件读取成功，大小：1024 字节 [DEBUG] 总行数：32 [DEBUG] 处理后有效行数：28 --- 处理结果 --- 第一行内容 第二行内容 ...
Autres extensionsUne fois le débogage terminé, n'oubliez pas de supprimer
[DEBUG]les instructions print commençant par [DEBUG], afin d'éviter que les informations de débogage ne soient mélangées à la sortie formelle.