Skill-Verzeichnisstruktur

Das Verständnis der Verzeichnisstruktur und des Funktionsmechanismus eines Skills ist die Grundlage für den Aufbau wartbarer und wiederverwendbarer Fähigkeiten von KI-Agenten.

Dieser Artikel erläutert die Verzeichnisstruktur, die Rolle jeder Datei und den vollständigen Workflow eines standardmäßigen Skills von Grund auf.


Was ist ein Skill

Ein Skill ist eine unabhängige Fähigkeitseinheit, die verwendet wird, um eine bestimmte Art von Aufgabe zu erledigen.

Vergleicht man den Agenten mit einem Betriebssystem, ist ein Skill wie eine Anwendung; vergleicht man den Agenten mit einem Projektmanager, ist ein Skill eine professionelle Fähigkeit, die aufgerufen werden kann.

Häufige Arten von Skills

Im Folgenden finden Sie einige typische Anwendungsszenarien für Skills:

TypeBeschreibungGeeignete Szenarien
PDF-DokumentanalysePDF-Inhalte extrahieren und Zusammenfassungen erstellenDokumentverarbeitung, Informationsextraktion
Web ScrapingAutomatisch Webdaten abrufenDatenerfassung, Informationsüberwachung
SQL-OptimierungSQL-Abfragen analysieren und optimierenLeistungsoptimierung von Datenbanken
DatenstatistikenDatenberechnung und statistische VerarbeitungDatenanalyse, Berichterstellung
BilderkennungInhalte in Bildern erkennenOCR, Bildklassifizierung

Beziehung zwischen Skill und Agent

Ein Skill selbst ist nicht dafür verantwortlich zu entscheiden, wann er verwendet wird; der Agent ist derjenige, der die Entscheidung tatsächlich trifft.

Der vollständige Workflow ist wie folgt:

Skill 工作流程

Wichtiger Punkt: Der Agent lädt nicht den gesamten Inhalt aller Skills auf einmal. Zuerst liest er die Beschreibungsinformationen jedes Skills und lädt erst nach dem Abgleich mit dem Ziel-Skill den vollständigen Inhalt. Der Grund dafür ist: Wenn es Hunderte von Skills gibt, wäre es extrem verschwenderisch mit Tokens, sie jedes Mal alle zu laden.


Standard-Verzeichnisstruktur eines Skills

Ein vollständiger Skill ist keine einzelne Datei, sondern ein Verzeichnis, das mehrere Dateien enthält.

Das Folgende ist die vollständige Verzeichnisstruktur eines Standard-Skills:

my-skill/
│
├── SKILL.md          ← 核心执行文件
├── metadata.json     ← 元信息
├── examples/         ← 示例目录
│   ├── example1.md
│   └── example2.md
│
├── scripts/          ← 可执行脚本
│   ├── main.py
│   └── utils.py
│
├── resources/        ← 资源目录
│   ├── prompt.md
│   └── config.yaml
│
├── tests/            ← 测试目录
│   ├── test_cases.md
│   └── eval.yaml
│
├── README.md         ← 使用说明
│
└── CHANGELOG.md      ← 变更日志

Als Nächstes werden wir den Zweck jeder Datei und jedes Verzeichnisses einzeln aufschlüsseln.


SKILL.md: Zentrale Ausführungsdatei

Dies ist die wichtigste Datei in einem Skill und definiert die gesamte Ausführungslogik des Skills.

Sie enthält die folgenden Schlüsselinformationen:

BereichBeschreibungZweck
BeschreibungFunktionale Beschreibung des SkillsWird für das Agent-Matching verwendet
Wann zu verwendenAnwendbare Szenarien klar definierenFehlauslösungen vermeiden
Wann NICHT zu verwendenNicht anwendbare Szenarien klar definierenKonflikte mit anderen Skills verhindern
EingabeEingabeformat definierenAufrufmethode standardisieren
AnweisungenAusführungsschritteAufgabenausführung anleiten
AusgabeBeschreibung des AusgabeformatsKonsistenz der Ergebnisse sicherstellen

Das Folgende ist ein standardisiertes SKILL.md-Beispiel:

Beispiel

# PDF-Analyse-Skill

## Beschreibung
Wird verwendet, um PDF-Inhalte zu analysieren und Zusammenfassungen zu erstellen.

## Wann zu verwenden

Geeignet für:

- PDF-Lesen
- Zusammenfassungsextraktion
- Inhaltsanalyse

## Wann NICHT zu verwenden

Nicht geeignet für:

- Bildbearbeitung
- Videoverarbeitung

## Eingabe

PDF-Datei

## Anweisungen

1. Text extrahieren
2. Kapitelstruktur identifizieren
3. Hauptinhalt zusammenfassen
4. Kernpunkte ausgeben

## Ausgabe

