Claude Skills: come creare una skill da zero (esempio reale)

Questo articolo esiste perché una Claude Skill ha fatto la maggior parte del lavoro: ha cercato gli articoli correlati sul blog, letto la SERP italiana, verificato che il titolo fosse unico, scritto la bozza secondo le mie regole SEO e l'ha caricata nel CMS tramite il mio server MCP. Io ho scelto l'argomento e riletto il testo.

Non è magia, è un file Markdown di un centinaio di righe. Da quando l'ho scritto ha prodotto oltre 150 articoli con lo stesso processo, sempre nello stesso ordine, senza che io debba rispiegare ogni volta come lavoro.

In questa guida ti mostro esattamente come si crea una skill: cosa sono le Claude Skills, come è fatto un SKILL.md, quando conviene usarle al posto di un server MCP o di un subagent. Ti faccio vedere il codice della skill reale che uso in produzione. Alla fine trovi gli errori che ho fatto io, così tu li salti.

Cosa sono le Claude Skills

Le Claude Skills sono cartelle di istruzioni che Claude carica da solo quando riconosce che un compito le riguarda. Ogni skill contiene un file SKILL.md con un'intestazione (nome e descrizione) e le istruzioni operative. Può includere anche script, template e documenti di riferimento.

La differenza rispetto a un prompt salvato è nel meccanismo di caricamento, che Anthropic chiama progressive disclosure:

• All'avvio Claude legge solo nome e descrizione di ogni skill: poche decine di token ciascuna.
• Quando serve carica il corpo del SKILL.md, cioè le istruzioni complete.
• Solo se necessario apre i file di supporto (reference, script, esempi).

Risultato: puoi avere decine di Claude Skills installate senza appesantire la finestra di contesto.

Le Claude Skills seguono lo standard aperto Agent Skills. Lo stesso SKILL.md funziona in Claude Code, in Claude.ai e Cowork, nell'Agent SDK e in strumenti compatibili come Codex, Gemini CLI e OpenCode. Scrivi una volta, usi ovunque.

Claude Skills, CLAUDE.md, MCP o subagent: quale usare

La regola breve: CLAUDE.md dice a Claude chi sei, una skill gli dice come fare un compito, un server MCP gli dà accesso a dati e sistemi esterni, un subagent isola un lavoro lungo in un contesto separato. Nella pratica si combinano.

La mia pipeline editoriale usa tutti e quattro. Il CLAUDE.md conosce il brand, la skill orchestra i passaggi, il server MCP mcp.cosimo.dev espone i tool del CMS e di Search Console, e la ricerca competitor gira in un subagent.

Se ti interessa il lato MCP, ho spiegato cosa è cambiato con la spec stateless di luglio 2026.

Anatomia di un SKILL.md

Un SKILL.md è un file Markdown con un'intestazione YAML. I campi che contano davvero sono due: name (massimo 64 caratteri) e description (massimo 200 caratteri). Claude Code è permissivo, ma la Skills API valida questi limiti: rispettali da subito e non dovrai riscrivere nulla.

La struttura tipica di una cartella skill:

crea-articolo/
├── SKILL.md          # obbligatorio: frontmatter + istruzioni
├── references/       # opzionale: regole SEO, brand, esempi
│   └── seo-rules.md
├── scripts/          # opzionale: script eseguibili
│   └── check-slug.py
└── templates/        # opzionale: scheletri di output
    └── outline.md

Tre regole di forma che la documentazione ufficiale di Claude Code raccomanda e che confermo per esperienza:

• Sotto le 500 righe. Se il SKILL.md cresce, sposta i dettagli in references/ e linkali.
• Description che dice cosa fa E quando usarla. È il solo testo che Claude legge per decidere se attivare la skill.
• Istruzioni imperative e numerate. Claude segue una checklist meglio di un discorso.

