Come creare una skill personalizzata per Hermes Agent

Una skill è la più piccola unità di comportamento che puoi insegnare a Hermes Agent senza modificarne il codice sorgente. È una cartella, un file markdown e una breve intestazione YAML. La documentazione ufficiale di Nous Research descrive il formato come "portabile perché è semplice", e scrivere una skill personalizzata richiede meno di cinque minuti una volta che ne conosci la forma.

Questa guida illustra quella forma dall'inizio alla fine. Vedrai dove vivono le skill su disco, cosa deve contenere l'intestazione del SKILL.md, quali sezioni l'agente legge davvero a runtime, come collegare i segreti tramite required_environment_variables e come verificare che la skill sia stata caricata correttamente. Il risultato è una skill che puoi inserire in ~/.hermes/skills/ e usare lo stesso giorno.

Dove vivono le skill e come Hermes le trova

Hermes archivia le skill come semplici cartelle dentro ~/.hermes/skills/. Le skill incluse vengono copiate lì durante l'installazione, e qualsiasi skill personalizzata che aggiungi si registra subito al riavvio successivo. La struttura della directory è piatta:

~/.hermes/skills/
├── backup-check/
│   └── SKILL.md
├── invoice-followup/
│   └── SKILL.md
└── stripe-mrr-digest/
    ├── SKILL.md
    └── helper.py

Il nome della cartella è l'id della skill. Hermes rileva automaticamente ogni cartella all'avvio e legge ciascun SKILL.md. Il campo description nel frontmatter YAML è ciò che l'agente confronta con il tuo messaggio a runtime, quindi scrivilo per l'agente, non per un lettore umano. Se la descrizione non descrive chiaramente la condizione di attivazione, la skill non si attiverà quando te lo aspetti.

Una skill può includere file aggiuntivi nella sua cartella: un helper Python, un template SQL, un file di testo con una checklist. Hermes non li esegue automaticamente. Sono lì perché l'agente li legga o li esegua quando la procedura glielo indica.

Diagramma di tre cartelle di skill dentro ~/.hermes/skills/, ognuna contenente un file SKILL.md con frecce che puntano al processo di Hermes Agent in esecuzione

Il formato del file SKILL.md

Ogni skill è un singolo file markdown. L'intestazione YAML in alto è il blocco dei metadati, e il corpo markdown è il set di istruzioni. Ecco uno scheletro minimo che puoi copiare:

---
name: backup-check
description: Verify nightly backup archives exist, are non-empty, and pass a quick checksum spot-check on the latest file.
version: 0.1.0
author: [email protected]
required_environment_variables: []
required_credential_files: []
---

I campi che contano fin dal primo giorno:

name - corrisponde al nome della cartella. In kebab-case, senza spazi.
description - una singola frase che Hermes usa per decidere quando caricare la skill. Sii specifico sulla condizione di attivazione ("quando l'utente chiede di X", "prima di eseguire Y").
version - in formato libero, ma trattalo come semver così puoi incrementarlo man mano che il testo evolve.
required_environment_variables - un array di nomi di segreti che devono essere impostati prima che la skill possa funzionare. L'agente li richiede alla prima attivazione e li scrive nel file .env.
required_credential_files - percorsi di token OAuth o file JSON di service account che devono essere montati nel sandbox.

Campi opzionali che vale la pena conoscere: platforms (un array di macos, linux, windows se la skill funziona solo su alcuni), requires_toolsets per mostrare la skill solo quando determinati toolset sono caricati, e fallback_for_toolsets per il caso opposto. La configurazione a livello di skill vive in metadata.hermes.config e finisce sotto skills.config nel tuo config.yaml per preferenze non segrete come percorsi o impostazioni di dominio.

Le cinque sezioni che vengono davvero lette

Sotto il frontmatter, il corpo markdown è testo discorsivo. Hermes non richiede alcuna sezione specifica, ma dalla guida ufficiale "Working with Skills" e dai post di authoring su dev.to e glukhov.org è emersa una struttura in cinque parti. L'agente la premia perché ogni parte risponde a una diversa domanda a runtime.

When to Use

Un breve paragrafo che distingue questa skill dalle altre skill che l'agente potrebbe scegliere. Se hai una skill chiamata invoice-followup e un'altra chiamata client-update, "when to use" è ciò che impedisce all'agente di attivare quella sbagliata.

Quick Reference

Un elenco puntato dei comandi, dei percorsi o delle costanti da cui dipende la procedura. L'agente lo legge prima della procedura per caricare il contesto. Metti qui i tuoi percorsi dei file, il nome del tuo bucket S3, i nomi delle tue variabili d'ambiente, l'id della chat Telegram di destinazione.

Procedure

