Creazione di skill per l'agente Hermes — struttura e migliori pratiche per SKILL.md

Hermes Agent tratta le skills come il metodo predefinito per insegnare flussi di lavoro ripetibili. La documentazione ufficiale le descrive come documenti di conoscenza on-demand allineati alla specifica aperta agentskills.io, caricati tramite progressive disclosure in modo che il modello veda prima un indice ridotto e richieda le istruzioni complete solo quando un task ne ha effettivamente bisogno.

L’autoreing è meno una questione di parole accorte e più di packaging—si sta dicendo al runtime quando caricare una procedura, quale sequenza di passi conta come “completato” e come distinguere il successo da un fallimento silenzioso. Questo articolo si concentra sulla struttura di SKILL.md, le cartelle di supporto, le regole di visibilità e la distinzione tra impostazioni segrete e non segrete—i dettagli che determinano se una skill appare nei comandi /slash, sopravvive a un’installazione hub o scompare silenziosamente in CI.

Hermes si colloca all’interno del più ampio cluster AI Systems: Self-Hosted Assistants, RAG, and Local Infrastructure dove gli assistenti sono trattati come sistemi costruiti da inferenza, retrieval, memoria e tooling piuttosto che come un singolo interfaccia chat. I percorsi di installazione, il cablaggio dei provider, il comportamento del gateway e la struttura di ~/.hermes sono tutti dettagliati nella guida Hermes AI Assistant - Install, Setup, Workflow, and Troubleshooting; l’ergonomia quotidiana della shell—hermes skills, profili, gateway, memoria—è più facile da consultare nel Hermes Agent CLI cheat sheet — commands, flags, and slash shortcuts. In deployment reali, le skills ereditano l’isolamento dai profili (configurazione separata, segreti, memorie e alberi di skill). Hermes AI Assistant Skills for Real Production Setups sostiene di trattare quei profili—non i singoli file markdown—come unità di ownership; tenerlo a mente quando si nominano skills e si decide cosa appartiene a external_dirs condivise versus un singolo profilo.

Skill o tool?

La guida ufficiale è diretta. Usa una skill quando la capacità consiste principalmente in istruzioni testuali più comandi shell e tool che Hermes espone già—avvolgere un CLI, guidare git, chiamare curl o usare web_extract per fetch strutturati. Usa un tool quando serve integrazione stretta per API keys e flussi di autenticazione, handling deterministico di binari, streaming o Python che deve eseguire nello stesso modo ogni volta.

Quel confine ha importanza pratica perché le skills si distribuiscono senza modificare il codice dell’agente, mentre i tools comportano overhead di review e release. La maggior parte dei team beneficia di iniziare con una skill, poi promuovere solo il nucleo fragile a tool una volta che i failure mode sono ovvi (loop di refresh auth, parser binari, idempotenza stretta). Per la domanda architetturale più ampia su quando usare un Agent Skill versus un server MCP—specialmente riguardo credenziali, stato live e scritture transazionali—vedi il nostro Agent Skills vs MCP Servers decision framework.

Procedure versus memoria curata

Le skills rispondono al come eseguire un workflow; la memoria core bounded di Hermes risponde al cosa è già stato concordato riguardo all’utente e al progetto. Una skill si carica quando il task corrisponde alla sua descrizione; MEMORY.md e USER.md rimangono nel prompt come strato fatto di fatti piccoli e curati. I due meccanismi si impilano anziché competere, e l’immagine completa di snapshot, limiti e provider esterni è dettagliata in Hermes Agent Memory System: How Persistent AI Memory Actually Works.

Anatomia di una directory skill

Su disco, ogni skill è una cartella sotto ~/.hermes/skills/, spesso nidificata sotto una categoria come devops/ o research/. Hermes si aspetta SKILL.md alla foglia; tutto il resto è struttura opzionale che aggiungi quando le istruzioni altrimenti si estenderebbero. Il pattern usuale è references/ per tabelle lunghe o documentazione vendor, templates/ per scheletri di output, scripts/ per helper deterministici e assets/ per file statici che l’agente non dovrebbe re-fetchare.

Quella struttura riflette come funziona la progressive disclosure nella pratica: l’agente può restare al file principale finché non ha davvero bisogno di un appendice profonda. Tenere il “happy path” in SKILL.md e spostare i dettagli raramente usati in references/ è uno dei modi più economici per proteggere i budget token.

Hermes può anche mergeare directory skill esterne tramite skills.external_dirs in config.yaml. Quei percorsi sono scansionati per discovery, ma l’agente scrive comunque attraverso skill_manage nell’albero primario ~/.hermes/skills/. I nomi locali shadowano quelli esterni, quindi se “risolvi” una skill condivisa nella tua home directory, i colleghi che pullano la stessa repo esterna non vedranno la tua modifica finché non rimuoveranno o rinomineranno la copia locale—una fonte comune di confusione “funziona sulla mia macchina”.

