Come trasformare una procedura in una Skill per Claude

Una procedura diventa una buona candidata per una Skill quando ricorre, ha un ingresso riconoscibile e produce un risultato controllabile. Se ogni volta riscrivi gli stessi vincoli, gli stessi passaggi e la stessa checklist, puoi raccoglierli in un componente che Claude carica quando il compito corrisponde.

Il passaggio importante non è copiare una SOP dentro un file chiamato SKILL.md. Devi ridurre la procedura a un contratto operativo: quando si attiva, quali input accetta, che cosa produce, quali controlli esegue e in quali casi si ferma. Solo dopo puoi aggiungere esempi, risorse o script.

La guida ufficiale Anthropic indica come struttura minima una cartella con SKILL.md, frontmatter con nome e descrizione e istruzioni chiare. Esempi, file di riferimento e script possono essere aggiunti quando servono. Anthropic, custom Skills.

Prima verifica se serve davvero una Skill

Non tutto ciò che vuoi ricordare è una procedura. Una preferenza generale come “scrivi in italiano” oppure “usa kebab-case per i file” appartiene alle istruzioni persistenti del progetto. Un insieme di passaggi che si attiva soltanto quando chiedi di validare un brief è invece un candidato per una Skill.

La documentazione su memoria e istruzioni di Claude Code distingue proprio questi livelli: le regole generali possono stare in CLAUDE.md, mentre i workflow in più passaggi e con trigger specifici possono essere organizzati come Skill. Anthropic, project memory.

Usa queste domande come filtro:

• il compito ricorre con una forma abbastanza stabile?

• puoi riconoscere quando la procedura va attivata e quando no?

• gli input necessari possono essere dichiarati?

• l'output ha criteri di completezza osservabili?

• esistono casi in cui il lavoro deve fermarsi?

• la procedura può essere provata su esempi non sensibili?

Se rispondi no alle prime quattro, forse stai ancora esplorando il processo. Documenta i tentativi prima di automatizzare la forma sbagliata. Se non sai quando fermarti, la Skill rischia di rendere ripetibile proprio l'ambiguità che volevi eliminare.

Riduci la procedura a un contratto operativo

Prendi la SOP e separa quattro elementi: trigger, input, output e stop. Non iniziare dai passaggi numerati, perché una procedura lunga può nascondere che mancano i materiali essenziali.

Questo contratto non descrive ancora ogni scelta. Stabilisce il perimetro. Per gli input puoi riprendere il metodo del contratto di input per workflow AI, specificando formato, campi obbligatori e comportamento quando un dato manca.

Evita output come “brief migliore”. Definisci invece una struttura che un'altra persona possa controllare. Per esempio: stato complete, incomplete o blocked; elenco dei campi verificati; problemi collegati al punto del brief; proposta separata dall'evidenza.

La condizione di stop non è un messaggio generico di prudenza. Deve impedire alla procedura di colmare un vuoto con una supposizione. Se una fonte centrale manca, la Skill registra il problema e termina senza dichiarare il brief pronto.

Scrivi un trigger che non si attivi ovunque

Il nome descrive la capacità per una persona. La descrizione aiuta Claude a capire quando usarla. Una descrizione come “aiuta con i contenuti” è troppo ampia: potrebbe attivarsi durante la scrittura, la revisione o una semplice domanda.

Preferisci una formulazione che includa azione, oggetto e confine:

Controlla la completezza di un brief editoriale già esistente.
Usa questa Skill quando l'utente chiede di validare un brief
prima della stesura. Non usarla per scrivere l'articolo,
scegliere il tema o approvare la pubblicazione.

Poi prepara richieste che non devono attivarla: “scrivi una headline”, “dammi cinque idee”, “correggi questo paragrafo”. Se la Skill sembra pertinente a tutte, il trigger è ancora troppo generico.

La descrizione non dovrebbe promettere un risultato che le istruzioni non possono verificare. “Garantisce la qualità del brief” nasconde criteri e responsabilità. “Controlla la presenza dei campi e segnala i blocchi” indica un comportamento osservabile.

Costruisci lo scheletro di SKILL.md

La struttura seguente è un esempio editoriale ridotto. Va adattata alla sintassi corrente del tuo ambiente e alle regole del progetto.

---
name: controlla-brief-editoriale
description: Controlla un brief esistente prima della stesura. Usa la Skill per verificare audience, obiettivo, fonti, CTA e condizioni di arresto. Non usarla per scrivere o pubblicare.
---

# Controlla il brief editoriale

## Input richiesti

- percorso del brief
- audience e domanda primaria
- fonti collegate ai claim
- CTA e destinazione

Se manca il percorso o il file non è leggibile, fermati.

## Procedura

1. Leggi il brief completo.
2. Verifica i campi richiesti senza inventare quelli assenti.
3. Collega ogni problema alla sezione interessata.
4. Distingui fatti mancanti da scelte editoriali aperte.
5. Produci l'esito nel formato definito sotto.

## Output

- Stato: complete, incomplete oppure blocked
- Campi verificati
- Problemi con evidenza
- Correzioni proposte
- Prossima azione

## Stop

