Skill di Claude Code per la SEO: Come Creo Workflow Automatizzati e Coerenti

Le skill di Claude Code sono istruzioni strutturate che trasformano un modello AI generico in uno specialista SEO coerente, affidabile e replicabile. In questo articolo mostro come le creo, come le testo e come le uso per automatizzare workflow SEO complessi.

Se hai provato a usare Claude Code (o qualsiasi AI) per task SEO ripetitivi, avrai notato un problema: ogni sessione è diversa. Lo stesso prompt produce risultati leggermente diversi, con priorità diverse, formati diversi, livelli di dettaglio diversi. Non è un bug — è la natura dei modelli generativi.

Le skill risolvono questo problema. Sono documenti che vivono nella tua configurazione di Claude Code e vengono caricati automaticamente quando il contesto lo richiede. Non sono prompt: sono manuali operativi che guidano il comportamento dell'AI in modo consistente, sessione dopo sessione.

In questo articolo mostro come ho costruito le mie skill SEO personali, partendo dalla skill di generazione immagini (Nano Banana) fino ai workflow di audit tecnico. Non è teoria: è il mio processo operativo documentato.

Cosa sono le skill di Claude Code e perché servono per la SEO

Il problema della inconsistenza

Quando chiedi a Claude Code di fare un audit SEO, il modello produce un output eccellente. Ma se rifai la stessa richiesta domani, l'output sarà leggermente diverso: ordine diverso, soglie diverse, dettagli diversi. Per un task occasionale non è un problema. Per un workflow che devi eseguire regolarmente su più clienti, diventa un limite serio.

Immagina di fare un audit settimanale per 5 clienti. Vuoi che ogni audit segua lo stesso processo, usi le stesse soglie di alert, produca lo stesso formato di report, verifichi gli stessi check. Senza le skill, dovresti riscrivere le istruzioni complete a ogni sessione — e comunque non avresti garanzia di coerenza.

La soluzione: skill come manuali operativi

Una skill è un file Markdown (SKILL.md) che vive nella directory delle skill di Claude Code (tipicamente ~/.claude/skills/nome-skill/). Contiene:

• Frontmatter YAML: nome e description che dicono a Claude quando caricare la skill — è il "trigger" automatico.
• Contesto e principi: spiegano cosa fare e perché, non solo come.
• Workflow strutturato: i passaggi da seguire, con decision point e branch condizionali.
• Regole e soglie: valori numerici, classificazioni, formati — i parametri che garantiscono coerenza.
• Pattern di errore: i mistake più comuni e come evitarli — Claude impara dagli errori documentati.
• Template e formati: il formato esatto degli output: report, commit message, nomi file.

Come vengono caricate

Le skill non vengono "attivate" manualmente. Claude Code le carica automaticamente quando il contesto della conversazione corrisponde alla description nel frontmatter. Se stai parlando di generazione immagini e hai una skill con description "Use when generating cover images", Claude la caricherà autonomamente.

Puoi anche invocarle esplicitamente con /skill-name, ma il valore reale è nell'attivazione automatica: non devi ricordarti di caricarle, perché Claude se ne occupa.

Anatomia di una skill SEO: struttura e principi

La struttura minima

Ogni skill segue una struttura standard. Ecco lo scheletro.

1. Frontmatter — name e description (max 1024 caratteri totali). La description inizia con "Use when..." e descrive solo le condizioni di attivazione, mai il workflow.
2. Overview — cos'è questa skill e il principio core in 1-2 frasi.
3. When to Use — bullet list con sintomi e casi d'uso. Include anche quando NON usarla.
4. Core Pattern — il workflow principale, con step numerati e decision point.
5. Regole e soglie — tabelle con parametri concreti (numeri, range, classificazioni).
6. Common Mistakes — errori frequenti con fix espliciti.
7. Output Format — template per il formato dell'output atteso.

Il principio del "trigger, non summary"

La description nel frontmatter è il campo più critico. Un errore che ho fatto all'inizio: descrivere cosa fa la skill nella description. Sbagliato.

Se la description riassume il workflow, Claude tende a seguire il riassunto invece di leggere il contenuto completo della skill. È un pattern cognitivo: se trova un riassunto, lo usa come shortcut.

La description deve contenere solo le condizioni di attivazione: quando usarla, quali sintomi la triggerano, in quale contesto si applica. Il "come" sta nel corpo della skill.

Keyword coverage per il discovery

Claude cerca le skill per keyword match. Se la tua skill parla di "audit SEO" ma nella description usi solo "analisi tecnica", Claude potrebbe non trovarla quando cerchi "audit". La soluzione: usa sinonimi, varianti e termini correlati sia nella description che nel corpo della skill.

Per una skill SEO, le keyword dovrebbero coprire: i termini tecnici (crawl, canonical, redirect, status code, alt text), i sinonimi italiani e inglesi (posizionamento/ranking, indicizzazione/indexing), i nomi degli strumenti (Screaming Frog, Search Console, Ahrefs), e i sintomi dei problemi (errore 404, pagina non indicizzata, traffico in calo).

Caso studio #1: la skill Nano Banana per la generazione immagini

La prima skill che ho creato per il mio sito è Nano Banana — il sistema di generazione immagini di copertina per pagine e articoli. È un ottimo esempio di skill ben strutturata perché copre tutti gli aspetti: configurazione tecnica, linee guida creative, template riutilizzabili e errori da evitare.

Il problema che risolve

Il mio sito ha circa 80 pagine, ciascuna con un'immagine di copertina. Generare immagini coerenti con l'identità visiva del brand non è banale: senza linee guida precise, ogni immagine ha uno stile diverso — colori, mood, composizione cambiano a ogni generazione.

La skill Nano Banana risolve questo definendo regole visive vincolanti che vengono applicate a ogni generazione, automaticamente.

Struttura della skill

La skill è organizzata in sezioni concentriche, dal più generale al più specifico.

Modelli disponibili: la skill documenta tre varianti di Gemini (Nano Banana, Nano Banana 2, Nano Banana Pro) con le differenze di qualità, velocità, risoluzione e costo. Il modello di default è impostato sulla variante più veloce per l'uso ad alto volume.

API call: il codice esatto per chiamare OpenRouter con il modello corretto, inclusi header, payload e gestione della risposta. Non un esempio generico: il codice funzionante specifico per il nostro setup.

Prompt architecture: un template strutturato per costruire prompt coerenti: [stile] [tipo di shot] [soggetto/scena] [dettagli composizione] [mood] [lighting] [palette colori] [spazio negativo] [aspect ratio]. Non keyword sciolte: una struttura narrativa che produce risultati consistenti.

