Skills-Debugging

Nachdem du einen Skill geschrieben hast, stößt du oft auf Probleme wie "nicht ausgelöst", "Ausführungsfehler" oder "falsche Ausgabe".

Dieser Artikel stellt die grundlegenden Ansätze und Methoden zur Fehlersuche bei diesen Problemen vor.

Drei häufige Arten von Debugging-Problemen

Problemtyp Symptom Prioritätsprüfung
Nicht ausgelöst Claude verwendet den Skill überhaupt nicht Formulierung der Beschreibung, Aufgabenkomplexität
Ausgelöst, aber Ausführungsfehler Der Skill wird gelesen, aber das Skript kann nicht ausgeführt werden Skriptpfad, Abhängigkeiten, Parameterformat
Ausgelöst und ausgeführt, aber das Ergebnis entspricht nicht den Erwartungen Ausgabeinhalt weicht von den Erwartungen ab Klarheit der Anweisungen in SKILL.md

Debugging-Problem 1: Skill wird nicht ausgelöst

Dies ist das häufigste Problem. Die Schritte zur Fehlerbehebung sind wie folgt:

Schritt 1: Bestätigen, dass die Skill-Datei korrekt geladen ist

Beispiel

# Prüfen, ob die Skill-Verzeichnisstruktur korrekt ist
ls -la my-skill/

# Bestätigen, dass SKILL.md existiert und nicht leer ist
wc -l my-skill/SKILL.md
-rw-r--r-- 1 user user  842 May 18 10:00 SKILL.md

Schritt 2: Das YAML-Frontmatter-Format prüfen

Eine falsche Formatierung des Frontmatters kann verhindern, dass der Skill erkannt wird.

---
name: my-skill
description: 这是一个示例 Skill，处理用户上传的文本文件。
---

# My Skill
...

Frontmatter muss---beginnen und enden mit,nameunddescriptionFeldnamen dürfen keine zusätzlichen Leerzeichen enthalten, und nach dem Doppelpunkt muss ein Leerzeichen stehen.

Schritt 3: Komplexere Test-Prompts verwenden

Einfache Aufgaben (wie "diese Datei lesen") können den Skill möglicherweise nicht auslösen.

Ändern Sie den Test-Prompt in eine komplexe Anfrage mit mehreren Schritten und klaren Anforderungen an das Ausgabeformat.

Prompts, die weniger wahrscheinlich auslösen Prompts, die wahrscheinlicher auslösen
"Diese Datei analysieren" "Analysieren Sie diese CSV-Verkaufsdaten, identifizieren Sie monatliche Wachstumstrends und erstellen Sie eine statistische Übersichtstabelle"
"Eine PPT erstellen" "Erstellen Sie basierend auf diesem Bericht eine 10-seitige Produktpräsentation mit Diagrammen und einer Zusammenfassung"

Debugging-Problem 2: Fehler bei der Skriptausführung

Wenn ein Skript mit einem Fehler abbricht, erscheint die Fehlermeldung in der Befehlszeilenausgabe.

In einer Claude-Sitzung können Sie Claude direkt bitten, das Skript auszuführen und die Ausgabe anzuzeigen:

Beispiel

# Führen Sie das Skript manuell aus und prüfen Sie die Fehlerausgabe
python scripts/process.py /mnt/user-data/uploads/test.csv

# Fügen Sie den Parameter -v (verbose) hinzu, um detaillierte Protokolle anzuzeigen (falls das Skript dies unterstützt)
python scripts/process.py /mnt/user-data/uploads/test.csv --verbose

Häufige Fehlertypen und Lösungen

Fehlermeldung Ursache Beheben
ModuleNotFoundError: No module named 'pandas' Abhängigkeit nicht installiert Führen Siepip install pandas --break-system-packages
FileNotFoundError: [Errno 2] Falscher Dateipfad Prüfen Sie, ob sich die Datei in/mnt/user-data/uploads/
PermissionError: [Errno 13] Keine Schreibberechtigung Ändern Sie das Ausgabeziel in/mnt/user-data/outputs/
SyntaxError Skript-Syntaxfehler Verwenden Siepython -m py_compile 脚本名.pyPrüfen