Le Claude Skills possono vivere a livello progetto (.claude/skills/nome/SKILL.md) o globale (~/.claude/skills/). Le skill di progetto vanno nel repository, così tutto il team le usa.

Se hai già dei comandi in .claude/commands/, sappi che gli slash command sono diventati skill: stesso comando /nome, più capacità.

Come creare una Claude Skill in 5 passi

Ecco il processo che seguo, con la skill reale crea-articolo come esempio. Puoi replicarlo per qualsiasi compito ripetitivo.

1. Scegli un compito che ripeti almeno una volta a settimana

Non partire dalla skill "perfetta". Parti dal lavoro che ti annoia. Per me era: cercare articoli correlati, analizzare la SERP, scrivere seguendo 20 regole SEO, caricare la bozza, far girare lo scoring. Cinque azioni, sempre le stesse, sempre nello stesso ordine.

2. Descrivi il processo a voce, poi usa lo skill-creator

In Claude Code lancia /skill-creator. È una skill ufficiale che ti intervista: cosa deve fare, quando attivarsi, se servono script. Genera la cartella e un frontmatter già valido. È il modo più veloce per non sbagliare la description.

3. Scrivi il frontmatter come un annuncio di lavoro

Questo è il frontmatter della mia skill, semplificato:

---
name: crea-articolo
description: Orchestratore end-to-end per creare un articolo pronto
  alla pubblicazione su cosimo.dev. Usalo quando l'utente dice
  "crea articolo", "nuovo articolo", "scrivi un articolo su X".
---

Nota le frasi trigger tra virgolette: sono le parole che dico davvero. Più la description assomiglia a come parli, più Claude la attiva al momento giusto.

4. Scrivi il corpo come una procedura, un passo alla volta

Il corpo della mia skill è una sequenza numerata. Ogni passo chiama un tool MCP specifico e salva un output intermedio:

# Procedura (esegui in ordine, un passo alla volta)

## Passo 0 - Duplicati e correlati
Chiama `cerca_articoli_per_keyword` e `get_articoli_correlati`.
Se esiste un articolo molto simile, fermati e proponi
aggiornamento o angolo diverso.

## Passo 1 - SERP e competitor (obbligatorio)
Chiama `serp_google` (it) e `brief_pre_scrittura`.
Analizza i primi 5 risultati: lunghezza, H2, FAQ, punti deboli.
Definisci la strategia di superamento.

## Passo 2 - Keyword e titolo
Keyword principale (2-4 parole) + 3-5 secondarie.
Max 60 caratteri. Verifica con `verifica_titolo_unico`.
Chiedi conferma all'utente.

## Passo 3 - Outline
4-8 H2, FAQ (3-7), sezione pratica, CTA.

## Passo 4 - Scrittura
Minimo 1.500 parole. Keyword nel primo paragrafo, in un H2
e nella conclusione. 3-7 link interni. Vedi references/seo-rules.md.

## Passo 5 - Pubblica in BOZZA
Chiama `create_articolo` con stato bozza. Mai pubblicare direttamente.

## Passo 6 - Scoring
Chiama `analizza_seo_articolo`. Target 95/100.
Massimo 3 iterazioni, poi riporta all'utente.

