Hermes-Agent-Skill-Authoring – SKILL.md-Struktur und Best Practices

Hermes Agent behandelt Skills als die Standardmethode, wiederholbare Workflows zu lehren. Die offizielle Dokumentation beschreibt sie als auf Abruf verfügbare Wissensdokumente, die dem offenen agentskills.io-Standard entsprechen und über progressive Offenlegung geladen werden, sodass das Modell zuerst einen kleinen Index sieht und nur dann die vollständigen Anweisungen lädt, wenn eine Aufgabe dies tatsächlich erfordert.

Das Verfassen von Skills hat weniger mit cleverer Formulierung als mit Verpackung zu tun – Sie teilen dem Runtime mit, wann ein Verfahren geladen werden soll, welche Schrittfolge als „abgeschlossen“ gilt und wie man Erfolg von einem stillen Fehler unterscheidet. Dieser Artikel konzentriert sich auf die SKILL.md-Struktur, unterstützende Ordner, Sichtbarkeitsregeln und die Trennung zwischen Geheimnissen und nicht-geheimen Einstellungen – den Details, die darüber entscheiden, ob ein Skill in /slash-Befehlen erscheint, eine Hub-Installation überlebt oder in CI stillschweigend verschwindet.

Hermes gehört zum größeren AI Systems: Self-Hosted Assistants, RAG, and Local Infrastructure-Cluster, in dem Assistenten als Systeme behandelt werden, die aus Inferenz, Abruf, Speicher und Werkzeugen bestehen, nicht als einzelne Chat-Oberfläche. Installationspfade, Provider-Anbindung, Gateway-Verhalten und die Struktur von ~/.hermes sind im Hermes AI Assistant - Install, Setup, Workflow, and Troubleshooting-Guide detailliert beschrieben; die tägliche Shell-Ergonomie – hermes skills, Profile, Gateway, Speicher – lässt sich im Hermes Agent CLI cheat sheet — commands, flags, and slash shortcuts leichter überblicken. In echten Deployments erben Skills ihre Isolation von Profilen (separate Konfiguration, Geheimnisse, Speicher und Skill-Bäume). Hermes AI Assistant Skills for Real Production Setups plädiert dafür, diese Profile – nicht einzelne Markdown-Dateien – als Einheit der Verantwortung zu behandeln; denken Sie daran, wenn Sie Skills benennen und entscheiden, was in geteilte external_dirs versus ein einzelnes Profil gehört.

Skill oder Tool?

Die offizielle Empfehlung ist klar. Verwenden Sie einen Skill, wenn die Fähigkeit hauptsächlich aus Prozeduranweisungen plus Shell-Befehlen und Tools besteht, die Hermes bereits bereitstellt – ein CLI zu umschließen, git zu steuern, curl aufzurufen oder web_extract für strukturierte Abrufe zu verwenden. Verwenden Sie ein Tool, wenn Sie eine enge Integration für API-Schlüssel und Auth-Flows benötigen, deterministische Binärdatei-Behandlung, Streaming oder Python, das jedes Mal gleich ausgeführt werden muss.

Diese Grenze ist in der Praxis wichtig, weil Skills ohne Änderung des Agenten-Codes ausgeliefert werden, während Tools Review- und Release-Aufwand mit sich bringen. Die meisten Teams profitieren davon, mit einem Skill zu beginnen und erst dann den spröden Kern zu einem Tool zu befördern, wenn die Fehlermodi offensichtlich sind (Auth-Refresh-Schleifen, Binärparser, strenge Idempotenz). Für die größere architektonische Frage, wann man einen Agenten-Skill versus einen MCP-Server verwenden sollte – insbesondere rund um Credentials, Live-Zustände und transaktionale Schreibvorgänge – siehe unser Agent Skills vs MCP Servers decision framework.

Verfahren versus kuratierte Erinnerung

