Hermes Agent Vaardigheidsontwikkeling — structuur en best practices voor SKILL.md

Hermes Agent behandelt vaardigheden (skills) als de standaardmanier om herhaalbare werkstromen te leren. De officiële documentatie beschrijft ze als kennisdocumenten op aanvraag, afgestemd op de open agentskills.io specificatie, die worden geladen via progressive disclosure (stapsgewijze onthulling), zodat het model eerst een kleine index ziet en volledige instructies alleen ophaalt wanneer een taak dit daadwerkelijk vereist.

Het schrijven van vaardigheden gaat minder over slimme formuleringen dan over verpakking: je vertelt de runtime wanneer een procedure moet worden geladen, welke volgorde van stappen als “klaar” telt en hoe je succes onderscheidt van een stille fout. Dit artikel richt zich op de structuur van SKILL.md, ondersteunende mappen, zichtbaarheidsregels en de scheiding tussen geheime en niet-geheime instellingen: de details die bepalen of een vaardigheid verschijnt in /slash-commando’s, overleeft een hub-installatie of stil verdwijnt in CI-omgevingen.

Hermes maakt deel uit van de bredere AI-systemen: Zelfgehoste assistenten, RAG en lokale infrastructuur-cluster, waarin assistenten worden behandeld als systemen die zijn opgebouwd uit inferentie, ophaling, geheugen en hulpmiddelen, in plaats van als een enkel chatoppervlak. Installatiepaden, provider-koppelingen, gatewaygedrag en de indeling van ~/.hermes worden allemaal uitgewerkt in de Hermes AI-assistent - Installatie, instelling, werkstroom en probleemoplossing-gids; dagelijkse shell-ergonomieën—hermes skills, profielen, gateway, geheugen—zijn makkelijker te scannen in de Hermes Agent CLI-cheat sheet — commando’s, vlaggen en slash-knoppen. In echte implementaties erven vaardigheden isolatie over van profielen (afzonderlijke configuratie, geheimen, geheugens en vaardigheidsbomen). Hermes AI-assistent-vaardigheden voor echte productie-instellingen pleit voor het behandelen van die profielen—niet individuele markdown-bestanden—als de eenheid van eigenaarschap; houd dit in gedachten wanneer je vaardigheden naamgeeft en beslist wat in gedeelde external_dirs hoort versus in één profiel.

Vaardigheid of hulpmiddel (tool)?

De officiële richtlijn is direct. Gebruik een vaardigheid wanneer de capaciteit voornamelijk bestaat uit proza-instructies plus shell-commando’s en hulpmiddelen die Hermes al blootlegt—het omhullen van een CLI, het besturen van git, het aanroepen van curl of het gebruik van web_extract voor gestructureerde ophalingen. Gebruik een hulpmiddel wanneer je strakke integratie nodig hebt voor API-sleutels en authenticatiestromen, deterministische binaire afhandeling, streaming of Python die elke keer op dezelfde manier moet worden uitgevoerd.

Die grens is in de praktijk belangrijk omdat vaardigheden worden geleverd zonder de agentcode te wijzigen, terwijl hulpmiddelen overhead voor review en release met zich meebrengen. De meeste teams profiteren ervan om te beginnen met een vaardigheid en pas de kwetsbare kern te promoveren tot een hulpmiddel zodra de faalmodi duidelijk zijn (auth-verversingslussen, binaire parsers, strikte idempotentie).

Procedures versus gecureerd geheugen

Vaardigheden beantwoorden de vraag hoe een werkstroom moet worden uitgevoerd; het begrenste kerngeheugen van Hermes beantwoordt de vraag wat al is overeengekomen over de gebruiker en het project. Een vaardigheid wordt geladen wanneer de taak overeenkomt met de beschrijving; MEMORY.md en USER.md blijven in de prompt als een kleine, gecureerde feitelijke laag. De twee mechanismen stapelen zich in plaats van te concurreren, en het volledige beeld van snapshots, limieten en externe providers wordt uitgewerkt in Hermes Agent Geheugensysteem: Hoe persistent AI-geheugen echt werkt.

Anatomie van een vaardigheidsmap

Op de schijf is elke vaardigheid een map onder ~/.hermes/skills/, vaak genest onder een categorie zoals devops/ of research/. Hermes verwacht SKILL.md op het bladerniveau; alles else is optionele structuur die je toevoegt wanneer de instructies anders zouden uitspatten. Het gebruikelijke patroon is references/ voor lange tabellen of vendor-documentatie, templates/ voor output-schetsen, scripts/ voor deterministische helpers en assets/ voor statische bestanden die de agent niet opnieuw moet ophalen.

Die indeling weerspiegelt hoe progressive disclosure in de praktijk werkt: de agent kan bij het hoofdbestand blijven totdat het echt een diepgaande appendix nodig heeft. Het houden van “happy path”-proza in SKILL.md en het verplaatsen van zelden gebruikte details naar references/ is een van de goedkoopste manieren om tokenbudgetten te beschermen.

Hermes kan ook externe vaardigheidsmappen samenvoegen via skills.external_dirs in config.yaml. Die paden worden gescand voor ontdekking, maar de agent schrijft nog steeds via skill_manage naar de primaire ~/.hermes/skills/-boom. Lokale namen overschaduwen externe, dus als je een gedeelde vaardigheid in je home-directory “fixt”, zien collega’s die dezelfde externe repo pullen je bewerking niet voordat ze de lokale kopie verwijderen of hernoemen—een veelvoorkomende bron van “het werkt op mijn machine”-verwarring.

SKILL.md frontmatter dat de review overleeft

De body van SKILL.md is Markdown; het openingsblok moet een geldige YAML zijn tussen ----delimiters. Echte vaardigheden accumuleren lange omheinde voorbeelden, dus de kleine gewoontes uit Markdown Code Blocks: Complete Guide with Syntax, Languages & Examples—consistent taaltags, leesbare fragmenten, strakke omheiningen—houden grote bestanden maintainable voor mensen en iets gemakkelijker te scannen voor het model.

Verplichte velden zijn name en description. De name wordt de slash-route en de indexsleutel; deze blijft in kleine letters met koppeltekens en moet voldoen aan de gedocumenteerde lengtelimiet. De description is het enige proza waar veel sessies ooit voor betalen op niveau nul, dus het zou moeten lezen als een zoekresultaat of routeringsstring (“wanneer backups oud lijken, verifieer het nieuwste archief en checksum”), niet als de eerste alinea van een blogpost.

Optionele toplevel-sleutels zoals version, author en license helpen bij hub-verpakking en audits. De platforms-lijst (macos, linux, windows) is scherper dan het lijkt—wanneer ingesteld, laat Hermes de vaardigheid volledig weg op niet-overeenkomende hosts, wat de reden is waarom een vaardigheid die “werkt op mijn Mac” kan verdwijnen in Linux CI zonder een foutmelding buiten een kortere vaardigheidslijst.

Hermes-specifieke knoppen staan onder metadata.hermes: tags, related_skills en de conditionele zichtbaarheidsvelden in het volgende gedeelte. required_environment_variables declareert geheimen die in .env moeten landen en door moeten worden gegeven naar sandboxes; required_credential_files dekt OAuth-tokenbestanden en andere op de schijf opgeslagen referenties die moeten worden gemount in Docker of Modal; metadata.hermes.config declareert niet-geheime voorkeuren die worden opgeslagen onder skills.config in config.yaml.

Officiële documenten benadrukken grootte-discipline om een reden. Knip de description tot zijn budget, begin met de procedure en verplaats historische notities of enorme optietabellen naar references/ zodat een gedeeltelijke skill_view de agent nog steeds iets uitvoerbaars geeft.

Hieronder staat een minimale SKILL.md die je kunt dropen in ~/.hermes/skills/devops/backup-check/SKILL.md (of elke andere categoriemap) en daar verder kunt itereren.

---
name: backup-check
description: Verifieer dat nachtelijke backup-archieven bestaan, niet-leeg zijn en een snelle checksum-spotcheck doorstaan op het nieuwste bestand.
version: 1.0.0
metadata:
  hermes:
    tags: [devops, backups, shell]
    requires_toolsets: [terminal]
    config:
      - key: backup_check.archive_dir
        description: Absoluut pad naar de map die backup-archieven bevat
        default: "/var/backups"
        prompt: Backup-archiefmap (absoluut pad)
---

# Spotcheck voor backup-archieven

## Wanneer te gebruiken

Gebruik wanneer de gebruiker vraagt om te bevestigen dat backups zijn uitgevoerd, het nieuwste archief op de schijf te auditen, of lege of verouderde backupbestanden te vangen voordat een herstel-oefening plaatsvindt.

## Snelle referentie

- De nieuwste archiefmap is geconfigureerd onder `skills.config.backup_check.archive_dir` (instellen via `hermes config migrate` indien gedeclareerd in metadata).
- De standaardcheck gebruikt `ls` op mtime en `test -s` voor niet-lege bestanden.

## Procedure

