Hermes Agent Skill Authoring — Struktur und Best Practices für SKILL.md

Hermes Agent behandelt Skills (Fertigkeiten) als die Standardmethode zur Vermittlung wiederholbarer Workflows. Die offizielle Dokumentation beschreibt sie als bedarfsgerechte Wissensdokumente, die mit der offenen agentskills.io-Struktur übereinstimmen. Sie werden durch progressive Offenlegung (Progressive Disclosure) geladen, sodass das Modell zunächst einen kleinen Index sieht und nur dann die vollständigen Anweisungen lädt, wenn eine Aufgabe dies tatsächlich erfordert.

Beim Erstellen von Skills geht es weniger um geschickte Formulierung als vielmehr um Strukturierung – Sie teilen dem Runtime mit, wann eine Prozedur geladen werden soll, welche Reihenfolge von Schritten als „erledigt“ gilt und wie Erfolg von einem stillen Fehler unterschieden wird. Dieser Artikel konzentriert sich auf die Struktur von SKILL.md, unterstützende Ordner, Sichtbarkeitsregeln und die Trennung zwischen geheimen und nicht-geheimen Einstellungen – die Details, die entscheiden, ob ein Skill in /slash-Befehlen angezeigt wird, bei einer Hub-Installation erhalten bleibt oder in CI-Umgebungen stillschweigend verschwindet.

Hermes ist Teil des breiteren Clusters AI Systems: Self-Hosted Assistants, RAG, and Local Infrastructure, in dem Assistenten als Systeme behandelt werden, die aus Inferenz, Abruf, Speicher und Werkzeugen bestehen, anstatt als eine einzelne Chat-Oberfläche. Installationspfade, die Konfiguration von Anbietern, das Verhalten des Gateways und die Struktur von ~/.hermes werden im Leitfaden Hermes AI Assistant - Install, Setup, Workflow, and Troubleshooting detailliert beschrieben; alltägliche Shell-Usability-Aspekte wie hermes skills, Profile, Gateway und Speicher sind im Hermes Agent CLI cheat sheet — commands, flags, and slash shortcuts übersichtlicher dargestellt. In echten Deployment-Szenarien erben Skills ihre Isolation von Profilen (separate Konfiguration, Secrets, Speicher und Skill-Bäume). Hermes AI Assistant Skills for Real Production Setups argumentiert dafür, diese Profile – nicht einzelne Markdown-Dateien – als Einheit der Eigentümerschaft zu betrachten; behalten Sie dies im Hinterkopf, wenn Sie Skills benennen und entscheiden, was in gemeinsame external_dirs gehört und was in ein einzelnes Profil.

Skill oder Tool?

Die offizielle Empfehlung ist direkt. Verwenden Sie einen Skill, wenn die Fähigkeit hauptsächlich aus prosaischen Anweisungen plus Shell-Befehlen und Werkzeugen besteht, die Hermes bereits bereitstellt – zum Beispiel das Umhüllen einer CLI, das Steuern von git, das Aufrufen von curl oder die Verwendung von web_extract für strukturierte Abrufe. Verwenden Sie ein Tool, wenn Sie eine enge Integration für API-Schlüssel und Authentifizierungsabläufe, deterministische Binärverarbeitung, Streaming oder Python benötigen, das jedes Mal auf die gleiche Weise ausgeführt werden muss.

Diese Grenze ist in der Praxis wichtig, da Skills ohne Änderung des Agenten-Codes ausgeliefert werden, während Tools Überprüfungsaufwand und Release-Overhead mit sich bringen. Die meisten Teams profitieren davon, mit einem Skill zu beginnen und nur den zerbrechlichen Kern in ein Tool umzuwandeln, sobald die Fehlermodi offensichtlich sind (Authentifizierungs-Aktualisierungs-Schleifen, Binärparser, strikte Idempotenz).

Prozeduren gegenüber kuratiertem Speicher

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

Anatomie eines Skill-Verzeichnisses

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

Diese Struktur spiegelt wider, wie progressive Offenlegung in der Praxis funktioniert: Der Agent kann beim Hauptdatei bleiben, bis er wirklich einen tiefen Anhang benötigt. Das Halten der „glücklichen Pfade“ (Happy Path) im Text in SKILL.md und das Verschieben selten genutzter Details in references/ ist einer der kostengünstigsten Wege, um Token-Budgets zu schützen.

Hermes kann auch externe Skill-Verzeichnisse über skills.external_dirs in config.yaml zusammenführen. Diese Pfade werden zur Entdeckung gescannt, aber der Agent schreibt weiterhin über skill_manage in den primären Baum ~/.hermes/skills/. Lokale Namen überschatten externe, sodass, wenn Sie einen gemeinsamen Skill in Ihrem Home-Verzeichnis „reparieren“, Teamkollegen, die dasselbe externe Repository ziehen, Ihre Bearbeitung nicht sehen, bis sie die lokale Kopie entfernen oder umbenennen – eine häufige Ursache für Verwirrung des Typs „Bei mir funktioniert es“.