Zusammenfassung im Markdown-Format

Häufige falsche Schreibstile

Viele Anfänger schreiben eine übermäßig vereinfachte SKILL.md, zum Beispiel:

Nicht empfohlenes Schreibbeispiel

# PDF-Skill

PDF lesen
Inhalt zusammenfassen
Ergebnis zurückgeben

Das Problem mit diesem Schreibstil ist: Er weiß nicht, wann er verwendet werden soll, weiß nicht, wann er nicht verwendet werden soll, das Ausgabeformat ist unklar, und es ist leicht, mit anderen Skills in Konflikt zu geraten.

Eine qualifizierte SKILL.md sollte es dem Agenten ermöglichen, auf einen Blick zu beurteilen: ob dieser Skill für die aktuelle Aufgabe geeignet ist.


metadata.json: Skill-Metadaten

Diese Datei stellt maschinenlesbare strukturierte Daten bereit, um dem Agenten zu helfen, Skills schnell zu filtern.

Beispiel

{
  "name": "pdf-analyzer",
  "version": "1.0.0",
"description": "PDF analysieren und eine Zusammenfassung erstellen",
  "tags": ["pdf", "summary"],
  "category": "document"
}

Allgemeine Feldbeschreibungen

FeldZweckBedeutung
nameSkill-NameErforderlich
descriptionFunktionale Beschreibung; der Agent verlässt sich darauf für den AbgleichAm wichtigsten
versionVersionsnummerEmpfohlen
tagsTags, zur einfachen AuffindbarkeitEmpfohlen
categoryKategorieOptional
authorAutorOptional
permissionsErforderliche BerechtigungenOptional

Unter ihnen ist das Felddescriptionam wichtigsten, weil der Agent sich normalerweise für die Zuordnung darauf verlässt.

Der Matching-Prozess verläuft ungefähr wie folgt: Nachdem der Benutzer eine Anfrage gestellt hat, scannt der Agent die Beschreibungen aller Skills und lädt nach dem Finden einer passenden Beschreibung den vollständigen Skill-Inhalt und führt ihn aus.


examples: Beispielverzeichnis

Viele Entwickler ignorieren diesen Teil, aber er ist tatsächlich sehr wichtig.

Verzeichnisstruktur

examples/
├── example1.md
├── example2.md

Beispiel-Dateiinhalt

Beispiel

Eingabe:

Bitte hilf mir, dieses PDF zu analysieren

Ausgabe:

# Dokumentzusammenfassung

## Kerninhalt

1. ...
2. ...
3. ...

Zweck der Beispiele

ZweckBeschreibung
Few-Shot-Beispiele bereitstellenHilf dem Modell, das erwartete Verhalten anhand von Beispielen zu verstehen
Ausgabeformat standardisierenAusgabestruktur und -stil anhand von Beispielen verdeutlichen
Ausgabestabilität verbessernZufälliges Verhalten reduzieren und Ergebnisse vorhersehbarer machen

Empirisch sind gute Beispiele oft effektiver als das Hinzufügen weiterer Prompts.


scripts: Ausführbare Skripte

Ein Skill ist nicht nur ein Prompt; manchmal ist es notwendig, tatsächlich Code auszuführen, um echte Arbeit zu erledigen.

Häufige Szenarien, die Skripte erfordern, sind: PDFs lesen, OCR ausführen, Datenbanken aufrufen, Datenverarbeitung, Diagramme generieren usw.

Verzeichnisstruktur

scripts/
├── main.py
└── utils.py

Python-Skript-Beispiel

Beispiel

# Dateipfad: scripts/extract.py
# Funktion: Textinhalt aus PDF-Datei extrahieren

from pypdf import PdfReader

# PDF-Datei öffnen
reader = PdfReader("demo.pdf")

# Extrahierten Text speichern
text = ""

# Über jede Seite iterieren und Text extrahieren
for page in reader.pages:
    text += page.extract_text()

# Gesamten Textinhalt ausgeben
print(text)

Der Skill-Workflow ist: Datei lesen → Skript ausführen → Ergebnis erhalten, dann das Ergebnis dem großen Modell zur Verarbeitung übergeben.


resources: Ressourcenverzeichnis

Wird verwendet, um Hilfsinhalte zu speichern und Konfiguration vom Code zu trennen.

Verzeichnisstruktur

resources/
├── prompt.md
├── config.yaml

Mögliche Ressourcentypen

RessourcentypBeschreibungBeispiel
Prompt-VorlageWiederverwendbare Prompt-Vorlagenprompt.md
KonfigurationsdateiParameter und Einstellungenconfig.yaml
TextvorlagenE-Mail- und Berichtsvorlagentemplate.txt
BildressourcenSymbole, Diagrammelogo.png
SQL-VorlagenVordefinierte Abfragevorlagenquery.sql

