Agent Skills erstellen und nutzen

Agent Skills sind Ordner, die Anweisungen, Skripte und ergänzende Ressourcen enthalten. Ein Large Language Model (LLM) kann diese Inhalte laden, wenn sie für spezialisierte Aufgaben hilfreich sind, um diese konsistent und wiederholbar auszuführen. Claude stellte dieses offene Framework 2025 vor, und seitdem wird es zunehmend von Organisationen und Agent-Entwicklern eingesetzt.

Früher musste der Kontext für einen LLM-Workflow häufig bei jeder Aufgabenstellung manuell mitgegeben werden. Mit Agent Skills lassen sich zusätzliche Ressourcen und ergänzende Anweisungen in separate Ordner auslagern, auf die das LLM nur dann zugreift, wenn es sie als relevant erkennt.

Wenn ein LLM beispielsweise PowerPoint-Präsentationen erstellen soll, müssen Styleguides, Grafiken und Vorlagen der Organisation nicht jedes Mal erneut in den Prompt eingefügt werden. Stattdessen können diese Materialien in einem Skill-Ordner abgelegt werden. Das LLM kann die Ressourcen dann selbstständig finden und verwenden, sobald eine Präsentation benötigt wird. Es lassen sich viele Skills anlegen, die LLMs ähnlich wie Werkzeuge nutzen können.

In diesem Tutorial wird ein Agent Skill zum Parsen von PDF-Dateien erstellt, ergänzt durch optionale Ordner für Referenzdokumentation und Assets.

Wichtige Erkenntnisse

Agent Skills sind Ordner mit einer SKILL.md-Datei, die Metadaten und Anweisungen enthält. Dadurch können LLMs spezialisierte Fähigkeiten nur bei Bedarf laden, anstatt den gesamten Kontext in jedem Prompt mitzuführen. Claude führte dieses Framework 2025 ein. Es unterstützt effizientere Agent-Workflows, indem Ressourcen in unabhängig zugängliche Module aufgeteilt werden.

Damit Agenten Skills verwenden können, müssen sie diese finden, laden und ausführen können. Dazu gehört, vorhandene Skills zu durchsuchen und den am besten passenden Skill für die Anfrage eines Nutzers auszuwählen.

Agent Skills können sich zu einem wichtigen Standard entwickeln, um Agenten um zusätzliche Fähigkeiten zu erweitern. Sie bieten viele Anpassungsmöglichkeiten und ermöglichen dynamischere Agent-Workflows.

Den Skill erstellen

Die einfachste Form eines Skills ist ein Ordner mit einer SKILL.md-Datei. Diese Markdown-Datei enthält Metadaten und Anweisungen für den Agenten und erklärt, wie bestimmte Aufgaben ausgeführt werden sollen. Zusätzlich können im selben Ordner weitere Ressourcen wie Vorlagen, Skripte, Referenzdokumente und unterstützende Dateien abgelegt werden.

Ordnerstruktur

your-skill-name/
├── SKILL.md          # Required: instructions + metadata
├── scripts/          # Optional: executable code
├── references/       # Optional: documentation
└── assets/           # Optional: templates, resources

Der Name des Skill-Ordners wird zum Namen des Skills. In diesem Ordner befinden sich die SKILL.md-Datei sowie alle zusätzlichen Materialien, die eingebunden werden sollen.

Erstellen Sie zunächst einen Ordner mit dem Namen skills. Dieser Ordner enthält alle Skills, die angelegt werden. Innerhalb des skills-Ordners wird ein weiterer Ordner mit dem Namen pdf-parsing erstellt. Dieser Ordner enthält alle Dateien und Dokumentationen für den pdf-parsing-Skill. Anschließend wird im Ordner pdf-parsing eine SKILL.md-Datei mit folgendem Inhalt angelegt.

SKILLS.md

---
name: pdf-processing
description: Extracts text from PDF files using PyPDF2.
---

# PDF Processing Skill

## When to use this skill
Use this skill when a user needs to extract text from a PDF file.

## How to Use this Skill
This skill provides the `extract_text()` function from the `parse_pdf.py` script. Import it into your agent script:

python
from skills.pdf_parsing.parse_pdf import extract_text

result = extract_text(
    file_path="/path/to/document.pdf",
    pages="all"  # or "1-3" or "1,2,3"
)

### Parameters
- `file_path` (str): Path to the PDF file
- `pages` (str): Pages to extract - "all", "1-3" (range), or "1,2,3" (specific pages)

### Returns
JSON object with:
- `success` (bool): Whether extraction succeeded
- `file_path` (str): Path to the processed file
- `total_pages` (int): Total pages in PDF
- `extracted_pages` (int): Number of pages extracted
- `pages` (list): Array of {page: number, text: string} objects

Alternativ kann das Skript auch direkt über die Kommandozeile ausgeführt werden:

python skills/pdf-parsing/parse_pdf.py extract_text --file_path /path/to/file.pdf --pages all

Die Felder name und description müssen am Anfang der Markdown-Datei im Frontmatter stehen. Frontmatter ist der Metadatenbereich am Beginn der Markdown-Datei. Der Agent nutzt diese Angaben aus jedem Skill, um zu entscheiden, welcher Skill am besten zu einer Anfrage passt. Optional können weitere Frontmatter-Felder wie license, compatibility, metadata und allowed-tools ergänzt werden. Für eigene Agent-Workflows lassen sich beliebige zusätzliche Felder definieren. Der Agent kann das Frontmatter jedes Skills zusammen mit der Nutzeranfrage verwenden, um den passenden Skill zu bestimmen.

Für den restlichen Inhalt der Markdown-Datei gibt es keine festen Formatvorgaben. Es empfiehlt sich jedoch, bewährte Prompting-Praktiken zu verwenden und die Anweisungen klar und verständlich für das LLM zu formulieren. Der Hauptteil der Markdown-Datei wird geladen, nachdem der Agent entschieden hat, welcher Skill genutzt werden soll.

Verwenden Sie anschließend entweder ein freies PDF-Parser-Skript oder erstellen Sie eine Datei parse_pdf.py, die eine extract_text()-Funktion mit PDF-Parsing-Funktionalität enthält. Achten Sie darauf, alle benötigten Abhängigkeiten zu installieren, wenn ein Skill hinzugefügt wird. Für dieses Skript wird PyPDF2 benötigt.

$ pip3 install PyPDF2

Damit wird das Python-Paket PyPDF2 installiert.

Den Skill integrieren

Damit ein Agent mit Skills arbeiten kann, muss er diese über einen definierten Workflow erkennen und anwenden. Zunächst durchsucht er beim Start die verfügbaren Verzeichnisse nach SKILL.md -Dateien und liest grundlegende Metadaten wie den Namen und die Beschreibung des Skills aus. Anschließend vergleicht er die Anfrage des Nutzers mit den verfügbaren Skills, wählt den passenden Skill aus, lädt die vollständigen Anweisungen aus der Markdown-Datei und folgt diesen Vorgaben. Falls erforderlich, lädt der Agent zusätzlich unterstützende Dateien oder führt Code aus.

Einige Agentensysteme unterstützen diesen Skill-Workflow bereits automatisch, und weitere Anbieter integrieren ähnliche Funktionen zunehmend in ihre Plattformen.

Es gibt zwei typische Möglichkeiten, Skills in einem benutzerdefinierten Agenten bereitzustellen. Eine Option ist ein dateisystembasierter Ansatz, bei dem das Modell in einer Umgebung arbeitet, die Shell-Befehle ausführen kann, beispielsweise um eine Skill-Datei mit cat /path/to/my-skill/skill.md zu lesen. Die andere Option ist ein toolbasierter Ansatz, bei dem jeder Skill als aufrufbares Tool bereitgestellt wird.

Die vollständige Erstellung eines Skill-fähigen Agenten von Grund auf wird hier nicht behandelt, aber ein Beispielskript kann als Ausgangspunkt dienen. Dieses Skript verbindet sich über einen serverlosen Inferenzdienst mit einem Large Language Model. Für die Nutzung erstellen Sie einen Access Key für die ausgewählte Inferenzplattform und fügen diesen Schlüssel in die main()-Funktion des Skripts ein.

Nachdem das Skript im selben Verzeichnis wie der skills-Ordner abgelegt wurde, kann es ausgeführt werden.

$ python3 agent_example.py