Due dettagli che fanno la differenza: il passo 0 può fermare il processo (una skill deve sapere quando non procedere) e il passo 5 forza lo stato bozza (l'ultimo click resta umano).

5. Testa con tre richieste diverse e misura

Prova la skill con una richiesta esplicita ("crea articolo su X"), una implicita ("mi serve un pezzo sul tema Y") e una fuori bersaglio ("correggi il footer"). Nei primi due casi deve attivarsi, nel terzo no.

Poi confronta l'output con quello che avresti fatto a mano. Se devi correggere sempre la stessa cosa, quella correzione va nel SKILL.md.

Il caso reale: le Claude Skills nella pipeline di cosimo.dev

La skill da sola non basterebbe: ha bisogno di mani. Le mani sono i tool del mio server MCP, che espone al modello circa 90 funzioni: articoli e categorie del CMS, Search Console, Analytics, SerpApi per SERP e Google Trends, PageSpeed, feed di notizie tech.

La skill decide cosa fare e in che ordine; l'MCP fa come. In pratica, quando scrivo "crea articolo", succede questo:

• Search Console mi dice su quali query il blog sta già salendo (in agosto 2026: i confronti tra strumenti di AI coding).
• Google Trends mi dice cosa sta esplodendo (la query "claude skills" era in impennata quando ho scritto questo pezzo).
• La SERP mi dice chi c'è in prima pagina e cosa gli manca.
• Il CMS riceve la bozza già con FAQ, schema HowTo, meta description e link interni.

Costruire tutto questo ha richiesto qualche settimana. Mantenerlo costa dieci minuti quando cambio una regola: modifico un file Markdown, non un'applicazione.

È lo stesso principio che applico quando costruisco automazioni e web app per le aziende: la logica di business deve essere leggibile da chi la usa.

7 errori da evitare con le Claude Skills

• Description generica. "Aiuta con gli articoli" non si attiva mai. "Usalo quando l'utente dice: crea articolo" sì.
• SKILL.md monolitico. Oltre 500 righe Claude perde il filo. Sposta le regole di dettaglio in references/.
• Dati hardcodati. Prezzi, nomi cliente, URL cambiano: mettili in un file separato o passali come input.
• Nessuna condizione di stop. Una skill che va sempre avanti produce duplicati e danni. Prevedi i casi in cui deve fermarsi e chiedere.
• Azioni irreversibili automatiche. Pubblicare, inviare, cancellare: lascia sempre l'ultimo passo a un umano.
• Skill installate alla cieca. Una skill può contenere script. Leggi cosa esegue prima di installarla da un marketplace: gli agenti AI sono già un bersaglio.
• Nessun test di non-attivazione. Una skill che si accende quando non deve è fastidiosa quanto una che non si accende mai.

Cosa può automatizzare una PMI con le Claude Skills

Le Claude Skills non sono solo per chi scrive codice. In Claude Cowork le stesse cartelle diventano procedure aziendali che chiunque in ufficio può lanciare. Alcuni esempi che ho costruito o valutato con clienti:

• Preventivi: una skill che legge il listino, applica le regole di sconto e produce il PDF nel formato dell'azienda.
• Email commerciali: risposte nel tono del titolare, con le informazioni prese dal gestionale via MCP.
• Report settimanali: vendite, ordini e scorte in un documento pronto per il lunedì mattina.
• Onboarding fornitori: raccolta documenti, verifica campi obbligatori, checklist di conformità.
• Contenuti: post per social e newsletter partendo dalle novità del catalogo.

Il pattern è sempre lo stesso: una skill che descrive come l'azienda fa quella cosa, un MCP che collega i dati veri, un umano che approva. Ne ho parlato più in dettaglio nella guida ai plugin di Claude Cowork.

Leggi anche

• Claude Code Skill: 15 estensioni, repo e tips 2026
• Claude Code Cheatsheet 2026: guida completa per sviluppatori
• MCP 2026-07-28: la spec diventa stateless, cosa si rompe
• Claude Cowork Plugin: guida completa per automatizzare il lavoro

Conclusione: la tua prima Claude Skill in un pomeriggio

Le Claude Skills sono il modo più economico che conosco per trasformare un modello generico in un collaboratore che lavora come te. Un file Markdown, una description scritta bene, una procedura numerata. Il resto lo impari costruendola.

Se hai un processo ripetitivo in azienda e vuoi capire se una skill (con o senza MCP) può assorbirlo, scrivimi: ti dico in una call se ha senso e quanto costa. Se invece sei uno sviluppatore, apri il terminale, lancia /skill-creator e descrivi la cosa che hai fatto tre volte questa settimana.