1. Los de archiefmap op vanuit de vaardigheidsconfiguratie of vraag de gebruiker één keer als deze niet is ingesteld.
2. Lijst het meest recent gewijzigde bestand op dat overeenkomt met het verwachte patroon (bijvoorbeeld `*.tar.zst`).
3. Bevestig dat het bestand bestaat, niet-leeg is en noteer het pad en de grootte voor het antwoord.
4. Als er een checksum-bestand naast het archief bestaat, verifieer het met het gedocumenteerde hulpmiddel (bijvoorbeeld `sha256sum -c`).

## Valkuilen

- Lege bestanden kunnen nog steeds een recente mtime hebben als een mislukte taak het pad heeft aangeraakt; controleer altijd de grootte.
- Relatieve paden breken wanneer de terminal-cwd niet de backup-host is; gebruik absolute paden in de configuratie.

## Verificatie

De gebruiker zou het pad van het nieuwste archief, de bytesgrootte en of een checksum OK-regel of een expliciete notitie moeten zien dat er geen `.sha256`-sidecar is gevonden.

Progressive disclosure in de praktijk

Progressive disclosure is het verschil tussen een vaardigheidsbibliotheek die snel aanvoelt en een die duizenden tokens verbrandt voordat het eerste gebruikersbericht. Hermes doorloopt drie conceptuele stappen: een compacte catalogus (namen en korte beschrijvingen), de volledige SKILL.md wanneer de taak overeenkomt, en—alleen indien nodig—een slice van een referentiebestand via skill_view-paden. Ga er van uit dat niveau nul alles is wat het model zal lezen totdat het expliciet committeert; elke zin in de description en het eerste scherm van bodytekst moeten helpen bij routing, niet bij verhalen vertellen.

Een praktische outline die gedeeltelijke laden overleeft is Wanneer te gebruiken (triggers in platte taal), Snelle referentie (commando’s, omgevingsvariabelen, bestandsnamen), Procedure (gerangschikte stappen die de agent niet moet improviseren), Valkuilen (bekende faalmodi) en Verificatie (hoe “groen” eruit ziet). Narratieve geschiedenis, vendor-changelog-dumps en tabellen met twintig rijen behoren in references/ met stabiele koppen zodat de agent een enkele sectie kan ophalen.

Wanneer een vaardigheid activeert, kan Hermes ${HERMES_SKILL_DIR} en ${HERMES_SESSION_ID} in de body herschrijven zodat shell-regels wijzen naar de geïnstalleerde map zonder handgemaakte paden. Optionele inline shell-fragmenten (!cmd``) kunnen verse context injecteren (huidige branch, vrije schijfruimte), maar ze worden uitgevoerd op de host en blijven uitgeschakeld tenzij skills.inline_shell is ingeschakeld—beschouw die vlag als een vertrouwensgrens voor de hele vaardigheidsbron, niet als een handig schakeltje.

Conditionele activatie en prompt-hygiëne

Vaardigheden kunnen tonen of verbergen op basis van welke toolsets of tools bestaan in de huidige sessie. requires_toolsets / requires_tools plaatsen een vaardigheid achter capaciteiten die aanwezig moeten zijn; fallback_for_toolsets / fallback_for_tools tonen een goedkopere of lokale pad wanneer een premium integratie afwezig is—de DuckDuckGo-fallback wanneer een betaalde webzoek-API niet is geconfigureerd, is het canonieke voorbeeld.

Deze predicaten vormen direct prompt-ruis. Een te strenge requires_*-regel verbergt een vaardigheid voor nieuwkomers die hermes tools-instelling nog niet hebben afgerond; een te losse fallback_for_*-regel dubbele helft van je bibliotheek telkens wanneer iemand een API-sleutel over het hoofd ziet. Het nuttige middenpad is om echte vereisten te noemen, te testen met hermes chat --toolsets skills en sleutels of toolsets opzettelijk in/uit te schakelen terwijl je bekijkt of de vaardigheidslijst ademt zoals je verwacht.

Geheimen, configuratie en referentiebestanden

Geheimen moeten worden gedeclareerd in required_environment_variables. Hermes kan vragen wanneer een vaardigheid wordt geladen in de lokale CLI, waarden persistent maken in .env en ze doorgeven naar terminal- en execute_code-sandboxes zonder het ruwe geheim terug te streamen naar het modeltranscript. Remote chatoppervlakken weigeren sleutels inline te verzamelen en verwijzen mensen in plaats daarvan naar hermes setup of handmatige .env-bewerkingen—schrijf je vaardigheidstekst zodat deze gedragingspatroon volgt (vertel gebruikers dat een sleutel vereist is, niet *om het in Telegram te plakken).

