Skills: Spezifikationsdesign für Ein-/Ausgabe
Ein exzellenter Skill erledigt nicht nur Aufgaben, sondern definiert auch klar "was er akzeptiert" und "was er erzeugt."
Gute Eingabe-/Ausgabe-Spezifikationen sind die Grundlage für den zuverlässigen Betrieb von Skills.
Warum Eingabe-/Ausgabe-Spezifikationen definieren
Skills sind mit echten Nutzeranfragen konfrontiert, und Eingabeformate variieren endlos.
Ohne klare Spezifikationen wird Claude die Eingabeabsicht selbst erraten, was zu instabilem Verhalten führt.
Spezifikationen sind keine Einschränkungen, sondern klare Handlungsgrenzen für Claude, die Mehrdeutigkeit reduzieren und die Ausgabekonsistenz verbessern.
Die vier Elemente von Eingabe-Spezifikationen
| Element | Beschreibung | Beispiel |
|---|---|---|
| Eingabetyp | Dateien, Text, URLs, Parameter usw. | Vom Nutzer hochgeladene PDF-Datei |
| Formatanforderungen | Dateiendung, Kodierung, Struktur | .csv, UTF-8-Kodierung, erste Zeile ist die Kopfzeile |
| Erforderlich/Optional | Welche Eingaben sind erforderlich | Dateipfad ist erforderlich, Spaltennamen sind optional |
| Standardverhalten | Wie damit umzugehen ist, wenn optionale Parameter nicht angegeben werden | Alle Spalten analysieren, wenn keine Spaltennamen angegeben sind |
Eingabespezifikationen in SKILL.md definieren
Beispiel
### Erforderliche Eingaben
- **Datendatei**: Vom Benutzer hochgeladene`.csv`oder`.xlsx`Datei
- Kodierung: UTF-8(CSV) oder Standard-Excel-Format
- Die erste Zeile muss aus Spaltenüberschriften bestehen
- Die Dateigröße darf 50MB nicht überschreiten
### Optionale Eingaben
- **Zielspalten**: Geben Sie an, welche Spalten analysiert werden sollen; standardmäßig werden alle numerischen Spalten analysiert
- **Ausgabeformat**:`Tabelle`(Tabelle) oder`Text`(Textzusammenfassung), Standard`Tabelle`
- **Genauigkeit**: Anzahl der beizubehaltenden Dezimalstellen, Standard2bits
### Umgang mit fehlenden Eingaben
Wenn keine Datei hochgeladen wurde, informieren Sie den Benutzer:"Bitte laden Sie die zu analysierende CSV- oder Excel-Datei hoch."
Wenn das Dateiformat nicht unterstützt wird, informieren Sie den Benutzer und listen Sie die unterstützten Formate auf.
Die drei Dimensionen der Ausgabespezifikationen
Dimension 1: Ausgabeinhalt
Geben Sie klar an, welche Inhalte ausgegeben werden sollen, und vermeiden Sie Auslassungen oder übermäßige Ausgaben.
Beispiel
Nach Abschluss der Analyse Folgendes angeben:
1. **Statistische Zusammenfassungstabelle**: Zeilenanzahl, Mittelwert, Maximum für jede Spalte/Minimalwert, Anzahl der Nullwerte
2. **Datenqualitätsbericht**: Aufgefundene Probleme auflisten (z. B. zu viele Nullwerte, gemischte Datentypen)
3. **Dateipfad**: Wenn Ausgabedateien erzeugt werden, Download-Pfade angeben
Dimension 2: Ausgabeformat
Geben Sie das Format an, in dem die Ausgabe dargestellt wird, und wo sie gespeichert wird.
| Ausgabeziel | Format | Speicherpfad |
|---|---|---|
| In der Unterhaltung anzeigen | Markdown-Tabellen, Codeblöcke | Keine Speicherung erforderlich |
| Herunterladbare Datei | .xlsx, .pdf, .html | /mnt/user-data/outputs/ |
| Zwischenergebnis | JSON, CSV | /home/claude/(temporär) |
Dimension 3: Ausgabezeitpunkt
Geben Sie an, wann ausgegeben werden soll, ob alles auf einmal ausgegeben oder schrittweise angezeigt werden soll.
Beispiel
1. **Nach dem Lesen der Datei**: Informieren Sie den Benutzer sofort über die grundlegenden Informationen der Datei (Zeilenanzahl, Spaltenanzahl, Größe)
2. **Während der Analyse**: Wenn die Analyse länger als10Sekunden dauert, geben Sie zuerst eine Fortschrittsmeldung aus
3. **Nach Abschluss der Analyse**: Geben Sie die vollständige statistische Zusammenfassung aus
4. **Nachdem die Datei generiert wurde**: Zeigen Sie den Dateipfad an und rufen Sie das Tool present_files auf
Vollständiges Beispiel einer Eingabe-/Ausgabespezifikation
Das Folgende ist eine vollständige Eingabe-/Ausgabespezifikation für einen Skill zur Dokumentzusammenfassung:
Beispiel
name: doc-summarizer
description: >
Zusammenfassungen aus von Benutzern hochgeladenen Dokumenten extrahieren, mit Unterstützung für PDF, Word (.docx) und reinen Text.
Verwenden, wenn Benutzer Dokumentinhalte schnell verstehen, Schlüsselinformationen extrahieren oder Dokumentzusammenfassungen generieren müssen.
---
# Dokumentzusammenfasser
## Eingabespezifikationen
### Erforderlich
- Dokumentdatei (.pdf, .docx oder .txt)
### Optional
- **Zusammenfassungslänge**:`kurz`(3Sätze)/ `mittel`(1Absatz/Absätze))/ `lang`(3Absätze), Standard`mittel`
- **Sprache**: Ausgabesprache, standardmäßig dieselbe wie im Originaltext
- **Fokusrichtung**: Zum Beispiel"Auf den Schlussabschnitt konzentrieren"、"Numerische Daten extrahieren"
### Ausnahmebehandlung
- Datei überschreitet 10MB: Informieren Sie den Benutzer, dass die Datei zu groß ist, und schlagen Sie vor, sie nach dem Aufteilen hochzuladen
- Nicht unterstütztes Format: Listen Sie die unterstützten Formate auf und bitten Sie den Benutzer, erneut hochzuladen
- Dokument ist ein gescanntes Bild und Text kann nicht erkannt werden: Informieren Sie den Benutzer, dass es nicht verarbeitet werden kann, und empfehlen Sie eine Vorverarbeitung mit einem OCR-Tool
## Ausgabespezifikationen
### Ausgabeinhalt (in Reihenfolge)
1. Grundlegende Dokumentinformationen: Titel (falls vorhanden), Seitenanzahl, geschätzte Wortanzahl
2. Kernzusammenfassung: Ausgabe entsprechend der vom Benutzer angegebenen Länge
3. Schlüsselwörter:5-8Themenschlüsselwörter
### Ausgabeformat
- Alles in der Konversation im Markdown-Format anzeigen
- Generieren Sie keine zusätzlichen Dateien, es sei denn, der Benutzer fordert ausdrücklich an, sie zu speichern
### Ausgabebeispiel
---
**Dokument**:example-annual-report.pdf(24Seiten, ungefähr12,000 Wörter)
**Zusammenfassung**: Dieser Bericht bewertet die jährliche Geschäftsleistung von example, wobei das Nutzervolumen im Jahresvergleich wächst35%,
Die Abdeckung der technischen Dokumentation stieg auf98%. Die Umsatzstruktur wird zunehmend diversifizierter, wobei die Umsatzanteile aus Werbung und Mitgliedschaften etwa gleich groß sind.
**Schlüsselwörter**: Jahresbericht, Nutzerwachstum, technische Dokumentation, Umsatzstruktur, Diversifizierung
---
Eingabe-/Ausgabe-Konventionen auf Skriptebene
Wenn das Skill mit Skripten ausgeliefert wird, wird empfohlen, JSON als strukturiertes Eingabe-/Ausgabeformat zu verwenden, damit Claude die Ergebnisse einfach parsen kann.
Beispiel
# Standardisiertes JSON-Eingabe-/Ausgabemuster
import json
import sys
def summarize(file_path: str, length: str = "medium") -> dict:
"""
Dokument zusammenfassen
Parameter:
file_path: Dokumentpfad (erforderlich)
length: Länge der Zusammenfassung, short/medium/long (optional, Standard: medium)
Rückgabe:
dict, das status-, data- oder error-Felder enthält
"""
try:
# Simuliere das Lesen des Dokuments
with open(file_path, "r", encoding="utf-8") as f:
content = f.read()
# Simuliere das Generieren der Zusammenfassung
summary = content[:200] + "..." # Sollte tatsächlich die echte Zusammenfassungslogik aufrufen
return {
"status": "success",
"data": {
"word_count": len(content),
"summary": summary,
"length": length
}
}
except FileNotFoundError:
return {"status": "error", "error": f"Datei nicht gefunden: {file_path}"}
except Exception as e:
return {"status": "error", "error": str(e)}
if __name__ == "__main__":
file_path = sys.argv[1] if len(sys.argv) > 1 else ""
length = sys.argv[2] if len(sys.argv) > 2 else "medium"
result = summarize(file_path, length)
# Einheitliche JSON-Ausgabe für Claude zum Parsen
print(json.dumps(result, ensure_ascii=False, indent=2))
{
"status": "success",
"data": {
"word_count": 12480,
"summary": "example 年度报告回顾了平台在过去一年的业务表现...",
"length": "medium"
}
}
Andere ErweiterungenDie Verwendung von JSON als Ausgabeformat des Skripts ermöglicht es Claude, Ergebnisse stabil zu parsen, ohne auf Vermutungen basierende Interpretationen von Freitext vornehmen zu müssen.