Tipps zur Optimierung von Skills-Beschreibungen

Das description-Feld ist die einzige Grundlage für die Entscheidung, ob ein Skill ausgelöst wird.

Eine gut geschriebene Beschreibung sorgt dafür, dass der Skill zum richtigen Zeitpunkt ausgelöst wird, und vermeidet, Claude in irrelevanten Szenarien zu stören.


Die Rolle und Grenzen der Beschreibung

Wenn entschieden wird, ob ein Skill verwendet werden soll, liest Claude nur das description-Feld und liest den Inhalt von SKILL.md nicht im Voraus.

Das bedeutet, dass die Beschreibung zwei Dinge gleichzeitig leisten muss: erklären, was der Skill kann, und angeben, wann er verwendet werden sollte.

Die ideale Länge für eine Beschreibung beträgt 50-150 Zeichen. Eine zu kurze Beschreibung führt zu ungenauem Auslösen; eine zu lange kann die Kontextgrenzen überschreiten, und Claude wird Schwierigkeiten haben, schnell zu scannen und zu vergleichen.


Die Vier-Elemente-Struktur der Beschreibung

ElementZweckBeispiel
Kernfunktion in einem SatzGibt am direktesten an, was der Skill ist"Tabellenkalkulationsdaten in Excel- und CSV-Formaten verarbeiten"
Liste spezifischer Fähigkeiten3-5 typische Operationen auflisten"Einschließlich Datenbereinigung, statistischer Analyse, Diagrammerstellung"
Beschreibung des AuslöseszenariosTeilt Claude mit, wann es verwendet werden sollte"Auslösen, wenn der Benutzer Datenanalyse, Berichte oder Statistiken erwähnt"
Werbeaussage (optional)Löst das Problem der "niedrigen Auslöserate""Auch wenn der Benutzer das Format nicht ausdrücklich erwähnt, sollte es verwendet werden, wann immer tabellarische Daten involviert sind"
---
name: data-analyzer
description: >
  处理 Excel(.xlsx)和 CSV 格式的表格数据,包括数据读取、
  清洗去重、统计分析(均值/中位数/分布)、生成可视化报告。
  当用户需要分析数据文件、生成统计报告、处理表格、
  查找数据规律时应优先使用此 Skill,即使用户只是上传了
  一个数据文件并询问"帮我看看这个"。
---

Häufige Probleme beim Schreiben von Beschreibungen

ProblemBeispiel (inkorrekt)Korrekturrichtung
Nur Funktionen schreiben, keine Trigger-Szenarien"Ein Tool zur Datenanalyse"Füge "Auslösen, wenn der Benutzer..." hinzu
Beschreibung ist zu allgemein"Ein Allzweckwerkzeug zur Verarbeitung von Dateien"Spezifische Dateitypen und Operationen auflisten
Skill-interne Implementierungsterminologie verwenden"pandas zur Analyse aufrufen"Zu einer fachlichen Beschreibung aus der Nutzerperspektive ändern
Unklare Abgrenzung zu anderen SkillsBeide Skills sagen "Dokumente verarbeiten"Die Dateitypen oder Operationstypen der einzelnen Skills klar unterscheiden

Beschreibung mit automatisierten Tools optimieren

skill-creator bietet ein Skript zur automatischen Optimierung von Beschreibungen, das iteratives Testen nutzt, um den Schreibstil mit der höchsten Auslöserate zu finden.

Schritt 1: Testfälle vorbereiten

Beispiel

[
  {
    "id": "should_trigger_01",
    "prompt": "Hilf mir, example_sales.csv zu analysieren und den monatlichen Verkaufstrend zu finden",
    "expected": true,
    "note": Typische Datenanalyse-Anfrage
  },
  {
    "id": "should_trigger_02",
    "prompt": "Welche Spalten in dieser Excel-Datei haben leere Werte? Hilf mir, sie zu zählen.",
    "expected": true,
    "note": Umfasst die Prüfung der Datenqualität
  },
  {
    "id": "should_not_trigger_01",
    "prompt": "Was ist der Unterschied zwischen Excel und CSV?",
    "expected": false,
    "note": Wissens-Q&A, kein Skill erforderlich
  },
  {
    "id": "should_not_trigger_02",
    "prompt": "Hilf mir, eine E-Mail zu schreiben",
    "expected": false,
    "note": Völlig unzusammenhängende Aufgabe
  }
]

Schritt 2: Optimierungsschleife ausführen

Beispiel

# Beschreibungs-Auto-Optimierung ausführen
# Das Skript wird automatisch: evaluieren → ändern → erneut evaluieren, 5 Mal wiederholt
python -m scripts.run_loop \
  --eval-set evals/trigger-eval.json \
  --skill-path data-analyzer/ \
  --model claude-sonnet-4-20250514 \
  --max-iterations 5 \
  --verbose
迭代 1:训练集得分 0.62,测试集得分 0.60
迭代 2:训练集得分 0.75,测试集得分 0.72
迭代 3:训练集得分 0.87,测试集得分 0.85
迭代 4:训练集得分 0.90,测试集得分 0.88
迭代 5:训练集得分 0.91,测试集得分 0.89

最优 description(测试集得分 0.89)已保存。

Schritt 3: Optimales Ergebnis anwenden

Beispiel

# Das Skript gibt das Feld best_description aus; ersetzen Sie damit die Beschreibung in SKILL.md
# Vor der Optimierung
grep "description:" data-analyzer/SKILL.md

# Manuell oder mit einem Skript: Ersetzen Sie es durch den Inhalt von best_description
# Skill nach der Ersetzung neu paketieren
python -m scripts.package_skill data-analyzer/

A/B-Vergleichstest

Wenn Sie unsicher sind, welcher Schreibstil besser ist, können Sie einen Blindtest-Vergleich der beiden Versionen der Beschreibung durchführen.

Beispiel

# Version A: aktuelle Beschreibung
# Version B: neue Beschreibung als Kandidat

# Evaluationen separat ausführen
python -m scripts.run_eval \
  --eval-set evals/trigger-eval.json \
  --skill-path data-analyzer-v1/ \
  --output evals/results_v1.json

python -m scripts.run_eval \
  --eval-set evals/trigger-eval.json \
  --skill-path data-analyzer-v2/ \
  --output evals/results_v2.json

# Vergleichsbericht generieren
python eval-viewer/generate_review.py \
  --results evals/results_v1.json evals/results_v2.json \
  --compare \
  --output evals/comparison.html

Die Evaluierung sollte auf dem Testset-Score basieren, nicht auf dem Trainingsset-Score. Wenn der Trainingsset-Score hoch, aber der Testset-Score niedrig ist, bedeutet das, dass die Beschreibung ein Overfitting auf die Testfälle betrieben hat, und ihre Leistung in realen Szenarien kann sich verschlechtern.

Andere Erweiterungen