Geben Sie in das Textfeld, das sich öffnet, Folgendes ein: Please parse the text out of the PDF at /path/to/your/document.pdf. Anschließend sollte eine Ausgabe erscheinen, die den aus der PDF-Datei extrahierten Text enthält.

Ausgabe

============================================================
SIMPLE TOOL-BASED SKILLS EXAMPLE
============================================================

✅ Found 1 skills:
   - pdf-processing: Extracts text from PDF files using PyPDF2.

============================================================
CHAT (type 'quit' to exit)
============================================================

You: Please extract the text from: /Desktop/document.pdf

[Turn 1]
💭 LLM: {"function_call": {"name": "activate_skill", "arguments": {"skill_name": "pdf-processing"}}}
..........
The cost of an RV is 30,000

Der Agent hat den Skill erfolgreich erkannt, die Metadaten gelesen, den Skill ausgeführt und den extrahierten PDF-Text zurückgegeben.

Funktionalität und weitere Skills ergänzen

Es können weitere Skripte oder Ordner hinzugefügt werden, auf die das LLM zugreifen soll. Anschließend wird die Funktionalität jedes Ordners und Skripts in der SKILL.md-Datei mit klaren Anweisungen und Beschreibungen dokumentiert. Beispielsweise könnten Skripte zum Erstellen oder Bearbeiten von PDF-Dateien ergänzt werden. Diese zusätzlichen Dateien sollten immer im Ordner des jeweiligen Skills abgelegt werden, zu dem sie gehören.

Es können beliebig viele Skills erstellt werden, allerdings muss jeder Skill-Ordner eine SKILL.md-Datei enthalten, damit der Agent ihn erkennen kann. Wenn sehr viele Skills vorhanden sind, kann es jedoch schwieriger werden, die Absicht des Nutzers korrekt den Metadaten zuzuordnen. Mit zunehmender Anzahl an Skills können zusätzliche Suchfunktionen oder Vektor-Embeddings erforderlich sein, um Nutzeranfragen zuverlässiger dem richtigen Skill zuzuweisen.

FAQ

Können Skills miteinander kommunizieren oder andere Skills aufrufen, und wie lässt sich Skill-Chaining umsetzen?

Ja, Skills können andere Skills aufrufen. Der Agent sollte erkennen können, wenn mehrere Skills benötigt werden, und diese miteinander verknüpfen. Andere Skills können außerdem direkt in den Skill-Anweisungen referenziert werden.

Wie werden Authentifizierung und API-Schlüssel in Skills gehandhabt, wenn externe Dienste angebunden werden?

Zugangsdaten sollten niemals direkt in Skill-Dateien gespeichert werden. Stattdessen sollten Umgebungsvariablen oder ein sicherer Secrets Manager verwendet werden.

Welche Auswirkungen hat das Laden vieler Skills beim Start auf die Performance, und gibt es Lazy-Loading-Strategien?

Das Laden der Metadaten von hunderten Skills kann Zeit beanspruchen. Zur Verbesserung der Performance können geladene Skills zwischengespeichert und Indexierungen genutzt werden, um große Skill-Sammlungen schneller zu durchsuchen. Außerdem lassen sich Discovery und Aktivierung trennen, sodass zunächst nur Metadaten geladen werden und die vollständigen Skill-Anweisungen erst bei Bedarf nachgeladen werden.

Wie werden Skills getestet und debuggt?

Jeder Skill sollte einzeln getestet werden, bevor er in den Agenten integriert wird. Zusätzlich hilft ausführliches Logging dabei nachzuvollziehen, welche Skills ausgewählt werden und aus welchem Grund.

Fazit

Agent Skills sind eine wirksame Möglichkeit, die Funktionalität eines LLM-Agenten zu standardisieren. Sie ermöglichen es, Agentenfunktionen strukturiert zu ergänzen und weiterzuentwickeln. Die konkrete Umsetzung hängt vom jeweiligen Agent-Workflow ab, doch immer mehr Agent-Dienste beginnen, Skills direkt zu unterstützen.

Als nächster Schritt können zusätzliche Skills erstellt und mit Funktionen erweitert werden, die zum jeweiligen Projekt passen. Danach lassen sich die Skill-Matching-Fähigkeiten des Agent-Workflows durch Vektor-Embeddings oder andere Suchmethoden verbessern.