Creazione di competenze per l'agente Hermes — Struttura e migliori pratiche di SKILL.md

Hermes Agent tratta le skills (abilità) come il metodo predefinito per insegnare flussi di lavoro ripetibili. La documentazione ufficiale le descrive come documenti di conoscenza on-demand allineati allo shape open di agentskills.io, caricati tramite progressive disclosure (rivelazione progressiva) in modo che il modello visualizzi prima un piccolo indice e recuperi le istruzioni complete solo quando un compito le richiede effettivamente.

La creazione di skills riguarda meno la scelta delle parole e più il packaging: stai dicendo al runtime quando caricare una procedura, quale sequenza di passaggi costituisce il completamento (“done”) e come distinguere un successo da un fallimento silente. Questo articolo si concentra sulla struttura di SKILL.md, sulle cartelle di supporto, sulle regole di visibilità e sulla separazione tra impostazioni segrete e non segrete: i dettagli che decidono se una skill appare nei comandi /slash, sopravvive a un’installazione via hub o scompare silenziosamente su CI.

Hermes si inserisce nel più ampio cluster AI Systems: Self-Hosted Assistants, RAG, and Local Infrastructure (Sistemi AI: Assistenti Self-Hosted, RAG e Infrastruttura Locale), dove gli assistenti sono trattati come sistemi costruiti su inferenza, recupero, memoria e tooling, piuttosto che come un semplice interfaccia di chat. I percorsi di installazione, la configurazione dei provider, il comportamento del gateway e la struttura di ~/.hermes sono dettagliati nella guida Hermes AI Assistant - Install, Setup, Workflow, and Troubleshooting (Installazione, Configurazione, Flusso di Lavoro e Troubleshooting dell’Assistente AI Hermes); le ergonomie della shell quotidiana—hermes skills, profili, gateway, memoria—sono più facili da consultare nel Hermes Agent CLI cheat sheet — commands, flags, and slash shortcuts (Guida rapida CLI Hermes Agent — comandi, flag e scorciatoie slash). Nelle distribuzioni reali, le skills ereditano l’isolamento dai profili (configurazione, segreti, memorie e alberi di skills separati). Hermes AI Assistant Skills for Real Production Setups (Skills dell’Assistente AI Hermes per Ambienti di Produzione Reali) sostiene di trattare quei profili—non i singoli file markdown—come l’unità di proprietà; tieni questo aspetto in mente quando nomini le skills e decidi cosa appartiene alle external_dirs condivise rispetto a un singolo profilo.

Skill o tool?

Le linee guida ufficiali sono dirette. Usa una skill quando la capacità si basa principalmente su istruzioni testuali più comandi shell e tool già esposti da Hermes—avvolgere un CLI, guidare git, chiamare curl o utilizzare web_extract per fetch strutturati. Usa un tool quando hai bisogno di un’integrazione stretta per chiavi API e flussi di autenticazione, gestione deterministica di binari, streaming o Python che deve eseguire nello stesso modo ogni volta.

Questo confine è importante nella pratica perché le skills vengono distribuite senza modificare il codice dell’agente, mentre i tools comportano un overhead di revisione e rilascio. La maggior parte dei team trae vantaggio dall’iniziare con una skill, per poi promuovere solo il nucleo fragile a tool una volta che le modalità di fallimento sono evidenti (loop di refresh dell’autenticazione, parser binari, idempotenza stretta).

Procedure versus memoria curata

Le skills rispondono al come eseguire un flusso di lavoro; la memoria centrale limitata di Hermes risponde al cosa è già stato concordato riguardo all’utente e al progetto. Una skill si carica quando il compito corrisponde alla sua descrizione; MEMORY.md e USER.md rimangono nel prompt come un piccolo livello di fatti curati. I due meccanismi si sovrappongono anziché competere, e il quadro completo di snapshot, limiti e provider esterni è delineato in Hermes Agent Memory System: How Persistent AI Memory Actually Works (Sistema di Memoria Hermes Agent: Come Funziona Realmente la Memoria AI Persistente).

Anatomia di una directory skill

Sul disco, ogni skill è una cartella sotto ~/.hermes/skills/, spesso annidata 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 espanderebbero. Il pattern usuale è references/ per tabelle lunghe o documenti vendor, templates/ per scheletri di output, scripts/ per helper deterministici e assets/ per file statici che l’agente non dovrebbe re-fetchare.

