Volevo aggiungere una funzionalità a OpenClaw che non esisteva: un digest di Hacker News che riassume le migliori storie ogni mattina e le pubblica sul mio Slack. Nulla di simile esisteva come competenza. Quindi, ne ho costruita una.
La prima volta ci sono volute quattro ore, di cui due ore a leggere male la specifica della competenza. La seconda competenza che ho costruito ha impiegato 45 minuti. Alla quinta, riuscivo a realizzarne una in 30 minuti. Ecco il processo, ripulito da tutti gli errori che ho fatto nel frattempo.
Cos’è realmente una competenza
Una competenza è una cartella con istruzioni e script opzionali. Al minimo, contiene un file SKILL.md — un documento in markdown che indica a OpenClaw cosa fa la competenza, quando attivarla e come usarla.
È davvero tutto. Nada compilazione. Nada registro dei pacchetti. Nada sistema di costruzione. Una competenza è un documento che OpenClaw legge quando deve eseguire un compito specifico.
La competenza più semplice possibile:
Una cartella chiamata daily-hn-digest contenente un solo file, SKILL.md, con istruzioni come: « Quando l’utente richiede un digest di Hacker News, usa lo strumento web_search per trovare le notizie più importanti su Hacker News, riassumi ciascuna in 2-3 frasi e formatta il risultato sotto forma di elenco puntato. »
Funziona. L’agente legge le istruzioni, le segue e produce un digest di Hacker News. Nessun codice necessario.
Aggiungere complessità quando ne hai bisogno
La competenza di base gestisce casi semplici. Per flussi di lavoro più complessi, aggiungi:
File di riferimento. La mia competenza di Hacker News include una cartella refs/ con esempi di output — mostrando all’agente come appare un buon digest. Questo migliora notevolmente la coerenza. Invece di « riassumere le storie », l’agente vede « ecco come appare un buon riassunto — segui questo formato. »
Script. Alcune competenze includono script shell o script Python per compiti che l’IA non può svolgere direttamente. La mia competenza di digest include uno script che recupera l’API di Hacker News (più veloce e affidabile dello scraping web). Le istruzioni della competenza dicono all’agente di eseguire lo script e di elaborare il suo output.
Configurazione. Le competenze possono leggere da file di configurazione. La mia competenza di digest ha un config.yaml che specifica quanti racconti includere (di default: 10), quali categorie dare priorità e il formato di output (Slack, email o testo semplice).
La struttura che funziona
Dopo aver costruito una dozzina di competenze, ecco la struttura di cartelle su cui mi sono fermato:
my-skill/
├── SKILL.md — Istruzioni principali (obbligatorie)
├── refs/ — Esempi di input e output (opzionali)
├── scripts/ — Script di supporto (opzionali)
└── config.yaml — Configurazione (opzionale)
SKILL.md è il file più importante. Deve includere:
1. Una descrizione chiara di cosa fa la competenza
2. Quando la competenza deve attivarsi (condizioni per l’attivazione)
3. Istruzioni passo passo per il flusso di lavoro
4. Guida alla gestione degli errori
5. Esempi di buona output
La qualità del tuo SKILL.md determina direttamente la qualità della competenza. Un SKILL.md vago produce risultati incoerenti. Un SKILL.md preciso produce risultati affidabili.
Scrivere buone istruzioni
La lezione più grande che ho imparato: scrivi SKILL.md come se stessi formando un nuovo dipendente, non come se stessi scrivendo documentazione.
Cattivo: « Recupera le storie di Hacker News e riassumile. »
Buono: « Recupera le 10 migliori storie dall’API Hacker News utilizzando lo script a scripts/fetch-hn.sh. Per ogni storia, scrivi un riassunto di 2-3 frasi che copra: cosa è successo, perché è importante e la reazione della comunità (se notevole). Formatta come un elenco numerato con il titolo della storia come link. »
La versione buona elimina l’ambiguità. L’agente sa esattamente cosa fare, quale formato utilizzare e quali informazioni includere. Non c’è spazio per un’interpretazione creativa dove non la desideri.
Includere modalità di fallimento. « Se l’API di Hacker News è irraggiungibile, usa web_search come soluzione di riserva. Se ci sono meno di 5 storie disponibili, annotalo nell’output e prosegui con ciò che è disponibile. Non inventare storie. »
Includere limiti. « Non fare commenti. Non aggiungere opinioni sulle storie. Non saltare storie perché sembrano poco importanti. Presenta tutte le principali storie in modo neutro. »
Testare la tua competenza
Il processo di test è semplice: installa la competenza, attivala e verifica l’output.
Per la mia competenza di Hacker News:
1. Copia la cartella nella directory delle competenze
2. Riavvia OpenClaw (o aspetta che rilevi la nuova competenza)
3. Digita « Dammi un digest di Hacker News »
4. Controlla l’output rispetto alle aspettative
5. Regola SKILL.md in base a ciò che non ha funzionato
Di solito percorro 3-4 cicli di revisioni prima di essere soddisfatto. Problemi comuni: l’agente salta passaggi (aggiungere istruzioni più esplicite), formattazione incoerente (aggiungere un esempio di output) o includere informazioni che non volevi (aggiungere limiti espliciti).
Pubblicazione e condivisione
Una volta che la tua competenza funziona, puoi condividerla tramite ClawHub — il mercato comunitario delle competenze. Carica la tua cartella di competenza, aggiungi una descrizione e altri utenti possono installarla con un solo comando.
Prima di pubblicare, pulisci la tua competenza: rimuovi qualsiasi configurazione personale, aggiungi un README con istruzioni di configurazione e testala su un’installazione fresca di OpenClaw per assicurarti che non dipenda dal tuo ambiente locale.
Le migliori competenze comunitarie sono mirate (fanno bene una cosa), ben documentate (SKILL.md chiaro) e solide (gestiscono i fallimenti con calma). Le peggiori sono vaghe (« usa l’IA per fare cose »), mal documentate, o fragili.
Le mie competenze personalizzate preferite
Oltre al digest di Hacker News, ecco le competenze personalizzate che utilizzo quotidianamente:
Preparazione della riunione. Prima di una riunione, dico « prepara la mia riunione alle 14:00 con [cliente]. » La competenza recupera le email recenti, gli aggiornamenti di progetto e i problemi in corso relativi a quel cliente e compila un briefing di una pagina.
Assistente di revisione del codice. Quando carico codice, la competenza lo esamina secondo gli standard di codifica del nostro team (documentati in un file di riferimento) e pubblica commenti nel nostro canale di team.
Generatore di retro settimana. Ogni venerdì, la competenza compila ciò che ho realizzato questa settimana (dai commit di GitHub, dai messaggi Slack e dalle attività completate) e scrive un riepilogo settimanale.
Ciascuna di queste competenze ha richiesto circa un’ora per essere costruita. Ognuna fa risparmiare 15-30 minuti per utilizzo. Il ritorno sull’investimento è evidente.
🕒 Published: