Att skapa Hermes-agentkompetenser — Struktur och bästa praxis för SKILL.md

Hermes Agent behandlar färdigheter (skills) som det vanliga sättet att lära ut återanvändbara arbetsflöden. Officiell dokumentation beskriver dem som kunskapsdokument på begäran, anpassade efter den öppna agentskills.io-specifikationen, och de laddas genom progressiv diskling (progressive disclosure) så att modellen först ser en liten index och endast hämtar fullständiga instruktioner när en uppgift faktiskt kräver dem.

Att skapa färdigheter handlar mindre om smart formulering och mer om förpackning – du informerar runtime-systemet om när en procedur ska laddas, vilken ordning på stegen som räknas som ”klart”, och hur man skiljer framgång från en tyst misslyckande. Denna artikel fokuserar på strukturen för SKILL.md, stödmappar, synlighetsregler och uppdelningen mellan hemliga och icke-hemliga inställningar – de detaljer som avgör om en färdighet visas i /slash-kommandon, överlever en installation via hubben, eller tyst försvinner i CI-miljöer.

Hermes ingår i det bredare AI Systems: Self-Hosted Assistants, RAG, and Local Infrastructure-klustret, där assistenter behandlas som system byggda från inferens, hämtning (retrieval), minne och verktyg, snarare än som en enda chattgränssnitt. Installationsvägar, provider-kopplingar, gateway-beteende och layouten av ~/.hermes redovisas i guiden Hermes AI Assistant - Install, Setup, Workflow, and Troubleshooting; daglig terminalhantering – hermes skills, profiler, gateway, minne – är lättare att granska i Hermes Agent CLI cheat sheet — commands, flags, and slash shortcuts. I verkliga deploymentar ärver färdigheter isolering från profiler (separat konfiguration, hemligheter, minnen och färdighets-träd). Hermes AI Assistant Skills for Real Production Setups argumenterar för att behandla dessa profiler – inte individuella markdown-filer – som enheten för ägarskap; ha detta i åtanke när du namnger färdigheter och bestämmer vad som hör hemma i delade external_dirs kontra en enskild profil.

Färdighet eller verktyg?

Den officiella riktlinjen är rak. Använd en färdighet när förmågan huvudsakligen består av prosainstruktioner samt shell-kommandon och verktyg som Hermes redan exponerar – att wrapa en CLI, styra git, anropa curl, eller använda web_extract för strukturerade hämtningar. Använd ett verktyg när du behöver tät integration för API-nycklar och auth-flöden, deterministisk binärhantering, strömning, eller Python som måste exekveras exakt på samma sätt varje gång.

Denna gräns är viktig i praktiken eftersom färdigheter levereras utan att ändra agentkoden, medan verktyg medför gransknings- och släppadministrativ börda. De flesta team gynnas av att börja med en färdighet, och först därefter lyfta den spräckliga kärnan till ett verktyg när misslyckandemoderna är uppenbara (auth-uppdateringsloopar, binära parsrar, strikt idempotens).

Procedurer jämfört med kuraterat minne

Färdigheter svarar på hur man kör ett arbetsflöde; Hermess begränsade kärnminne svarar på vad som redan har beslutats om användaren och projektet. En färdighet laddas när uppgiften matchar dess beskrivning; MEMORY.md och USER.md stannar i prompten som ett litet, kuraterat fakta-lager. De två mekanismerna staplas snarare än att de tävlar, och den fulla bilden av snapshot, gränser och externa leverantörer redovisas i Hermes Agent Memory System: How Persistent AI Memory Actually Works.

Anatomien av en färdighetskatalog

På disk är varje färdighet en mapp under ~/.hermes/skills/, ofta inbäddad under en kategori som devops/ eller research/. Hermes förväntar sig SKILL.md i bladläget; allt annat är valfri struktur som du lägger till när instruktionerna annars skulle sprida sig. Den vanliga mönstret är references/ för långa tabeller eller leverantörsdokument, templates/ för utmatningsskelett, scripts/ för deterministiska hjälpmedel, och assets/ för statiska filer som agenten inte bör hämta om.

Denna layout speglar hur progressiv diskling fungerar i praktiken: agenten kan stanna vid huvudfilen tills den verkligen behöver ett djupare appendix. Att hålla ”happy path”-prosa i SKILL.md och flytta sällan använda detaljer till references/ är ett av de billigaste sätten att skydda token-budgeten.

Hermes kan också slå in externa färdighetskataloger via skills.external_dirs i config.yaml. Dessa sökvägar skannas för upptäckt, men agenten skriver fortfarande genom skill_manage i primära ~/.hermes/skills/-trädet. Lokala namn överskuggar externa, så om du ”fixar” en delad färdighet i din hemkatalog kommer teamkollegor som hämtar samma externa repo inte se din redigering förrän de tar bort eller döper om den lokala kopian – en vanlig källa till ”det fungerar på min maskin”-förvirring.

