Creare skill per agenti IA per flussi di lavoro aziendali specifici di dominio

Un agente IA generalista per lo sviluppo software sa svolgere con competenza una gamma sorprendentemente ampia di attività. Legge la documentazione, scrive codice, diagnostica errori e affronta problemi nuovi se dispone di un contesto sufficiente. Ma la maggior parte dei team che impiegano questi agenti in ambienti operativi reali incontra lo stesso ostacolo: fornire quel contesto è già di per sé un’attività, che cresce con la complessità del dominio.

Un analista che chiede all’agente di estrarre i tempi di consegna dei fornitori da una cartella di ordini di acquisto in formati diversi non vuole spiegare ogni volta che cos’è un ordine di acquisto, come funzionano le convenzioni di denominazione aziendali e quale formato di output si aspettano i sistemi a valle. Uno sviluppatore che si occupa del monitoraggio dell’infrastruttura non vuole incollare le stesse soglie di allerta e definizioni di gravità in ogni conversazione. Il problema è la ripetizione.

Le skill, configurazioni riutilizzabili che racchiudono conoscenze di dominio e istruzioni di comportamento in un’unica unità richiamabile, rispondono direttamente a questo problema. Questo articolo descrive come costruirle, come impiegarle nei flussi di lavoro ricorrenti e in quali ambiti offrono valore in modo affidabile.

Che cos’è davvero una skill

Una skill non è una funzionalità del modello né una capacità dell’API. È un file, più precisamente un file Markdown inserito in una directory che l’agente esamina all’avvio della sessione (in Claude Code, per esempio, un file SKILL.md in una cartella sotto ~/.claude/skills/ o sotto .claude/skills/ nel progetto; gli altri ambienti di esecuzione degli agenti usano percorsi propri). Quando incontra una richiesta che corrisponde alla descrizione della skill, l’agente ne carica e segue le istruzioni, anziché ragionare da zero su come affrontare l’attività.

Il file contiene quattro elementi: un blocco descrittivo che indica all’agente quando attivare la skill; un insieme di istruzioni su come gestire quella categoria di attività; eventuali dichiarazioni di accesso agli strumenti che, a seconda dell’ambiente di esecuzione, autorizzano preventivamente o limitano gli strumenti che l’agente può usare durante l’esecuzione (in Claude Code, allowed-tools autorizza preventivamente gli strumenti senza limitare gli altri); ed eventuali esempi che mostrano il comportamento corretto con input realistici.

Il file non contiene dati aziendali incorporati direttamente nelle istruzioni. Una skill codifica come affrontare una categoria di attività, cioè il vocabolario del dominio, il metodo di ragionamento e il formato dell’output, non le attività stesse. La distinzione tra codificare l’approccio e codificare i dati è la questione centrale nella progettazione di skill che restino utili nel tempo.

Quando codificare le conoscenze di dominio e quando evitarlo

La maggior parte delle implementazioni di skill che falliscono codifica troppe informazioni. Entusiasti del concetto, i team scrivono skill che includono nomi di fornitori specifici, fasce di prezzo attuali, il formato di report preferito da un cliente e gli esatti endpoint API in uso oggi. Sei mesi dopo, metà delle informazioni è sbagliata, la skill non rispecchia più la realtà e nessuno sa di quali parti fidarsi.

La regola pratica: codifica ciò che cambia lentamente e lascia all’agente ciò che cambia spesso.

Il vocabolario di un dominio cambia lentamente. Una skill per elaborare la documentazione di importazione dovrebbe sapere che cos’è un certificato di origine, che cosa significa il metodo deduttivo nella determinazione del valore in dogana e quale quadro normativo si applica al mercato di destinazione. Questa conoscenza cambia molto più lentamente dei dettagli operativi, anche se i quadri normativi vengono modificati e richiedono comunque revisioni periodiche. Va inclusa nella skill.

I formati specifici di presentazione dei documenti, i nomi delle controparti, le soglie normative vigenti e le scadenze esatte cambiano continuamente. Devono far parte dei dati ricevuti dall’agente durante l’esecuzione, non della definizione della skill. La skill insegna all’agente come leggere una categoria di documenti. Il documento concreto arriva come contesto.

Un criterio utile: se occorre aggiornare la skill ogni volta che cambia qualcosa nell’ambiente aziendale, contiene le informazioni sbagliate. Le skill ben progettate resistono ai cambiamenti organizzativi. Quelle progettate male diventano obsolete quasi subito.