Skills beantworten die Frage wie ein Workflow ausgeführt wird; der begrenzte Kernspeicher von Hermes beantwortet die Frage was bereits über den Benutzer und das Projekt vereinbart wurde. Ein Skill lädt, wenn die Aufgabe seiner Beschreibung entspricht; MEMORY.md und USER.md bleiben als kleine, kuratierte Fakten-Ebene im Prompt. Die beiden Mechanismen stapeln sich statt zu konkurrieren, und das vollständige Bild von Snapshots, Grenzen und externen Providern wird in Hermes Agent Memory System: How Persistent AI Memory Actually Works dargelegt.

Anatomie eines Skill-Ordners

Auf der Festplatte ist jeder Skill ein Ordner unter ~/.hermes/skills/, oft verschachtelt unter einer Kategorie wie devops/ oder research/. Hermes erwartet SKILL.md an der Blattstelle; alles andere ist optionale Struktur, die Sie hinzufügen, wenn die Anweisungen sonst zu weitläufig würden. Das übliche Muster ist references/ für lange Tabellen oder Vendor-Dokumente, templates/ für Ausgabe-Skelette, scripts/ für deterministische Helfer und assets/ für statische Dateien, die der Agent nicht erneut abrufen sollte.

Diese Struktur spiegelt wider, wie progressive Offenlegung in der Praxis funktioniert: Der Agent kann im Hauptfile bleiben, bis er wirklich eine tiefe Anhangsdatei benötigt. Das „Happy-Path“-Prosa in SKILL.md zu halten und selten genutzte Details nach references/ zu verschieben, ist eine der günstigsten Methoden, Token-Budgets zu schützen.

Hermes kann auch externe Skill-Verzeichnisse über skills.external_dirs in config.yaml zusammenführen. Diese Pfade werden für die Entdeckung gescannt, aber der Agent schreibt weiterhin über skill_manage in den primären ~/.hermes/skills/-Baum. Lokale Namen überschatten externe, sodass Ihre „Korrektur“ eines geteilten Skills in Ihrem Home-Verzeichnis von Teammitgliedern, die dasselbe externe Repo ziehen, nicht gesehen wird, bis sie die lokale Kopie entfernen oder umbenennen – eine häufige Quelle von „es funktioniert auf meinem Rechner“-Verwirrung.

SKILL.md-Frontmatter, das die Überprüfung übersteht

Der Körper von SKILL.md ist Markdown; der Anfangsblock muss gültiges YAML zwischen ----Delimitern sein. Echte Skills akkumulieren lange gefencete Beispiele, daher halten die kleinen Gewohnheiten aus Markdown Code Blocks: Complete Guide with Syntax, Languages & Examples – konsistente Sprach-Tags, lesbare Auszüge, eng gefencete Blöcke – große Dateien für Menschen wartbar und für das Modell etwas leichter zu scannen.

Erforderliche Felder sind name und description. Der name wird zur Slash-Route und zum Index-Schlüssel; er bleibt klein mit Bindestrichen und muss die dokumentierte Längenbeschränkung einhalten. Die description ist der einzige Prosa, den viele Sessions je auf Stufe null bezahlen, daher sollte sie wie ein Suchergebnis oder Router-String klingen („wenn Backups veraltet aussehen, letztes Archiv und Checksumme überprüfen“), nicht wie der erste Absatz eines Blogposts.

Optionale Top-Level-Schlüssel wie version, author und license helfen bei Hub-Packaging und Audits. Die platforms-Liste (macos, linux, windows) ist schärfer, als sie aussieht – wenn gesetzt, lässt Hermes den Skill auf nicht-passenden Hosts ganz aus, weshalb ein Skill, der „auf meinem Mac funktioniert“, in Linux-CI ohne Fehlermeldung außer einer kürzeren Skill-Liste verschwinden kann.