Schnelle Syntaxprüfung

Beispiel

# Python-Skript-Syntax prüfen (wird nicht ausgeführt, validiert nur die Syntax)
python -m py_compile scripts/process.py && echo "Syntax ist korrekt" || echo "Syntaxfehler"

# Shell-Skript-Syntax prüfen
bash -n scripts/run.sh && echo "Syntax ist korrekt" || echo "Syntaxfehler"
Grammatically correct.

Debugging-Problem 3: Ausgabe entspricht nicht den Erwartungen

Diese Art von Problem resultiert normalerweise aus unklaren oder mehrdeutigen Anweisungen in SKILL.md.

Fehlerbehebungsmethode: Schritt für Schritt eingrenzen

Fügen Sie vorübergehend Debug-Ausgabeanweisungen zu SKILL.md hinzu, um Claudes Verständnis bei jedem Schritt zu beobachten:

## 调试模式（开发时使用，发布前删除）

执行前，先输出以下信息供确认：
1. 识别到的输入文件路径
2. 用户期望的输出格式
3. 计划执行的步骤列表

等待用户确认后再继续执行。

Häufige Probleme mit mehrdeutigen Anweisungen

Vage Formulierung Klare Formulierung
"Geben Sie die Ergebnisse aus, nachdem die Verarbeitung abgeschlossen ist" "Speichern Sie die Ergebnisse im Verzeichnis /mnt/user-data/outputs/ und zeigen Sie den Dateipfad in der Konversation an"
"Analysieren Sie die Daten" "Berechnen Sie den Mittelwert, den Median und die Standardabweichung jeder Spalte und geben Sie sie im Markdown-Tabellenformat aus"
"Erstellen Sie einen Bericht" "Erzeuge eine HTML-Datei, die einen Zusammenfassungsabsatz, eine Datentabelle und ein Fazit enthält, und speichere sie im Ausgabeverzeichnis"

Verwenden von print zum Debuggen im Skript

Das Hinzufügen von print-Anweisungen an wichtigen Stellen im Skript ist der direkteste Weg, um Probleme mit dem Ausführungsfluss zu beheben.

Beispiel

# Dateipfad: scripts/debug_example.py
import sys

def process_file(file_path: str):
    print(f"[DEBUG] Beginne mit der Verarbeitung der Datei: {file_path}")  # Debug-Punkt 1

    with open(file_path, "r", encoding="utf-8") as f:
        content = f.read()

    print(f"[DEBUG] Datei erfolgreich gelesen, Größe: {len(content)} bytes")  # Debug-Punkt 2

    lines = content.split("\n")
    print(f"[DEBUG] Gesamtzahl der Zeilen: {len(lines)}")  # Debug-Punkt 3

    # Tatsächliche Verarbeitungslogik
    result = [line.strip() for line in lines if line.strip()]
    print(f"[DEBUG] Gültige Zeilen nach der Verarbeitung: {len(result)}")  # Debug-Punkt 4

    return result

if __name__ == "__main__":
    output = process_file(sys.argv[1])
    print("\n"--- Verarbeitungsergebnis ---")
    for line in output[:5]:  # Nur die ersten 5 Zeilen anzeigen
        print(line)
[DEBUG] 开始处理文件：/mnt/user-data/uploads/sample.txt
[DEBUG] 文件读取成功，大小：1024 字节
[DEBUG] 总行数：32
[DEBUG] 处理后有效行数：28

--- 处理结果 ---
第一行内容
第二行内容
...

Nach Abschluss des Debuggens denken Sie daran,[DEBUG]die print-Anweisungen, die mit [DEBUG] beginnen, zu löschen, um zu vermeiden, dass Debug-Informationen in die formale Ausgabe eingemischt werden.

Andere Erweiterungen