I passaggi numerati che l'agente dovrebbe seguire. Scrivili come istruzioni all'imperativo ("esegui X", "se la risposta contiene Y, fai Z"). L'agente tratta questa sezione come una ricetta e ti citerà o parafraserà i passaggi mentre li esegue.

Pitfalls

Le trappole che già conosci. Rate limit, errori silenziosi, bug di fuso orario, l'unico cliente i cui dati hanno una forma strana. L'agente le legge come barriere di sicurezza e rifiuta o avvisa quando ne riscontra le condizioni.

Verification

Come l'agente conferma di aver fatto la cosa giusta. Un grep, un curl, un checksum, un "mostrami l'ultima riga". La verifica è ciò che trasforma una skill in qualcosa che puoi lasciare in esecuzione.

Collegare segreti e credenziali

Se la tua skill comunica con un'API, dichiara il segreto in required_environment_variables:

required_environment_variables:
  - STRIPE_RESTRICTED_KEY
  - SLACK_WEBHOOK_URL

La prima volta che la skill si attiva, l'agente ti chiede ciascun valore e li scrive nel file .env del progetto. Vengono poi passati automaticamente ai sandbox (Docker, Modal, runner effimeri). Non inserire mai una chiave direttamente nel testo: l'agente la riproporrà durante l'esecuzione e brucerà il segreto in qualche log.

Per i token OAuth o i file JSON di service account, usa required_credential_files:

required_credential_files:
  - ~/.config/gcloud/application_default_credentials.json

Questi vengono montati nel sandbox come volumi di sola lettura. L'agente non li analizza; si assicura solo che siano presenti prima che la procedura venga eseguita.

Come Hermes estrae automaticamente le skill dalle conversazioni

Puoi anche lasciare che sia Hermes a scrivere le skill al posto tuo. Dopo un compito complesso che ha richiesto cinque o più chiamate a strumenti, lo strumento skill_manage cattura il pattern riuscito e scrive una skill riutilizzabile in ~/.hermes/skills/. L'agente analizza la conversazione, individua il flusso di lavoro riutilizzabile ed emette un SKILL.md con una procedura che rispecchia ciò che ha effettivamente fatto.

È lo stesso meccanismo che fa sembrare Hermes sempre più affilato nel tempo. Lo strato di memoria persistente ricorda di cosa avete parlato; le skill estratte automaticamente ricordano come ha risolto un problema. I due strati sono spiegati più in dettaglio nel nostro articolo su memoria e skill di Hermes Agent.

Le prime skill estratte automaticamente sono di solito per l'80 percento ciò che vuoi e per il 20 percento fuori bersaglio. Apri il SKILL.md, affina la descrizione, elimina i passaggi che l'agente ha eseguito solo per caso e incrementa la versione. Ora hai una skill modificata a mano che si attiva in modo affidabile.

Testare una skill dall'inizio alla fine

Una volta che il SKILL.md è al suo posto, riavvia Hermes (oppure esegui hermes skill reload se la tua build lo supporta). Poi esegui tre controlli:

Chiedi a Hermes di elencare le sue skill. La nuova skill dovrebbe comparire con il nome e la descrizione che hai scritto.
Invia un messaggio che corrisponde alla condizione di attivazione. L'agente dovrebbe annunciare che sta usando la skill prima di fare qualsiasi cosa.
Esegui manualmente il passaggio di verifica. Se la tua skill scrive un file, controlla il file. Se invia a un webhook, controlla il webhook.

Se la skill non si carica, il colpevole abituale è lo YAML. Un carattere di tabulazione di troppo o un due punti senza virgolette romperà silenziosamente il parser del frontmatter. Hermes registra un errore di parsing all'avvio; controlla lo stderr dell'agente la prima volta che ricarichi.

Scena fotorealistica del terminale di uno sviluppatore che mostra una sessione di Hermes Agent mentre carica una skill personalizzata, con un prompt verde e una luce ambientale soffusa

Salta l'impalcatura con Hermes gestito

Una skill personalizzata è un file markdown, ma eseguire Hermes stesso non lo è. Ti servono un host, una chiave di un provider di modelli, un bot Telegram o una UI web, una strategia di backup per la directory delle skill e un modo per testare le modifiche senza rompere il tuo agente attivo.

Hermify è hosting gestito per Hermes Agent che si occupa di tutto questo. La tua directory delle skill persiste tra i riavvii, le chiavi dei modelli vivono in uno storage cifrato a riposo, e puoi abbinare le skill personalizzate che scrivi qui con le integrazioni MCP che Hermes già supporta. Inizia con Hermify e la tua prima skill personalizzata può essere in esecuzione su un agente reale in meno di cinque minuti.