Hermes-spezifische Knöpfe leben unter metadata.hermes: tags, related_skills und die konditionellen Sichtbarkeitsfelder im nächsten Abschnitt. required_environment_variables deklariert Geheimnisse, die in .env landen und in Sandboxes übergeben werden sollen; required_credential_files deckt OAuth-Token-Dateien und andere on-disk Credentials ab, die in Docker oder Modal gemountet werden müssen; metadata.hermes.config deklariert nicht-geheime Präferenzen, die unter skills.config in config.yaml gespeichert werden.

Die offiziellen Docs betonen aus gutem Grund Größen-Diziplin. Kürzen Sie die description auf ihr Budget, stellen Sie das Verfahren voran und schieben Sie historische Notizen oder riesige Options-Matrizen nach references/, damit eine partielle skill_view dem Agenten immer noch etwas Handlungsfähiges gibt.

Nachfolgend ist ein minimales SKILL.md, das Sie in ~/.hermes/skills/devops/backup-check/SKILL.md (oder einen beliebigen Kategorie-Ordner) legen und von dort aus iterieren können.

---
name: backup-check
description: Verify nightly backup archives exist, are non-empty, and pass a quick checksum spot-check on the latest file.
version: 1.0.0
metadata:
  hermes:
    tags: [devops, backups, shell]
    requires_toolsets: [terminal]
    config:
      - key: backup_check.archive_dir
        description: Absolute path to the directory that holds backup archives
        default: "/var/backups"
        prompt: Backup archive directory (absolute path)
---

# Backup archive spot-check

## When to use

Use when the user asks to confirm backups ran, to audit the latest archive on disk, or to catch empty or stale backup files before a restore drill.

## Quick reference

- Latest archive directory is configured under `skills.config.backup_check.archive_dir` (set via `hermes config migrate` if declared in metadata).
- Default check uses `ls` by mtime and `test -s` for non-empty files.

## Procedure

1. Resolve the archive directory from skill config or ask the user once if unset.
2. List the most recently modified file matching the expected pattern (for example `*.tar.zst`).
3. Confirm the file exists, is non-empty, and record its path and size for the reply.
4. If a checksum file exists beside the archive, verify it with the documented tool (for example `sha256sum -c`).

## Pitfalls

- Empty files can still have a recent mtime if a failed job touched the path; always check size.
- Relative paths break when the terminal cwd is not the backup host; use absolute paths in config.

## Verification

The user should see the latest archive path, byte size, and either a checksum OK line or an explicit note that no `.sha256` sidecar was found.

Progressive Offenlegung in der Praxis

Progressive Offenlegung ist der Unterschied zwischen einer Skill-Bibliothek, die schnell wirkt, und einer, die tausende Tokens verbrennt, bevor die erste Benutzer-Nachricht kommt. Hermes durchläuft drei konzeptionelle Schritte: einen kompakten Katalog (Namen und kurze Beschreibungen), das vollständige SKILL.md, wenn die Aufgabe passt, und – nur wenn nötig – einen Ausschnitt einer Referenzdatei über skill_view-Pfade. Gehen Sie davon aus, dass Stufe null alles ist, was das Modell liest, bis es explizit weitergeht; jeder Satz in der description und auf dem ersten Bildschirm des Körper-Textes sollte beim Routing helfen, nicht beim Geschichtenerzählen.

Ein praktischer Aufbau, der partielle Ladevorgänge übersteht, ist When to use (Trigger in einfacher Sprache), Quick reference (Befehle, Umgebungsvariablen, Dateipfade), Procedure (geordnete Schritte, die der Agent nicht improvisieren sollte), Pitfalls (bekannte Fehlermodi) und Verification (wie „grün“ aussieht). Narrative Geschichte, Vendor-Changelog-Dumps und zwanzigzeilige Optionstabellen gehören nach references/ mit stabilen Überschriften, damit der Agent einen einzelnen Abschnitt abrufen kann.