SKILL.md frontmatter che sopravvive alla review

Il corpo di SKILL.md è Markdown; il blocco iniziale deve essere YAML valido tra delimiter ---. Le skills reali accumulano lunghi esempi fenced, quindi le piccole abitudini da Markdown Code Blocks: Complete Guide with Syntax, Languages & Examples—tag di linguaggio consistenti, estratti leggibili, fence stretti—mantengono i file grandi manutenibili per gli umani e leggermente più facili da scansionare per il modello.

I campi obbligatori sono name e description. Il name diventa la route slash e la chiave dell’indice; resta minuscolo con trattini e deve rispettare il limite di lunghezza documentato. La description è l’unica prosa che molte sessioni pagano mai al livello zero, quindi dovrebbe leggere come un risultato di ricerca o stringa router (“quando i backup sembrano obsoleti, verifica ultimo archivio e checksum”), non il primo paragrafo di un post blog.

Chiavi top-level opzionali come version, author e license aiutano il packaging hub e gli audit. La lista platforms (macos, linux, windows) è più tagliente di quanto sembri—quando impostata, Hermes omette la skill interamente su host non corrispondenti, motivo per cui una skill che “funziona sul mio Mac” può sparire in CI Linux senza messaggio d’errore oltre a una lista skill più corta.

I knob specifici Hermes vivono sotto metadata.hermes: tags, related_skills e i campi di visibilità condizionale nella prossima sezione. required_environment_variables dichiara segreti che dovrebbero atterrare in .env e passare nei sandbox; required_credential_files copre file token OAuth e altre credenziali su disco che devono montarsi in Docker o Modal; metadata.hermes.config dichiara preferenze non segrete memorizzate sotto skills.config in config.yaml.

La documentazione ufficiale sottolinea la disciplina sulle dimensioni per un motivo. Riduci la description al suo budget, front-loada la procedura e sposta note storiche o enormi matrici di opzioni in references/ così una skill_view parziale dà comunque all’agente qualcosa di azionabile.

Di seguito è una SKILL.md minimale che puoi inserire in ~/.hermes/skills/devops/backup-check/SKILL.md (o qualsiasi cartella categoria) e iterare da lì.

---
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 disclosure nella pratica

La progressive disclosure è la differenza tra una libreria skill che si sente snella e una che brucia migliaia di token prima del primo messaggio utente. Hermes percorre tre passi concettuali: un catalogo compatto (nomi e descrizioni brevi), il SKILL.md completo quando il task corrisponde, e—solo se necessario—una slice di un file reference tramite percorsi skill_view. Assumi che il livello zero sia tutto ciò che il modello leggerà finché non si impegna esplicitamente; ogni frase nella description e nella prima schermata del corpo testo dovrebbe aiutare il routing, non storytelling.

Un outline pratico che sopravvive ai carichi parziali è When to use (trigger in linguaggio semplice), Quick reference (comandi, env vars, percorsi file), Procedure (passi ordinati che l’agente non dovrebbe improvvisare via), Pitfalls (failure mode noti) e Verification (come appare “green”). Storia narrativa, dump changelog vendor e tabelle di opzioni da venti righe appartengono in references/ con heading stabili così l’agente può tirare una singola sezione.

Quando una skill si attiva, Hermes può riscrivere ${HERMES_SKILL_DIR} e ${HERMES_SESSION_ID} nel corpo così le linee shell puntano alla cartella installata senza percorsi costruiti a mano. Snippet inline shell opzionali (!cmd``) possono iniettare contesto fresco (branch corrente, spazio disco libero), ma eseguono sull’host e restano disabilitati finché skills.inline_shell non è on—tratta quel flag come un trust boundary per l’intera sorgente skill, non un toggle di convenienza.

Attivazione condizionale e igiene del prompt

Le skills possono mostrarsi o nascondersi in base a quali toolset o tool esistono nella sessione corrente. requires_toolsets / requires_tools gateano una skill dietro capacità che devono essere presenti; fallback_for_toolsets / fallback_for_tools mettono in superficie un percorso più economico o locale quando un’integrazione premium è assente—il fallback DuckDuckGo quando un’API web search pagata non è configurata è l’esempio canonico.

Questi predicati modellano direttamente il prompt noise. Una regola requires_* troppo stretta nasconde una skill da nuovi utenti che non hanno finito la configurazione hermes tools; una regola fallback_for_* troppo lasca duplica metà della tua libreria ogni volta che qualcuno omette un API key. Il terreno utile intermedio è nominare prerequisiti reali, testare con hermes chat --toolsets skills e toggleare chiavi o toolset intenzionalmente mentre si osserva se la lista skill respira come ci si aspetta.