Niet-geheime voorkeuren—standaardpaden, orgnamen, feature-toggles—behooren tot metadata.hermes.config. Waarden worden opgelost in skills.config binnen config.yaml, verschijnen in hermes config show en komen aan in het vaardigheidsbericht als opgeloste feiten zodat het model je configuratiebestand niet midden in een taak hoeft te openen.

Bestandsvormige referenties (OAuth-token JSON, service-account-sleutels) worden gemapt naar required_credential_files. Wanneer die bestanden bestaan, kan Hermes ze bind-mounten in Docker of synchroniseren in Modal-taken; het vooraf declareren ervan vermijdt het klassieke “script werkt lokaal, sterft in sandbox”-gat.

Ondersteunende scripts en afhankelijkheden

De upstream-gids dringt auteurs aan tot saamlopende afhankelijkheden: stdlib Python, curl en Hermes’ eigen tools (web_extract, read_file, terminal). Dat gaat minder over zuiverheid dan over reproduceerbaarheid—elke extra pip install is een andere stille fout wanneer de agent draait in een schone container.

Wanneer JSON- of XML-parsing lastig is, wint een kort script onder scripts/ plus een ${HERMES_SKILL_DIR}-pad het van het vragen aan het model om parsers elke run opnieuw af te leiden. Als je echt een pakket nodig hebt, vermeld het installatiecommando in Procedure, herhaal het faalsymptom in Valkuilen en geef een Verificatie-commando dat hard faalt wanneer de afhankelijkheid ontbreekt.

Publiceren, hub-installaties en vertrouwen

Community-vaardigheden bewegen door de Skills Hub en de andere ontdekkingspaden die de gebruikersgids noemt—officiële optionele vaardigheden, GitHub-slugs, skills.sh-entries, .well-known-indexen en ruwe SKILL.md-URLs. Installaties worden gescand op voor de hand liggende exfiltratie, injectie en destructieve patronen; vertrouwingsniveaus lopen van builtin via community, en sommige bevindingen worden alleen gewist met --force terwijl de ergste gevallen volledig worden geblokkeerd.

De SKILL.md-bestandsvorm is niet Hermes-specifiek; IDE-gerichte assistenten gebruiken hetzelfde idee van stapsgewijze loading met verschillende ontdekking en triggers. Claude Vaardigheden en SKILL.md voor Ontwikkelaars: VS Code, JetBrains, Cursor is een nuttig contrastlees—frontmatter-discipline en “laad alleen wanneer relevant” dragen over, zelfs wanneer de installer en slash-commando-koppeling verschillen.

Org-brede roll-outs paren meestal een private tap of gedeelde Git-repo met external_dirs voor read-only delen, terwijl ze de agent-schrijfbare kopie onder elk profiel houden wanneer skill_manage vaardigheden op hun plaats mag muteren.

Probleemoplossing en optimalisatie

Wanneer een vaardigheid zich verkeerd gedraagt, loop dan deze checklist af voordat je proza herschrijft.

• Zichtbaarheid — Bevestig platforms, requires_* en fallback_for_*-predicaten. Een vaardigheid die “werkt op mijn Mac” maar niet in Linux CI is vaak een platform-guard.
• Naamcollisions — Dubbele namen over lokale en externe mappen volgen lokale precedentie. Hernoem of namespace agressief.
• Ontdekkingsindeling — Een verkeerd geplaatste SKILL.md of verkeerde categoriemap kan de vaardigheid volledig laten vallen uit de indexering.
• Token-load — Als sessies langzaam aanvoelen, verkort niveau-nul-beschrijvingen, verplaats diepgang naar references/ en deduplicateer enorme tabellen.
• Agent-bewerkingen — Hermes kan vaardigheden maken, patchen of verwijderen via skill_manage. Behandel waardevolle vaardigheden als code: review diffs, exporteer snapshots en reset gebundelde vaardigheden bewust wanneer upgrades afwijken.

Een strakke regressielus wint van het herlezen van het hele bestand: hermes chat --toolsets skills -q "Gebruik de <vaardigheid>-werkstroom voor <concrete taak>" zou de agent moeten laten zien die het juiste disclosure-niveau ophaalt voordat het freestyles. Als het nooit skill_view aanroept, komt je Wanneer te gebruiken-tekst of description waarschijnlijk niet overeen met hoe mensen verzoeken formuleren.

Officiële referenties blijven autoritair voor gedragsveranderingen—de Skills System-gebruikersgids voor runtime-semantiek, Creating Skills voor author-gerichte regels, de Bundled Skills Catalog voor copy-paste-voorbeelden, en de agentskills.io specificatie voor het gedeelde bestandsformaat waarmede Hermes zich uitlijnt.