Questo layout rispecchia come funziona la rivelazione progressiva nella pratica: l’agente può rimanere sul file principale fino a quando non ha davvero bisogno di un appendice profonda. Tenere il testo del “percorso felice” in SKILL.md e spostare i dettagli raramente usati in references/ è uno dei modi più economici per proteggere il budget dei token.

Hermes può anche unire directory di skill esterne tramite skills.external_dirs in config.yaml. Questi percorsi sono scansionati per la scoperta, ma l’agente scrive ancora attraverso skill_manage nell’albero principale ~/.hermes/skills/. I nomi locali oscurano quelli esterni, quindi se “correggi” 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 del tipo “funziona sul mio computer”.

Frontmatter SKILL.md che sopravvive alla revisione

Il corpo di SKILL.md è Markdown; il blocco iniziale deve essere YAML valido tra delimitatori ---. Le skill reali accumulano lunghi esempi con fence, quindi le piccole abitudini da Markdown Code Blocks: Complete Guide with Syntax, Languages & Examples (Blocchi di Codice Markdown: Guida Completa con Sintassi, Lingue & Esempi)—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 rotta slash e la chiave dell’indice; rimane in minuscolo con trattini e deve rispettare il limite di lunghezza documentato. Il description è l’unica prosa per cui molte sessioni pagano al livello zero, quindi dovrebbe leggere come un risultato di ricerca o una stringa di routing (“quando i backup sembrano obsoleti, verifica l’archivio più recente e il checksum”), non come il primo paragrafo di un post di blog.

Le chiavi di livello opzionali come version, author e license aiutano nel packaging del hub e nelle audit. La lista platforms (macos, linux, windows) è più tagliente di quanto sembri—quando impostata, Hermes omette la skill interamente su host non corrispondenti, ecco perché una skill che “funziona sul mio Mac” può scomparire in CI Linux senza alcun messaggio di errore oltre a una lista di skills più corta.

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

I documenti ufficiali enfatizzano la disciplina delle dimensioni per un motivo. Riduci il description al suo budget, anteposiziona la procedura e sposta le note storiche o le enormi matrici di opzioni in references/ in modo che una skill_view parziale dia ancora all’agente qualcosa di azionabile.