SKILL.md frontmatter som överlever granskning

Kroppen av SKILL.md är Markdown; öppningsblocket måste vara giltig YAML mellan ----avgränsare. Verkliga färdigheter ackumulerar långa inramade exempel, så de små vanterna från Markdown Code Blocks: Complete Guide with Syntax, Languages & Examples – konsekventa språktaggar, läsbara utdrag, täta inramningar – håller stora filer underhållbara för människor och något lättare för modellen att skanna.

Obligatoriska fält är name och description. name blir slash-rutinen och indexnyckeln; den förblir små bokstäver med bindestreck och måste respektera den dokumenterade längdgränsen. description är den enda prosa som många sessioner betalar för på nivå noll, så den ska läsas som ett sökresultat eller router-sträng (”när backups verkar utdaterade, verifiera senaste arkiv och checksumma”), inte som första stycket i ett blogginlägg.

Valfria toppnivå-nycklar som version, author och license hjälper till med hubb-packaging och revisioner. platforms-listan (macos, linux, windows) är skarpare än den ser ut – när den är inställd lämnar Hermes färdigheten helt bort på icke-matchande värdar, vilket är varför en färdighet som ”fungerar på min Mac” kan försvinna i Linux CI utan felmeddelande bortom en kortare färdighetslista.

Hermes-specifika reglage finns under metadata.hermes: tags, related_skills, och de villkorliga synlighetsfälten i nästa avsnitt. required_environment_variables deklarerar hemligheter som bör landa i .env och passeras in i sandlådor; required_credential_files täcker OAuth-tokenfiler och andra på-disk-credentialer som måste mountas in i Docker eller Modal; metadata.hermes.config deklarerar icke-hemliga preferenser som lagras under skills.config i config.yaml.

Officiell dokumentation betonar storleksdisciplin av en anledning. Trimma description till sin budget, prioritera proceduren, och flytta historiska anteckningar eller enorma matriser till references/ så att en partiell skill_view fortfarande ger agenten något hanterbart.

Nedan är en minimal SKILL.md som du kan lägga i ~/.hermes/skills/devops/backup-check/SKILL.md (eller valfri kategorimapp) och iterera från där.

---
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.

Progressiv diskling i praktiken

Progressiv diskling är skillnaden mellan en färdighetsbibliotek som känns snabb och ett som bränner tusentals token innan första användarmeddelandet. Hermes går tre konceptuella steg: en kompakt katalog (namn och korta beskrivningar), hela SKILL.md när uppgiften matchar, och – endast om behövt – ett utsnitt av en referensfil via skill_view-vägar. Anta att nivå noll är allt modellen kommer läsa tills den explicit engagerar sig; varje mening i description och den första skärmen med kroppstext ska hjälpa routning, inte berättande.

En praktisk kontur som överlever partiella laddningar är When to use (triggare i enkel språk), Quick reference (kommandon, miljövariabler, filvägar), Procedure (ordnade steg som agenten inte bör improvisera bort), Pitfalls (kända misslyckandemod), och Verification (vad ”grönt” ser ut). Narrativ historia, leverantörschangelog-dumpar och tjugoradiga optionstabeller hör hemma i references/ med stabila rubriker så att agenten kan hämta ett enskilt avsnitt.

När en färdighet aktiveras kan Hermes skriva om ${HERMES_SKILL_DIR} och ${HERMES_SESSION_ID} i kroppen så att shell-rader pekar på den installerade mappen utan handbyggda vägar. Valfri inline shell-snuttar (!cmd``) kan injecera färsk kontext (nuvarande gren, ledigt diskutrymme), men de exekveras på värdmaskinen och stannar inaktiverade om inte skills.inline_shell är på – behandla den flaggan som en gräns för förtroende för hela färdighetskällan, inte som en bekvämlighetsbrytare.

Villkorlig aktivering och prompt-hygien

Färdigheter kan visa eller dölja sig baserat på vilka verktygssatser eller verktyg som finns i den aktuella sessionen. requires_toolsets / requires_tools stänger en färdighet bakom förmågor som måste vara närvarande; fallback_for_toolsets / fallback_for_tools ytan en billigare eller lokal väg när en premiumintegration saknas – DuckDuckGo-fallbacken när en betald webbsearch-API inte är konfigurerad är det kanoniska exemplet.

Dessa predikat formar direkt prompt-brus. En för strikt requires_*-regel döljer en färdighet från nybörjare som inte avslutat hermes tools-inställningen än; en för lös fallback_for_*-regel duplicerar hälften av ditt bibliotek varje gång någon utelämnar en API-nyckel. Den användbara mellangrunden är att namnge verkliga förutsättningar, testa med hermes chat --toolsets skills, och växla nycklar eller verktygssatser avsiktligt medan man tittar på om färdighetslistan andas som du förväntar dig.