La struttura di SKILL.md

La struttura canonica del file di una skill è semplice. Un blocco di metadati iniziale, o frontmatter, identifica la skill e definisce quando attivarla; il corpo spiega come usarla.

---
name: import-document-processor
description: Use when processing import declarations, ACP applications,
  or customs documentation for Singapore, Japan, or EU markets
---

## Context
Background on the domain: what this class of documents is, why it
exists, what the agent needs to know to interpret one intelligently.

## Approach
Step-by-step instructions for handling the task: what to look for,
how to handle ambiguous cases, what to escalate to human review.

## Output Format
Exactly what the output should contain, in what structure.

## Edge Cases
Known failure modes and how to handle them.

Dal punto di vista operativo, il blocco descrittivo è la parte più importante. Determina se l’agente attiva la skill. Una descrizione vaga, come «usare per i documenti», produce attivazioni irregolari. Una descrizione precisa, che indica tipi di documenti, contesti aziendali e mercati pertinenti, produce un comportamento affidabile.

La descrizione, però, non deve essere troppo restrittiva. Se è troppo specifica, l’agente non riconosce richieste pertinenti. L’obiettivo è una descrizione nella quale un professionista attento riconosca la propria situazione, senza eccessi né lacune. Serve una calibrazione sul campo; durante la prima distribuzione conviene testare i casi limite per verificare che i criteri di attivazione corrispondano alle aspettative.

Il modello /loop per le attività ricorrenti

Alcuni flussi di lavoro aziendali seguono una pianificazione: estrazione giornaliera da un endpoint API, aggregazione settimanale dei report dei fornitori, generazione mensile di riepiloghi per i clienti. Non sono interazioni isolate, ma processi operativi che proseguono indipendentemente dal fatto che qualcuno li avvii manualmente.

In Claude Code, il comando /loop trasforma un’interazione basata su una skill in un’operazione ricorrente:

/loop 24h /process-supplier-reports

Il comando esegue nuovamente la skill indicata all’intervallo specificato all’interno della sessione corrente, che fornisce il contesto a ogni invocazione. La skill gestisce il lavoro; il ciclo gestisce la pianificazione. A ottobre 2026, la documentazione di Claude Code descrive /loop come limitato alla sessione: le attività si attivano solo mentre la sessione è in esecuzione e le attività ricorrenti scadono dopo sette giorni. Le pianificazioni durature in produzione vanno quindi affidate a un job cron, una pipeline CI o un’attività pianificata nel cloud che richiami la stessa skill.

Le skill ricorrenti richiedono accorgimenti progettuali diversi da quelle interattive. Devono essere idempotenti: eseguire due volte la stessa skill sullo stesso input non deve creare record duplicati, inviare notifiche duplicate o corrompere lo stato dei sistemi a valle. Devono prevedere un comportamento esplicito in caso di errore, definendo chiaramente che cosa succede quando l’input è malformato, un’API non è disponibile o mancano dati attesi. Se i sistemi a valle ne utilizzano l’output, questo deve essere leggibile dalle macchine, non solo dalle persone.

Le skill che funzionano in modo affidabile in un ciclo hanno quasi sempre un ambito più ristretto di quelle interattive. Una skill interattiva può gestire bene cinque tipi diversi di documenti, con un degrado accettabile per quelli sconosciuti. La variante ciclica gestisce con precisione un solo tipo di documento e segnala esplicitamente un errore per qualsiasi input inatteso. L’affidabilità operativa privilegia la specificità rispetto alla flessibilità.

Un criterio pratico: se non riesci a descrivere l’intero comportamento atteso della skill, compresi i casi di errore, in meno di dieci minuti, probabilmente il suo ambito è troppo ampio per un’esecuzione pianificata affidabile.

Esempi pratici dalla produzione

Tre modelli che abbiamo utilizzato in ambienti operativi reali:

Estrazione dei dati dalle comunicazioni dei fornitori. I fornitori inviano conferme d’ordine, notifiche di spedizione e aggiornamenti delle fatture in formati incoerenti, a volte strutturati, spesso no. Una skill configurata per lo stile di comunicazione di ciascun fornitore estrae dati strutturati da testo non strutturato. Sa che un determinato fornitore inserisce il riferimento all’ordine di acquisto nel secondo paragrafo dell’email di conferma, che il formato delle date è DD.MM.YYYY e che i codici prodotto seguono uno schema specifico. Il contenuto delle email cambia ogni settimana; il metodo di analisi resta stabile. L’output estratto alimenta direttamente i sistemi di gestione delle scorte, senza interventi manuali tra la ricezione del messaggio e l’inserimento dei dati.

Generazione di report dai dati operativi. Per produrre un riepilogo operativo settimanale occorre sapere quali metriche contano, quali soglie sono significative, quali confronti tra periodi sono utili e come presentare i risultati a un pubblico specifico. Questi elementi non cambiano di settimana in settimana. Una skill li codifica una volta sola. Durante l’esecuzione, l’agente riceve i dati attuali e applica il quadro di analisi configurato. Il formato dell’output, il registro linguistico e le sezioni che devono sempre comparire sono definiti nella skill, senza doverli specificare ogni volta. Il risultato è una coerenza che i prompt manuali raramente raggiungono su larga scala.

Monitoraggio dei sistemi e gestione degli avvisi. L’infrastruttura genera log continuamente. Le skill di monitoraggio definiscono quali schemi costituiscono un evento rilevante, come classificarne la gravità e quali informazioni servono a una persona per intervenire efficacemente. Abbinate al modello ciclico ed eseguite a intervalli brevi, verificano le condizioni definite e generano avvisi strutturati quando tali condizioni si verificano.

L’aspetto progettuale centrale è la gestione dei falsi positivi. Una skill che segnala ogni anomalia abitua gli operatori a ignorare gli avvisi. Il vero lavoro è la calibrazione: definire con precisione quando un avviso merita l’attenzione di una persona. Non è un problema tecnico, ma di conoscenza del dominio. Per risolverlo servono indicazioni dettagliate da chi oggi gestisce manualmente i problemi, perché ha già imparato a distinguere le segnalazioni utili dal rumore. La skill formalizza questa conoscenza.

Che cosa non risolvono le skill

Le skill codificano competenze in domini specifici. Non creano capacità generali.

Una skill ben configurata gestisce in modo affidabile schemi noti. Non affronta altrettanto bene situazioni del tutto nuove, perché le istruzioni che la rendono affidabile nei contesti familiari ne limitano il comportamento in quelli sconosciuti. In pratica, le skill funzionano meglio quando l’ambito delle attività è sufficientemente delimitato: documentazione di importazione da mercati specifici, generazione di report per un insieme definito di metriche, analisi dei log rispetto a schemi di allerta noti. «Aiutare nelle operazioni aziendali» non è un ambito delimitato. Le skill non possono rendere competente un agente in domini nei quali nessuno ha investito per definire che cosa significhi essere competente.

L’altro limite è la manutenzione. Le skill che codificano conoscenze di dominio richiedono aggiornamenti quando queste cambiano: non a ogni cambiamento, perché quelle ben progettate evitano le informazioni volatili, ma alcuni aggiornamenti sono inevitabili. Mantenerle attuali richiede la stessa disciplina necessaria per la documentazione. Le organizzazioni che non vi investono scoprono gradualmente che le skill non rispecchiano più la realtà. Il malfunzionamento è silenzioso: la skill continua a essere eseguita e a produrre output, ma i risultati sono imprecisi in modi difficili da rilevare subito.

Le organizzazioni che ricavano più valore dalle skill investono sia nella configurazione iniziale sia nella calibrazione continua. L’investimento iniziale è inferiore a quanto molti si aspettano. L’impegno di manutenzione è maggiore di quanto molti pianifichino: prevederlo con realismo distingue le skill che restano utili da quelle che diventano una fonte di errori silenziosi.

Approfondimenti correlati

• Claude Skills: la risposta di Anthropic al problema della personalizzazione dell’IA – Come è progettato il sistema di skill di Anthropic e quale problema organizzativo risolve
• Creare un assistente IA locale con ricerca web: configurazione di MCP + Ollama – Configurazione pratica degli strumenti per agenti IA in un ambiente gestito sulla propria infrastruttura
• Integrazione Punchout con WooCommerce: semplificare l’approvvigionamento B2B con l’automazione intelligente – Automazione specifica di dominio applicata a un flusso di lavoro B2B strutturato