Di seguito è riportato un SKILL.md minimale che puoi inserire in ~/.hermes/skills/devops/backup-check/SKILL.md (o in qualsiasi cartella di 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.

Rivelazione progressiva nella pratica

La rivelazione progressiva è la differenza tra una libreria di skills che sembra reattiva e una che brucia migliaia di token prima del primo messaggio dell’utente. Hermes esegue tre passaggi concettuali: un catalogo compatto (nomi e brevi descrizioni), l’intero SKILL.md quando il compito corrisponde, e—solo se necessario—una fetta di un file di riferimento tramite percorsi skill_view. Assumi che il livello zero sia tutto ciò che il modello leggerà fino a quando non si impegna esplicitamente; ogni frase nella description e nella prima schermata del testo del corpo dovrebbe aiutare il routing, non la narrazione.

Un’outline pratica che sopravvive ai carichi parziali è When to use (trigger in linguaggio semplice), Quick reference (comandi, variabili d’ambiente, percorsi file), Procedure (passaggi ordinati che l’agente non dovrebbe improvvisare via), Pitfalls (modalità di fallimento note) e Verification (com’è un risultato “verde”). La storia narrativa, gli dump del changelog del vendor e le tabelle di opzioni di venti righe appartengono in references/ con intestazioni stabili in modo che l’agente possa recuperare una singola sezione.

Quando una skill si attiva, Hermes può riscrivere ${HERMES_SKILL_DIR} e ${HERMES_SESSION_ID} nel corpo in modo che le righe shell puntino alla cartella installata senza percorsi costruiti a mano. Snippet inline shell opzionali (!cmd``) possono iniettare contesto fresco (ramo corrente, spazio libero su disco), ma vengono eseguiti sull’host e rimangono disabilitati a meno che skills.inline_shell non sia attivo—tratta quel flag come un confine di fiducia per l’intera sorgente della skill, non come un interruttore di comodità.

Attivazione condizionale e igiene del prompt

Le skills possono mostrare o nascondersi in base a quali toolsets o tools esistono nella sessione corrente. requires_toolsets / requires_tools bloccano una skill dietro capacità che devono essere presenti; fallback_for_toolsets / fallback_for_tools mostrano un percorso più economico o locale quando un’integrazione premium è assente—il fallback DuckDuckGo quando un’API di ricerca web a pagamento non è configurata è l’esempio canonico.

Questi predicati modellano direttamente il rumore del prompt. Una regola requires_* eccessivamente rigorosa nasconde una skill ai nuovi utenti che non hanno ancora completato la configurazione di hermes tools; una regola fallback_for_* eccessivamente lasca duplica metà della tua libreria ogni volta che qualcuno omette una chiave API. La via di mezzo utile è nominare prerequisiti reali, testare con hermes chat --toolsets skills e alternare chiavi o toolsets intenzionalmente osservando se la lista delle skills respira nel modo in cui ti aspetti.

Segreti, config e file di credenziali

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

Le preferenze non segrete—percorsi predefiniti, nomi di organizzazione, toggle delle funzionalità—appartengono in metadata.hermes.config. I valori si risolvono in skills.config dentro config.yaml, appaiono in hermes config show e arrivano nel messaggio della skill come fatti risolti in modo che il modello non abbia bisogno di aprire il tuo file di config a metà del compito.

Le credenziali a forma di file (JSON token OAuth, chiavi service account) mappano a required_credential_files. Quando quei file esistono, Hermes può bind-montarli in Docker o sincronizzarli nei job Modal; dichiararli in anticipo evita il classico divario “lo script funziona localmente, muore nel sandbox”.

Script di supporto e dipendenze

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

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

Pubblicazione, installazioni hub e fiducia

Le skills della comunità si muovono attraverso il Skills Hub e gli altri percorsi di scoperta elencati nella guida utente—skills ufficiali opzionali, slug GitHub, voci skills.sh, indici .well-known e URL SKILL.md raw. Le installazioni sono scansionate per evidenti esfiltrazioni, iniezioni e pattern distruttivi; i livelli di fiducia vanno da builtin attraverso community, e alcuni risultati si chiariscono solo con --force mentre i casi peggiori restano bloccati interamente.

La forma del file SKILL.md non è specifica di Hermes; gli assistenti centrati sull’IDE usano la stessa idea di caricamento progressivo con scoperta e trigger diversi. Claude Skills and SKILL.md for Developers: VS Code, JetBrains, Cursor è una lettura di contrasto utile—la disciplina del frontmatter e “carica solo quando rilevante” si trasportano, anche quando l’installatore e il cablaggio dei comandi slash differiscono.

Le rollout a livello di organizzazione solitamente accoppiano un tap privato o repo Git condivisa con external_dirs per la condivisione in sola lettura, mantenendo la copia scrivibile dall’agente sotto ciascun profilo quando skill_manage è autorizzato a mutare le skills in loco.

Troubleshooting e ottimizzazione

Quando una skill si comporta male, segui questa checklist prima di riscrivere il testo.

• Visibilità — Conferma i predicati platforms, requires_* e fallback_for_*. Una skill che “funziona sul mio Mac” ma non in CI Linux è spesso un guardiano di piattaforma.
• Collisioni di nome — I nomi duplicati tra directory locali ed esterne seguono la precedenza locale. Rinomina o usa namespace in modo aggressivo.
• Layout di scoperta — Un SKILL.md fuori posto o una cartella di categoria errata può far cadere la skill dall’indicizzazione interamente.
• Carico token — Se le sessioni sembrano lente, accorcia le descrizioni a livello zero, sposta la profondità in references/ e deduplica le tabelle giganti.
• Modifiche dell’agente — Hermes può creare, patchare o eliminare skills tramite skill_manage. Tratta le skills preziose come codice: revisiona i diff, esporta snapshot e resetta le skills bundled deliberatamente quando gli aggiornamenti divergono.

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

I riferimenti ufficiali restano autorevoli per i cambiamenti di comportamento—la Skills System user guide per le semantiche runtime, Creating Skills per le regole rivolte agli autori, il Bundled Skills Catalog per esempi da copiare-incollare e la agentskills.io specification per il formato file condiviso con cui Hermes si allinea.