SKILL.md Frontmatter, das Reviews übersteht

Der Körper von SKILL.md ist Markdown; der öffnende Block muss gültiges YAML zwischen ----Delimitern sein. Echte Skills sammeln lange gefenzte Beispiele an, daher helfen die kleinen Gewohnheiten aus Markdown Code Blocks: Complete Guide with Syntax, Languages & Examples – konsistente Sprachtags, lesbare Exzerpte, enge Fences – dabei, große Dateien für Menschen wartbar und für das Modell etwas einfacher zu scannen zu halten.

Erforderliche Felder sind name und description. Der name wird zur Slash-Route und zum Indexschlüssel; er bleibt kleinbuchstabig mit Bindestrichen und muss die dokumentierte Längenbeschränkung einhalten. Die description ist der einzige Text, für den viele Sessions auf Stufe null bezahlen, daher sollte sie wie ein Suchergebnis oder eine Router-String aussehen („wenn Backups veraltet aussehen, neuestes 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 Liste platforms (macos, linux, windows) ist schärfer, als sie aussieht – wenn eingestellt, lässt Hermes den Skill auf nicht übereinstimmenden Hosts vollständig weg, weshalb ein Skill, der „auf meinem Mac funktioniert“, in Linux CI ohne Fehlermeldung außer einer kürzeren Skill-Liste verschwinden kann.

Hermes-spezifische Einstellungen befinden sich unter metadata.hermes: tags, related_skills und die bedingten Sichtbarkeitsfelder im nächsten Abschnitt. required_environment_variables erklärt Secrets, die in .env landen und in Sandboxes übergeben werden sollen; required_credential_files deckt OAuth-Token-Dateien und andere auf der Festplatte befindliche Anmeldeinformationen ab, die in Docker oder Modal gemountet werden müssen; metadata.hermes.config erklärt nicht-geheime Präferenzen, die unter skills.config in config.yaml gespeichert sind.

Offizielle Dokumente betonen Größendisziplin aus einem Grund. Kürzen Sie die description auf ihr Budget, stellen Sie die Prozedur an den Anfang und verschieben Sie historische Notizen oder riesige Optionsmatrizen in references/, sodass ein teilweises skill_view dem Agenten immer noch etwas Ausführbares bietet.

Nachfolgend finden Sie ein minimales SKILL.md, das Sie in ~/.hermes/skills/devops/backup-check/SKILL.md (oder einen beliebigen Kategorieordner) einfügen und von dort iterativ erweitern 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 zügig wirkt, und einer, die Tausende von Tokens verbrennt, bevor die erste Benutzernachricht eingeht. Hermes durchläuft drei konzeptionelle Schritte: einen kompakten Katalog (Namen und kurze Beschreibungen), das vollständige SKILL.md, wenn die Aufgabe übereinstimmt, und – nur falls 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 zusagt; jeder Satz in der description und der erste Bildschirm des Textkörpers sollte dem Routing helfen, nicht dem Geschichtenerzählen.

Ein praktischer Leitfaden, der partielle Laden übersteht, ist When to use (Auslöser 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, Hersteller-Changelog-Dumps und zwanzigzeilige Optionstabellen gehören in references/ mit stabilen Überschriften, damit der Agent einen einzelnen Abschnitt ziehen kann.

Wenn ein Skill aktiviert wird, kann Hermes ${HERMES_SKILL_DIR} und ${HERMES_SESSION_ID} im Textkörper umschreiben, sodass Shell-Zeilen auf den installierten Ordner zeigen, ohne manuell erstellte Pfade. Optionale 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 aktiviert – behandeln Sie dieses Flag als Vertrauensgrenze für die gesamte Skill-Quelle, nicht als Komfortschalter.

Bedingte Aktivierung und Prompt-Hygiene

Skills können angezeigt oder versteckt werden, 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 bieten einen günstigeren oder lokalen Pfad, wenn eine Premium-Integration fehlt – der DuckDuckGo-Fallback, wenn eine bezahlte Websuch-API nicht konfiguriert ist, ist das kanonische Beispiel.

Diese Prädikate formen direkt Prompt-Lärm. Eine zu strenge requires_*-Regel versteckt einen Skill vor Neueinsteigern, die hermes tools noch nicht vollständig eingerichtet haben; eine zu lockere 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 benennen, mit hermes chat --toolsets skills zu testen und Schlüssel oder Toolsets absichtlich umzuschalten, während man beobachtet, ob die Skill-Liste so „atmet“, wie erwartet.

Secrets, Konfiguration und Credential-Dateien

Secrets sollten in required_environment_variables deklariert werden. Hermes kann beim Laden eines Skills in der lokalen CLI nachfragen, Werte in .env persistieren und sie in terminal- und execute_code-Sandboxes übergeben, ohne das rohe Secret zurück in die Modelltranskription zu streamen. Remot-Chat-Oberflächen weigern sich, Schlüssel inline zu sammeln und verweisen stattdessen auf hermes setup oder manuelle .env-Bearbeitungen – verfassen Sie Ihren Skill-Text so, dass er diesem Verhalten entspricht (teilen Sie den Benutzern mit, dass ein Schlüssel erforderlich ist, nicht, dass sie ihn in Telegramm 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 kommen im Skill-Nachricht als aufgelöste Fakten an, sodass das Modell Ihre Konfigurationsdatei nicht mitten in der Aufgabe öffnen muss.

Datei-förmige Anmeldeinformationen (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; das Vorausdeklarieren vermeidet die klassische Lücke „Skript funktioniert lokal, stirbt im Sandbox“.

Unterstützende Skripte und Abhängigkeiten

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

Wenn das Parsen von JSON oder XML umständlich ist, ist ein kurzes Skript unter scripts/ plus einem ${HERMES_SKILL_DIR}-Pfad besser, als das Modell zu bitten, Parser bei jedem Durchlauf neu abzuleiten. Wenn Sie wirklich ein Paket benötigen, geben Sie den Installationsbefehl in Procedure an, wiederholen Sie das Fehlersymptom in Pitfalls und geben Sie einen Verification-Befehl an, der laut fehlschlägt, wenn die Abhängigkeit fehlt.

Veröffentlichen, Hub-Installationen und Vertrauen

Community-Skills bewegen sich durch den Skills Hub und die anderen Entdeckungspfade, die der Benutzerleitfaden 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 bis community, und einige Funde werden nur mit --force freigegeben, während die schlimmsten Fälle vollständig blockiert bleiben.

Die SKILL.md-Dateistruktur ist nicht Hermes-spezifisch; IDE-zentrierte Assistenten nutzen die gleiche Idee des progressiven Ladens mit unterschiedlicher Entdeckung und Auslösern. Claude Skills and SKILL.md for Developers: VS Code, JetBrains, Cursor ist ein nützlicher Kontrast-Lesestoff – Frontmatter-Disziplin und „nur laden, wenn relevant“ übertragen sich, auch wenn Installer und Slash-Befehls-Verdrahtung sich unterscheiden.

Unternehmensweite Rollouts koppeln normalerweise ein privates Tap oder ein gemeinsames Git-Repository mit external_dirs für schreibgeschütztes Teilen, während die agentenschreibbare Kopie unter jedem Profil gehalten wird, wenn skill_manage Skills an Ort und Stelle mutieren darf.

Fehlerbehebung und Optimierung

Wenn ein Skill falsch funktioniert, durchlaufen Sie diese Checkliste, bevor Sie den Text umschreiben.

• Sichtbarkeit – Bestätigen Sie die Prädikate platforms, requires_* und fallback_for_*. Ein Skill, der „auf meinem Mac funktioniert“, aber nicht in Linux CI, ist oft eine Plattform-Wache.
• Namenskollisionen – Duplizierte Namen über lokalen und externen Verzeichnissen folgen lokaler Präzedenz. Benennen Sie um oder verwenden Sie Namensräume aggressiv.
• Entdeckungsstruktur – Ein falsch platziertes SKILL.md oder falscher Kategorieordner kann den Skill vollständig aus der Indexierung ausschließen.
• Token-Last – Wenn Sessions langsam wirken, kürzen Sie Beschreibungen der Stufe null, verschieben Sie Tiefe in references/ und deduplizieren Sie riesige Tabellen.
• Agent-Edits – Hermes kann Skills über skill_manage erstellen, patchen oder löschen. Behandeln Sie wertvolle Skills wie Code: überprüfen Sie Diffs, exportieren Sie Snapshots und setzen Sie gebündelte Skills bewusst zurück, wenn Upgrades abweichen.

Ein enger Regressions-Loop schlägt das erneute Lesen der gesamten Datei: hermes chat --toolsets skills -q "Use the <skill> workflow to <concrete task>" sollte zeigen, dass der Agent das richtige Offenlegungslevel zieht, bevor er freestylet. Wenn er skill_view nie aufruft, passt Ihr When to use-Text oder Ihre description wahrscheinlich nicht dazu, wie Leute Anfragen formulieren.

Offizielle Referenzen bleiben maßgeblich für Verhaltensänderungen – der Skills System-Benutzerleitfaden für Runtime-Semantik, Creating Skills für autorbezogene Regeln, der Bundled Skills Catalog für Copy-Paste-Beispiele und die agentskills.io specification für das gemeinsame Dateiformat, mit dem Hermes übereinstimmt.