Wenn ein Skill aktiviert wird, kann Hermes ${HERMES_SKILL_DIR} und ${HERMES_SESSION_ID} im Körper umschreiben, sodass Shell-Zeilen auf den installierten Ordner zeigen, ohne manuell gebaute Pfade. Optionelle inline-Shell-Snippets (!cmd``) können frischen Kontext injizieren (aktueller Branch, freier Speicherplatz), aber sie werden auf dem Host ausgeführt und bleiben deaktiviert, es sei denn skills.inline_shell ist an – behandeln Sie dieses Flag als Vertrauensgrenze für die gesamte Skill-Quelle, nicht als Komfort-Umschalter.

Konditionale Aktivierung und Prompt-Hygiene

Skills können sich zeigen oder verstecken, basierend darauf, welche Toolsets oder Tools in der aktuellen Session existieren. requires_toolsets / requires_tools sperren einen Skill hinter Fähigkeiten, die vorhanden sein müssen; fallback_for_toolsets / fallback_for_tools zeigen einen günstigeren oder lokalen Pfad an, wenn eine Premium-Integration fehlt – der DuckDuckGo-Fallback bei nicht konfigurierter bezahlter Websuche-API ist das kanonische Beispiel.

Diese Prädikate formen direkt die Prompt-Lautstärke. Eine zu strenge requires_*-Regel versteckt einen Skill vor Neulingen, die noch nicht die hermes tools-Einrichtung abgeschlossen haben; eine zu lasche fallback_for_*-Regel dupliziert die Hälfte Ihrer Bibliothek, wann immer jemand einen API-Schlüssel weglässt. Der nützliche Mittelweg besteht darin, echte Voraussetzungen zu nennen, mit hermes chat --toolsets skills zu testen und Schlüssel oder Toolsets gezielt umzuschalten, während man beobachtet, ob die Skill-Liste so atmet, wie erwartet.

Geheimnisse, Konfiguration und Credential-Dateien

Geheimnisse sollten in required_environment_variables deklariert werden. Hermes kann bei der lokalen CLI-Ladung eines Skills nachfragen, Werte in .env persistieren und sie in terminal- und execute_code-Sandboxes übergeben, ohne das rohe Geheimnis zurück in den Modell-Transkript zu streamen. Remote-Chat-Oberflächen weigern sich, Schlüssel inline zu sammeln und verweisen stattdessen auf hermes setup oder manuelle .env-Edits – verfassen Sie Ihren Skill-Text so, dass er diesem Verhalten entspricht (sagen Sie Benutzern, dass ein Schlüssel erforderlich ist, nicht dass sie ihn in Telegram einfügen sollen).

Nicht-geheime Präferenzen – Standardpfade, Organisationsnamen, Feature-Toggles – gehören in metadata.hermes.config. Werte werden in skills.config innerhalb von config.yaml aufgelöst, erscheinen in hermes config show und erreichen die Skill-Nachricht als aufgelöste Fakten, sodass das Modell Ihre Konfigurationsdatei nicht während der Aufgabe öffnen muss.

Datei-förmige Credentials (OAuth-Token-JSON, Service-Account-Schlüssel) werden auf required_credential_files abgebildet. Wenn diese Dateien existieren, kann Hermes sie in Docker bind-mounten oder in Modal-Jobs synchronisieren; die vorherige Deklaration vermeidet die klassische „Skript funktioniert lokal, stirbt in Sandbox“-Lücke.

Unterstützende Skripte und Abhängigkeiten

Das Upstream-Guide drängt Autoren zu langweiligen Abhängigkeiten: stdlib Python, curl und Hermes’ eigene Tools (web_extract, read_file, terminal). Das hat weniger mit Reinheit als mit Reproduzierbarkeit zu tun – jedes zusätzliche pip install ist ein weiterer stiller Fehler, wenn der Agent in einem sauberen Container läuft.