Hemligheter, konfiguration och credential-filer

Hemligheter bör deklareras i required_environment_variables. Hermes kan prompta när en färdighet laddas i den lokala CLI, persistera värden i .env, och passera dem in i terminal- och execute_code-sandlådor utan att strömma den råa hemligheten tillbaka i modeltranskriptet. Remota chattytter vägrar samla nycklar inline och pekar istället människor mot hermes setup eller manuella .env-redigeringar – skriv din färdighetstext så att den matchar det beteendet (berätta för användare att en nyckel krävs, inte att klistra in den i Telegram).

Icke-hemliga preferenser – standardvägar, org-namn, feature-toggles – hör hemma i metadata.hermes.config. Värdena löses in i skills.config inuti config.yaml, visas i hermes config show, och anländer i färdighetsmeddelandet som lösta fakta så att modellen inte behöver öppna din konfigurationsfil mitt i uppgiften.

Filformade credentialer (OAuth-token JSON, service account keys) mappar till required_credential_files. När dessa filer finns kan Hermes bind-mounta dem in i Docker eller synka dem in i Modal-jobb; att deklarera dem i förväg undviker den klassiska gapet ”skript fungerar lokalt, dör i sandlåda”.

Stödsript och beroenden

Den upstream-guider pressar författare mot tråkiga beroenden: stdlib Python, curl, och Hermess egna verktyg (web_extract, read_file, terminal). Det handlar mindre om renhet än om reproducerbarhet – varje extra pip install är en tyst misslyckande när agenten kör i en ren container.

När JSON- eller XML-parsing är flummig, vinner ett kort skript under scripts/ plus en ${HERMES_SKILL_DIR}-väg mot att be modellen om att återleda parsrar varje gång. Om du verkligen behöver ett paket, ange installationskommandot i Procedure, upprepa misslyckandet i Pitfalls, och ge ett Verification-kommando som misslyckas högljutt när beroendet saknas.

Publicering, hubb-installationer och förtroende

Community-färdigheter flyttas genom Skills Hub och de andra upptäcktsvägar som användarguiden listar – officiella valfria färdigheter, GitHub-slugs, skills.sh-poster, .well-known-index, och råa SKILL.md-URL:er. Installationer skannas för uppenbara exfiltrering, injektion och destruktiva mönster; förtroendenivåer löper från builtin genom community, och vissa fynd klaras endast med --force medan de värsta fallen blockerar helt.

SKILL.md-filformatet är inte Hermes-specifikt; IDE-centrerade assistenter använder samma idé om progressiv laddning med annan upptäckt och triggare. Claude Skills and SKILL.md for Developers: VS Code, JetBrains, Cursor är en användbar kontrastläsning – frontmatter-disciplin och ”ladda endast när relevant” bär över, även när installatören och slash-kommandokopplingen skiljer sig.

Org-wide rullningar parar vanligtvis en privat tap eller delad Git-repo med external_dirs för read-only-delning, medan den agent-skrivbara kopian hålls under varje profil när skill_manage tillåts mutera färdigheter på plats.

Felsökning och optimering

När en färdighet beter sig fel, gå igenom denna checklista innan du skriver om prosan.

• Synlighet — Bekräfta platforms, requires_*, och fallback_for_*-predikat. En färdighet som ”fungerar på min Mac” men inte i Linux CI är ofta en plattformsguard.
• Namnkollisioner — Dubletterade namn över lokala och externa kataloger följer lokal prioritet. Byt namn eller namnrym aggressivt.
• Upptäcktslayout — En felplacerad SKILL.md eller fel kategorimapp kan dropa färdigheten från indexeringen helt.
• Token-belastning — Om sessioner känns långsamma, förkorta nivå-noll-beskrivningar, flytta djupet till references/, och deduplicera enorma tabeller.
• Agentredigeringar — Hermes kan skapa, patcha eller ta bort färdigheter via skill_manage. Behandla värdefulla färdigheter som kod: granska diffs, exportera snapshots, och återställ bundled skills medvetet när uppgraderingar drifter.

En tät regressionsloop slår att läsa om hela filen: hermes chat --toolsets skills -q "Use the <skill> workflow to <concrete task>" bör visa agenten som drar rätt diskling-nivå innan den freestyler. Om den aldrig anropar skill_view, matchar din When to use-text eller description troligen inte hur människor formulerar begäran.

Officiella referenser förblir auktoritativa för beteendeförändringar – Skills System-användarguiden för runtime-semantik, Creating Skills för författarriktade regler, Bundled Skills Catalog för copy-paste-exempel, och agentskills.io specification för det delade filformat Hermes anpassar sig efter.