Beispiel für eine Konfigurationsdatei

Beispiel

# Dateipfad: resources/config.yaml
# Zusammenfassungsbezogene Konfiguration

max_length
: 1000    # Maximale Zusammenfassungslänge (Zeichen)
language
: zh        # Ausgabesprache: zh=Chinesisch, en=Englisch

Das Ablegen der Konfiguration in einer separaten Datei bedeutet, dass Sie den Code später nicht ändern müssen, wenn Sie Parameter ändern.


tests: Testverzeichnis

Ausgereifte Projekte enthalten normalerweise Tests, um die Effektivität und Stabilität des Skills zu überprüfen.

Verzeichnisstruktur

tests/
├── test_cases.md
└── eval.yaml

Beispiel für einen Testfall

Beispiel

Test:

Eingabe:

Hilf mir, das PDF zu analysieren

Erwartet:

Eine Zusammenfassung ausgeben
Wichtige Punkte einbeziehen

Zweck des Testens

ZweckBeschreibung
Wirksamkeit überprüfenSicherstellen, dass die Ausgabe des Skills den Erwartungen entspricht
RegressionstestsNach Änderungen überprüfen, dass die alte Funktionalität nicht beeinträchtigt ist
Automatisierte BewertungBatch-Tests mit automatisierten Workflows
A/B-TestsAusgabequalität verschiedener Versionen vergleichen

Skills ohne Tests neigen zu dem Problem, dass "das Ändern eines Satzes plötzlich alte Funktionalität zerstört."


README: Nutzungsanleitung

README richtet sich an Entwickler und erklärt, wie man diesen Skill installiert und verwendet.

Beispiel

# Installation

In das Verzeichnis skills kopieren

# Verwendung

PDF hochladen

# Ausgabeformat

Markdown

Das Kernproblem, das es löst, ist: In Zukunft weiß selbst der Autor möglicherweise nicht mehr, wie er den Skill verwendet, den er geschrieben hat.


Vollständiges Beispiel: PDF-Analyse-Skill

Unten ist ein vollständiges Beispiel, das alle oben genannten Konzepte miteinander verbindet.

Übersicht der Verzeichnisstruktur

pdf-analyzer/
├── SKILL.md
├── metadata.json
├── examples/
│   └── summary.md
├── scripts/
│   └── extract.py
├── tests/
│   └── eval.md
└── README.md

Vollständiger Aufrufablauf

用户:
上传 PDF 并总结

        ↓

Agent:
扫描所有 Skills

        ↓

发现:
description: 分析 PDF 并生成摘要

        ↓

命中 pdf-analyzer

        ↓

读取 SKILL.md

        ↓

调用 extract.py

        ↓

提取 PDF 内容

        ↓

生成摘要

        ↓

返回结果

Warum Skills als Verzeichnisstruktur entwerfen?

Viele Leute fragen: Warum nicht einfach eine einzelne prompt.txt verwenden, um alles zu erledigen?

Der Grund dafür ist, dass die Dinge mit zunehmendem Umfang außer Kontrolle geraten.

Probleme mit dem Einzeldatei-Ansatz

ProblemKonkrete Ausprägung
Nicht wartbarAlle Inhalte in einer Datei angehäuft, was Änderungen schwierig macht
Nicht testbarKeine Testfälle, also weiß man nach Änderungen nicht, ob es funktioniert
Nicht wiederverwendbarJeder Skill muss von Grund auf neu geschrieben werden
Keine VersionsverwaltungSchwierig, den Änderungsverlauf nachzuvollziehen
Keine Zusammenarbeit mehrerer PersonenWenn mehrere Personen dieselbe Datei ändern, entstehen leicht Konflikte

Vorteile des verzeichnisbasierten Ansatzes

VorteilImplementierungsmethode
WartbarJede Datei hat klare Zuständigkeiten, Änderungen sind schnell zu lokalisieren
WiederverwendbarSkripte und Konfigurationen können über Skills hinweg gemeinsam genutzt werden
TestbarUnabhängiges Testverzeichnis, unterstützt automatisierte Verifizierung
ErweiterbarNeue Funktionen erfordern nur das Hinzufügen von Dateien
VeröffentlichbarDas Verzeichnis kann gepackt und verteilt werden

Zusammenfassung

Ein Skill ist im Wesentlichen kein Prompt, sondern ein vollständiges Software-Fähigkeitspaket.

Beziehungen der Kerndateien

SKILL.md
    ↓
定义行为

metadata.json
    ↓
定义信息

examples/
    ↓
定义示例

scripts/
    ↓
定义能力

tests/
    ↓
定义质量

README
    ↓
定义使用方式

Ein Prompt löst ein Problem nur einmal, während ein Skill eine Fähigkeit in einen Vermögenswert verwandelt.

Weitere Erweiterungen