Fermati su dati sensibili inattesi, fonte centrale assente
o richiesta di pubblicazione non autorizzata.

Lo scheletro è intenzionalmente corto. Se la parte centrale cresce, crea file di riferimento distinti e indica esattamente quando leggerli. Una Skill che carica sempre un manuale intero può rendere meno leggibile il passaggio che conta.

Sposta esempi e risorse fuori dal flusso principale

Gli esempi sono utili quando mostrano una decisione difficile, non quando ripetono una regola già chiara. Puoi conservare un brief completo, uno incompleto e uno bloccato in una cartella examples/. Rimuovi dati reali e spiega perché ogni esito è corretto.

Le risorse servono per tassonomie, schemi o riferimenti che la Skill consulta soltanto in certi casi. Indica il percorso e la condizione: “leggi references/schema-brief.md quando devi verificare i campi”, non “consulta le risorse se utile”.

Uno script è giustificato quando esegue un controllo deterministico, per esempio validare che un JSON contenga chiavi obbligatorie. Non usarlo per nascondere una decisione editoriale. Prima di eseguire script provenienti da altre Skill, leggili e verifica che cosa possono accedere o modificare. La guida Anthropic raccomanda di non inserire segreti e di esaminare le Skill scaricate.

Progetta casi positivi, negativi e di arresto

Una Skill non è verificata perché funziona sul caso che hai usato per scriverla. Prepara una matrice minima:

Il caso positivo controlla il percorso previsto. I negativi misurano la precisione del trigger. I casi di arresto verificano che la procedura non continui quando manca l'autorità o la base informativa.

Conserva input e output attesi. Un dataset di test per un workflow AI può essere piccolo ma deve includere le differenze che contano. Non usare un solo esempio cambiando il nome del file.

Dopo una correzione, ripeti anche i casi che prima funzionavano. Una descrizione resa più specifica può evitare un'attivazione sbagliata ma smettere di riconoscere la richiesta corretta.

Versiona la procedura insieme alle prove

Registra almeno versione, data, motivo della modifica e casi rieseguiti. La Skill e la SOP da cui deriva non devono divergere in silenzio. Se la procedura approvata cambia un campo obbligatorio, aggiorna istruzioni, esempi e test nello stesso lavoro.

Puoi usare una nota sintetica:

Versione: 1.2
Modifica: CTA ora obbligatoria per i brief destinati al blog.
Motivo: il passaggio alla produzione restava ambiguo.
Test rieseguiti: completo, CTA assente, richiesta fuori trigger.
Esito: tre casi coerenti con l'atteso.

Non aggiornare il numero di versione senza spiegare il comportamento cambiato. La provenienza serve a capire quale regola ha prodotto un esito, soprattutto quando due persone usano copie diverse della Skill.

Una SOP per workflow AI resta la fonte organizzativa più ampia: include ruoli, eccezioni e responsabilità. La Skill esegue una parte delimitata, non sostituisce chi approva il processo.

Un esempio: controllo di completezza di un brief

Immagina un brief con titolo, audience e struttura, ma senza fonte per il claim “riduce i tempi del 40%”. La Skill non dovrebbe rendere la frase più prudente e proseguire come se il problema fosse risolto. Deve indicare il claim, registrare l'assenza della fonte e applicare lo stato previsto dal contratto.

Se il brief contiene invece una fonte pertinente ma manca la CTA, l'esito può essere incomplete. La correzione proposta resta separata: “definire destinazione e azione richiesta” non equivale a inventare una pagina commerciale.

Infine, se l'utente chiede “scrivi l'articolo da questo brief”, la Skill di controllo non dovrebbe appropriarsi dell'intero lavoro. Può essere eseguita prima soltanto se la richiesta e il sistema prevedono quel passaggio; poi la stesura appartiene a un'altra procedura.

I tre casi mostrano perché trigger, output e stop sono più importanti di una lunga lista di consigli. Rendono visibile la decisione che la Skill deve prendere.

Errori comuni

Il primo è trasformare una raccolta di preferenze in una Skill universale. Se deve attivarsi sempre, probabilmente stai descrivendo istruzioni di progetto.

Il secondo è incorporare segreti, token o dati reali negli esempi. Le risorse della Skill devono essere revisionabili e condivisibili secondo il loro perimetro.

Il terzo è scrivere soltanto il percorso ideale. Senza dati mancanti, conflitti e richieste fuori scope non sai come reagirà la procedura sul lavoro reale.

Il quarto è permettere alla Skill di pubblicare o modificare servizi esterni soltanto perché sa produrre una bozza. Produzione e rilascio hanno gate e autorizzazioni distinti.

Porta una procedura reale nel programma

Scegli una procedura che il team usa già e individua un solo passaggio ripetibile. Scrivi trigger, input, output e stop prima di toccare la struttura della Skill. In questo modo il componente nasce da una decisione operativa, non dal desiderio generico di automatizzare.

Nel programma per costruire Skill e processi con Claude di MAIKER HUB puoi lavorare su questo passaggio, preparare i casi di prova e decidere dove mantenere la supervisione. Porta una procedura senza dati riservati e un esempio di esito corretto.