Secreti, config e file credential

I secreti dovrebbero essere dichiarati in required_environment_variables. Hermes può promptare quando una skill si carica nel CLI locale, persistere valori in .env e passarli nei sandbox terminal e execute_code senza streamare il segreto grezzo indietro nella trascrizione del modello. Le superfici chat remote rifiutano di raccogliere chiavi inline e invece indirizzano le persone a hermes setup o edizioni manuali di .env—autori il testo della tua skill così che corrisponda a quel comportamento (dichiara agli utenti che una chiave è richiesta, non *di incollarla in Telegram).

Le preferenze non segrete—percorsi default, nomi org, feature toggle—appartengono in metadata.hermes.config. I valori si risolvono in skills.config dentro config.yaml, appaiono in hermes config show e arrivano nel messaggio skill come fatti risolti così il modello non ha bisogno di aprire il tuo file config a metà task.

I credential file-shaped (JSON token OAuth, chiavi service account) mappano a required_credential_files. Quando quei file esistono, Hermes può bind-mountarli in Docker o sincronizzarli nei job Modal; dichiararli upfront evita il classico divario “script funziona localmente, muore nel sandbox”.

Script di supporto e dipendenze

La guida upstream spinge gli autori verso dipendenze noiose: stdlib Python, curl e i tool stessi di Hermes (web_extract, read_file, terminal). Questo è meno questione di purezza che di riproducibilità—ogni extra pip install è un altro fallimento silenzioso quando l’agente esegue in un container pulito.

Quando il parsing JSON o XML è faticoso, uno script breve sotto scripts/ più un percorso ${HERMES_SKILL_DIR} batte chiedere al modello di re-derivare parser ogni run. Se hai davvero bisogno di un pacchetto, dichiara il comando install in Procedure, ripeti il sintomo del fallimento in Pitfalls e dai un comando Verification che fallisce rumorosamente quando la dipendenza è mancante.

Publishing, installazioni hub e trust

Le skills community si muovono attraverso il Skills Hub e gli altri percorsi discovery elencati nella user guide—skills ufficiali opzionali, slug GitHub, entry skills.sh, indici .well-known e URL grezzi SKILL.md. Le installazioni sono scansionate per evidenti esfiltrazione, iniezione e pattern distruttivi; i trust tier corrono da builtin attraverso community, e alcuni findings si chiariscono solo con --force mentre i casi peggiori restano bloccati interamente.

La forma del file SKILL.md non è specifica Hermes; assistenti IDE-centrici usano la stessa idea di progressive-loading con discovery e trigger diversi. Claude Skills and SKILL.md for Developers: VS Code, JetBrains, Cursor è una lettura di contrasto utile—la disciplina frontmatter e “carica solo quando rilevante” si trasferiscono, anche quando installer e cablaggio slash-command differiscono.

I rollouts org-wide di solito appaiano un tap privato o repo Git condivisa con external_dirs per sharing read-only, mantenendo la copia agente-writable sotto ogni profilo quando skill_manage è permesso di mutare skills in place.

Troubleshooting e ottimizzazione

Quando una skill si comporta male, percorri questa checklist prima di riscrivere prosa.

• Visibilità — Conferma predicati platforms, requires_* e fallback_for_*. Una skill che “funziona sul mio Mac” ma non in CI Linux è spesso un guard piattaforma.
• Collisioni nomi — Nomi duplicati attraverso directory locali ed esterne seguono precedenza locale. Rinomina o namespazia aggressivamente.
• Layout discovery — Un SKILL.md mal posizionato o cartella categoria sbagliata può far cadere la skill dall’indice interamente.
• Carico token — Se le sessioni si sentono lente, accorcia descrizioni livello-zero, sposta profondità in references/ e deduplica tabelle enormi.
• Edizioni agente — Hermes può creare, patchare o cancellare skills tramite skill_manage. Tratta skills preziose come codice: review diff, esporta snapshot e resetta skills bundled deliberatamente quando gli upgrade driftano.

Un loop di regressione stretto batte rileggere l’intero file: hermes chat --toolsets skills -q "Use the <skill> workflow to <concrete task>" dovrebbe mostrare l’agente che tira il livello disclosure giusto prima di freestyleare. Se non invoca mai skill_view, il tuo testo When to use o la description probabilmente non corrispondono a come le persone formulano richieste.

I riferimenti ufficiali restano autorevoli per cambiamenti di comportamento—la user guide Skills System per semantica runtime, Creating Skills per regole author-facing, il Bundled Skills Catalog per esempi copy-paste e la agentskills.io specification per il formato file condiviso con cui Hermes si allinea.