Brand guidelines: i colori esatti del brand (teal #14B8A6, slate #0F172A, off-white #F1F5F9), il mood (professionale ma accessibile, minimal, data-driven), le regole di stile (no stock imagery generica, preferire fotografia editoriale, profondità di campo) e un "preamble" da anteporre a ogni prompt.

Aspect ratio e risoluzioni: tabelle dettagliate con le risoluzioni disponibili per ogni modello, i casi d'uso (16:9 per hero, 1:1 per social, 9:16 per stories) e le limitazioni specifiche.

Errori comuni: una tabella con i mistake più frequenti e i fix. "Prompt a keyword-list" → "Scrivi descrizioni narrative". "Nessun aspect ratio" → "Specifica sempre, default 16:9". "Nessuno spazio negativo" → "Richiedi esplicitamente area per text overlay".

Come la skill garantisce coerenza

Senza la skill, ogni richiesta di immagine richiederebbe di specificare: modello, API endpoint, colori del brand, stile fotografico, composizione, aspect ratio. Con la skill, basta dire "genera un'immagine di copertina per la pagina consulenza SEO" e Claude applica automaticamente tutte le regole.

Il risultato: 80+ immagini di copertina tutte coerenti con l'identità visiva del sito. Stessa palette, stesso mood, stessa qualità. Costo totale: circa 3 dollari. Tempo: pochi minuti per batch con uno script di automazione.

Lezione appresa: il preamble obbligatorio

La sezione più utile della skill è il "preamble" — un blocco di testo che viene anteposto a ogni prompt di generazione immagine. Contiene le regole visive fondamentali: stile editoriale, palette cool-toned con teal, luce naturale diffusa, profondità di campo, composizione pulita, no testo nell'immagine.

Senza il preamble, dovrei ripetere queste istruzioni a ogni prompt. Con il preamble nella skill, sono applicate automaticamente e non posso dimenticarle. Questo pattern — definire un preamble obbligatorio per ogni tipo di output — è trasferibile a qualsiasi skill SEO: audit report, content brief, meta description.

Caso studio #2: skill per audit SEO tecnico con Screaming Frog

Questa skill è progettata per lavorare in sinergia con il workflow MCP di Screaming Frog che ho descritto nell'altro articolo. Definisce le regole operative dell'audit.

Cosa definisce la skill di audit

La skill di audit non ripete il "come usare il tool" — quello lo sa già Claude. Definisce il "come ragionare sui dati" e il "cosa considerare critico".

Tab da esportare per default: Internal:All, Response Codes:All, Page Titles:All, Meta Description:All, H1:All, H2:All, Images:All, Directives:All, Canonicals:All. Ogni audit parte con gli stessi dati, sempre.

Soglie di classificazione: le regole numeriche che determinano se un valore è ok, warning o errore. Title: <30 char = warning, >60 = errore. Description: <80 char = warning, >160 = errore. Immagini: >200 KB = warning, >500 KB = errore. Queste soglie garantiscono che ogni audit usi gli stessi criteri.

Analisi incrociate obbligatorie: la lista di check che devono essere eseguiti incrociando dati da tab diversi. Pagine 200 + title presente + description presente. Canonical = URL effettiva. Nessun link interno che punta a 3xx o 4xx. Immagini nelle pagine core hanno alt text.

Classificazione dei problemi: critico (impatto immediato su indicizzazione: 5xx, noindex errati, canonical rotti), alto (impatto su ranking: title mancanti, catene di redirect), medio (impatto su UX e CTR: description troppo lunghe, alt mancanti), basso (ottimizzazione: title che potrebbe essere migliorato).

Formato del report: struttura fissa per ogni audit. Executive summary, statistiche generali, problemi critici con dettaglio URL, problemi alti, problemi medi, confronto con crawl precedente (se disponibile), azioni raccomandate con priorità.

Perché le soglie fisse sono fondamentali

Senza soglie definite nella skill, Claude prende decisioni ragionevoli ma inconsistenti. Un giorno classifica un title di 65 caratteri come "leggermente lungo", il giorno dopo come "problematico". Per un singolo audit non importa. Per il monitoraggio continuo su più clienti, questa inconsistenza rende impossibile tracciare i miglioramenti nel tempo.

Le soglie nella skill fungono da "contratto": ogni audit usa gli stessi criteri, e il delta tra due audit successivi riflette cambiamenti reali, non variazioni nell'interpretazione.

Come creare una skill SEO: il processo step-by-step

Creare una skill non è scrivere documentazione. È un processo iterativo che richiede testing e raffinamento. Ecco il mio approccio.

Step 1: Identifica il pattern ricorrente

Una skill ha senso quando fai la stessa cosa più di 3 volte e il risultato deve essere coerente. Esempi SEO tipici:

• Audit tecnico — stesso processo, stesse soglie, stesso formato di report.
• Generazione meta tag — stesse regole di lunghezza, stessa struttura, stesso tono.
• Review del contenuto — stessi criteri E-E-A-T, stesse verifiche, stesse raccomandazioni.
• Generazione immagini — stessa identità visiva, stessi parametri tecnici.
• Analisi competitor — stessi KPI, stessa struttura di confronto.

Step 2: Documenta il tuo processo manuale

Prima di scrivere la skill, fai il task manualmente almeno 3 volte e annota tutto: ogni decisione, ogni soglia, ogni preferenza. Le cose che dai per scontate sono quelle che mancano nelle skill scritte di fretta.

Domande chiave da porsi durante la documentazione:

• Quali dati consulto sempre? (tab Screaming Frog, metriche Search Console, ecc.)
• Quali soglie uso per classificare i problemi? (sono numeri precisi o "a sensazione"?)
• In che ordine analizzo le cose? (c'è una priorità naturale?)
• Cosa mi fa decidere che un problema è critico vs basso? (quali criteri?)
• Che formato ha il mio output? (report, lista, tabella, commit message?)
• Quali errori faccio più spesso? (e come li prevengo?)

Step 3: Scrivi la skill in formato strutturato

La skill è un file SKILL.md con frontmatter YAML. Segui questa struttura.

Frontmatter: nome con soli lettere, numeri e trattini. Description che inizia con "Use when..." e contiene solo le condizioni di attivazione, mai il riassunto del workflow.

Corpo: overview in 1-2 frasi, when to use con bullet list, core workflow con step numerati, regole e soglie in tabelle, errori comuni con fix, formato output con template.

Tieni la skill sotto le 500 parole se possibile. Claude deve poterla leggere e interiorizzare velocemente. Se una sezione richiede contenuto pesante (es. documentazione API con 100+ righe), mettila in un file separato referenziato dalla skill.

Step 4: Testa con scenari reali

Questo è il passaggio che fa la differenza tra una skill mediocre e una eccellente. Non basta scrivere la skill: devi testarla con scenari reali e verificare che Claude la segua correttamente sotto pressione.

Il processo di testing:

1. Lancia una sessione senza la skill e fai il task. Annota il risultato.
2. Installa la skill e rifai lo stesso task. Confronta i risultati.
3. Verifica che le soglie vengano rispettate (es. i title >60 char sono effettivamente segnalati come errore).
4. Prova scenari edge case: cosa succede con un sito che ha 0 problemi? E con uno che ne ha centinaia?
5. Prova sotto pressione: dai istruzioni contraddittorie alla skill e verifica che le regole tengano.

Step 5: Raffina sulla base dei fallimenti

Ogni volta che Claude non segue la skill correttamente, chiediti: perché? Di solito il problema è uno di questi:

• Ambiguità: la regola è troppo vaga. "Title non troppo lungo" → "Title > 60 caratteri = errore". Numeri concreti battono le descrizioni vaghe.
• Conflitto: due regole si contraddicono. La skill dice "mantieni il title sotto i 60 char" ma anche "includi sempre brand e keyword target". Definisci la priorità esplicita.
• Mancanza: un caso non è coperto. Claude prende una decisione ragionevole ma diversa da quella che vuoi. Aggiungi la regola.
• Description troppo descrittiva: la description riassume il workflow e Claude usa il riassunto come shortcut invece di leggere il corpo.

Pattern avanzati per skill SEO

Pattern #1: la skill come contratto

La skill più utile non è quella che dice a Claude cosa fare, ma quella che definisce i criteri di "fatto bene". È un contratto tra te e l'AI.

Esempio: invece di "Analizza i title tag", scrivi: "Un title è valido quando: lunghezza 30-60 caratteri, contiene la keyword primaria, non è duplicato su altre pagine, include il brand name per pagine non-blog, non inizia con stop-word". Questo è un contratto verificabile.

Pattern #2: soglie progressive

Non tutti i problemi hanno la stessa gravità. Usa soglie progressive con tre livelli: ok, warning, errore.

Pattern #3: template di output fisso

Definisci il formato esatto dell'output nella skill. Non un formato generico: il formato specifico con header, sezioni, ordine e stile.

Per un audit report, il mio template fissa: executive summary (3 frasi: stato generale, problema più critico, azione prioritaria), statistiche (tabella: URL totali, errori, warning, ok), problemi ordinati per gravità (critico → alto → medio → basso), ciascun problema con URL, valore attuale, valore atteso e azione, confronto con baseline (se disponibile), prossimi passi con priorità.

Pattern #4: cross-referencing con altre skill

Le skill possono riferirsi ad altre skill. La mia skill di audit SEO rimanda alla skill Nano Banana quando identifica immagini senza copertina, e alla skill di content review quando trova pagine con thin content.

Questo crea un ecosistema di competenze interconnesse: Claude non solo identifica il problema, ma sa anche quale skill caricare per risolverlo. È l'equivalente di un team dove ogni membro sa quando passare la palla al collega giusto.

Pattern #5: la tabella anti-razionalizzazione

Il pattern più sottile e potente. Quando Claude è sotto pressione (task complesso, molti problemi, sessione lunga), tende a prendere scorciatoie: "Questo title è solo leggermente lungo, lo lascio" oppure "La description è ok, anche se è 170 char".

Per prevenire queste razionalizzazioni, aggiungi una tabella esplicita nella skill con le scuse più comuni e la risposta corretta.

Come organizzo le mie skill SEO

L'organizzazione conta quanto il contenuto. Ecco la struttura che uso.

Ogni skill è auto-contenuta: non serve leggerne più di una per capire cosa fare. Ma possono referenziarsi quando il contesto lo richiede.

La directory delle skill

Le skill personali vivono in ~/.claude/skills/. La struttura per ciascuna è minima.

• ~/.claude/skills/nano-banana/SKILL.md — skill completa in un file singolo.
• ~/.claude/skills/seo-audit/SKILL.md — skill con riferimento a file di soglie separate se necessario.
• ~/.claude/skills/seo-fix/SKILL.md — skill con classificazione rischio e pattern fix.

La regola è: se la skill sta sotto le 500 parole, tutto in SKILL.md. Se ha heavy reference (documentazione API, tabelle lunghe), split in file separati referenziati dal file principale.

Errori che ho fatto (e che tu puoi evitare)

Errore #1: skill troppo lunghe

La prima versione della mia skill di audit era 2000 parole. Claude la leggeva, ma non la applicava in modo coerente — troppe informazioni, troppi dettagli marginali. La versione attuale è sotto le 500 parole con tabelle concise. Funziona molto meglio.

Regola: se non puoi spiegarlo in 500 parole, probabilmente stai cercando di mettere troppe responsabilità in una singola skill. Splittala.

Errore #2: description che riassume il workflow

L'ho già menzionato ma merita un rinforzo: ho scoperto che quando la description dice "analizza i dati di crawl, classifica i problemi e genera un report", Claude segue quel riassunto superficiale invece di leggere le regole dettagliate nel corpo. Risultato: un report generico senza le soglie specifiche che avevo definito.

Fix: description solo con trigger conditions. "Use when performing SEO technical audits or analyzing crawl data." Punto. Il come sta dentro la skill.

Errore #3: niente testing

Le prime skill le ho scritte e basta. Funzionavano... il 70% delle volte. Il 30% restante, Claude trovava ambiguità o casi non coperti e improvvisava. Da quando testo ogni skill con scenari reali prima di usarla in produzione, il tasso di compliance è salito al 95%+.

Errore #4: regole vaghe

"Il title non deve essere troppo lungo" non è una regola, è un'opinione. "Il title deve essere tra 30 e 60 caratteri, spazi inclusi" è una regola. Ogni volta che scrivi "adeguato", "ragionevole", "appropriato" in una skill, fermati e sostituisci con un numero o un criterio verificabile.

Errore #5: non aggiornare le skill

Google cambia le regole. I tool evolvono. Le soglie che funzionavano 6 mesi fa possono essere obsolete. Faccio una revisione delle mie skill ogni trimestre: verifico che le soglie siano ancora attuali, che i workflow riflettano i tool che effettivamente uso, e che gli errori documentati siano ancora rilevanti.

ROI concreto: cosa cambia con le skill

Quantificare il beneficio delle skill non è immediato, ma posso dare numeri reali dal mio utilizzo.

Il beneficio più grande non è il tempo risparmiato (che è già significativo). È la coerenza. Sapere che ogni audit segue lo stesso processo, ogni immagine rispetta le stesse linee guida, ogni report ha lo stesso formato — questo è ciò che ti permette di scalare senza perdere qualità.

Conclusione: le skill come investimento a lungo termine

Le skill di Claude Code non sono una feature per power user. Sono il ponte tra "uso l'AI ogni tanto per velocizzare qualcosa" e "ho un sistema di lavoro AI-augmented che produce risultati coerenti e scalabili".

Per la SEO tecnica, le skill risolvono il problema fondamentale dell'inconsistenza: le stesse soglie, lo stesso processo, lo stesso formato — sessione dopo sessione, cliente dopo cliente. Non è solo efficienza: è professionalità.

Il tempo investito nella creazione di una skill si ripaga dalla seconda sessione. Dalla terza in poi è puro guadagno. E ogni skill che scrivi migliora la tua comprensione del tuo stesso processo — perché ti costringe a formalizzare decisioni che prima prendevi "a sensazione".

Il mio consiglio: inizia dalla skill più semplice — quella per il task che fai più spesso. Testala. Raffinala. Poi passa alla successiva. In poche settimane avrai un ecosistema di competenze che trasforma il tuo modo di lavorare.

Se vuoi vedere le skill in azione su un workflow completo, leggi il mio articolo su Screaming Frog MCP + Claude Code per audit SEO automatizzati.

Per discutere di come integrare AI e automazione nel tuo workflow SEO, contattami per una consulenza. Aiuto aziende e professionisti a costruire sistemi di lavoro AI-augmented che funzionano davvero.