Wenn JSON- oder XML-Parsing fummelig ist, übertrifft ein kurzes Skript unter scripts/ plus ein ${HERMES_SKILL_DIR}-Pfad das Bitten des Modells, Parser bei jedem Durchlauf neu abzuleiten. Wenn Sie wirklich ein Paket benötigen, nennen Sie den Installationsbefehl in Procedure, wiederholen Sie das Fehlersymptom in Pitfalls und geben Sie einen Verification-Befehl, der laut fehlschlägt, wenn die Abhängigkeit fehlt.

Veröffentlichung, Hub-Installationen und Vertrauen

Community-Skills bewegen sich durch den Skills Hub und die anderen Entdeckungspfade, die der User-Guide auflistet – offizielle optionale Skills, GitHub-Slugs, skills.sh-Einträge, .well-known-Indizes und rohe SKILL.md-URLs. Installationen werden auf offensichtliche Exfiltration, Injektion und destruktive Muster gescannt; Vertrauensstufen reichen von builtin über community, und einige Befunde klären sich nur mit --force, während die schlimmsten Fälle ganz blockiert bleiben.

Die SKILL.md-Dateiform ist nicht Hermes-spezifisch; IDE-zentrierte Assistenten verwenden dieselbe progressive-Ladeidee mit anderer Entdeckung und Triggern. Claude Skills and SKILL.md for Developers: VS Code, JetBrains, Cursor ist ein nützlicher Kontrast-Lesestoff – Frontmatter-Diziplin und „lade nur wenn relevant“ übertragen sich, auch wenn Installer und Slash-Befehls-Anbindung anders sind.

Org-weite Rollouts paaren normalerweise einen privaten Tap oder geteilten Git-Repo mit external_dirs für schreibgeschütztes Teilen, während sie die agentenschreibbare Kopie unter jedem Profil behalten, wenn skill_manage erlaubt ist, Skills vor Ort zu mutieren.

Fehlerbehebung und Optimierung

Wenn ein Skill sich falsch verhält, durchlaufen Sie diese Checkliste, bevor Sie Prosa umschreiben.

• Sichtbarkeit — Bestätigen Sie platforms, requires_* und fallback_for_*-Prädikate. Ein Skill, der „auf meinem Mac funktioniert“, aber nicht in Linux-CI, ist oft ein Platform-Guard.
• Namenskollisionen — Duplizierte Namen über lokale und externe Verzeichnisse folgen der lokalen Priorität. Umbenennen oder Namespace aggressiv.
• Entdeckungs-Layout — Ein fehlplatziertes SKILL.md oder falscher Kategorie-Ordner kann den Skill ganz vom Indexing fallen lassen.
• Token-Last — Wenn Sessions sich langsam anfühlen, kürzen Sie Stufe-null-Beschreibungen, verschieben Sie Tiefe nach references/ und deduplizieren Sie riesige Tabellen.
• Agenten-Edits — Hermes kann Skills über skill_manage erstellen, patchen oder löschen. Behandeln Sie wertvolle Skills wie Code: Reviewen Sie Diffs, exportieren Sie Snapshots und setzen Sie gebündelte Skills gezielt zurück, wenn Upgrades drifteten.

Ein enger Regressionsloop übertrifft das Wiederlesen der ganzen Datei: hermes chat --toolsets skills -q "Use the <skill> workflow to <concrete task>" sollte zeigen, dass der Agent das richtige Offenlegungs-Level zieht, bevor er freestylet. Wenn er nie skill_view aufruft, passt Ihre When to use-Text oder description wahrscheinlich nicht dazu, wie Leute Anfragen formulieren.

Offizielle Referenzen bleiben autoritativ für Verhaltensänderungen – die Skills System-User-Guide für Runtime-Semantik, Creating Skills für author-facing Regeln, der Bundled Skills Catalog für Copy-Paste-Beispiele und die agentskills.io specification für das gemeinsame Dateiformat, mit dem Hermes sich abstimmt.