Skills in Claude Code: estendere l’assistente con moduli dichiarativi

Le skills di Claude Code sono bundle dichiarativi che estendono l’assistente con conoscenza di dominio e workflow riusabili. Invece di ripetere ogni volta “ricordati che il nostro progetto usa X, segui lo stile Y, quando vedi Z fai W”, si scrive una volta sola in un file Markdown e Claude la carica quando serve.

L’idea è semplice: una cartella, un file SKILL.md con frontmatter YAML, eventuali asset o script helper accanto. Claude legge il frontmatter per decidere quando attivarla, poi segue le istruzioni nel body.

Dove vivono le skills

Claude Code cerca le skills in due posti:

• ~/.claude/skills/ — personal, disponibili in tutti i progetti dell’utente
• .claude/skills/ nella root del repo — condivise con il team via git

Le personal sono comode per workflow individuali (stile di commit, template di review, scorciatoie che non hanno senso fuori dal proprio laptop). Le di progetto vanno committate: servono a far convergere tutto il team sullo stesso modo di lavorare, senza affidarsi al fatto che ognuno scriva bene il prompt.

Anatomia di una skill

La struttura minima è una cartella con dentro un file SKILL.md:

.claude/skills/
└── pdf-extract/
    ├── SKILL.md
    ├── extract.py
    └── examples/
        └── sample.pdf

Il frontmatter YAML in testa al file contiene almeno name e description. La description è il trigger: Claude la usa per capire se la skill va attivata nel contesto corrente. Va scritta pensando al match semantico, non per SEO: elencare i casi d’uso reali, non parole chiave generiche.

Esempio: skill per estrarre testo da PDF

Un esempio concreto. La skill delega a uno script Python il lavoro sporco e lascia a Claude solo la parte di orchestrazione:

---
name: pdf-extract
description: Estrae testo e metadati da file PDF usando pdfplumber.
  Usare quando l'utente chiede di leggere un PDF, estrarre tabelle da un PDF,
  cercare testo dentro un PDF o convertire PDF in Markdown.
---

# PDF Extract

Skill per lavorare con file PDF. Usa lo script `extract.py` in questa
cartella, non reimplementare l'estrazione a mano.

## Quando attivare
- L'utente fornisce un percorso a un file .pdf
- L'utente chiede di estrarre tabelle, testo o metadati da un PDF
- L'utente vuole convertire un PDF in testo/Markdown

## Workflow
1. Verifica che `pdfplumber` sia installato: `python -c "import pdfplumber"`
2. Se manca, installa con `pip install pdfplumber`
3. Lancia lo script: `python extract.py <path-al-pdf> --format md`
4. Mostra l'output all'utente e chiedi se vuole salvarlo su file

## Note
- Per PDF scansionati (immagini) lo script non funziona: avvisa l'utente
  che serve OCR e suggerisci `ocrmypdf` prima di riprovare.
- Non tentare di parsare PDF con regex: usa sempre lo script.

Quando Claude nella conversazione vede un path PDF, riconosce il match con la description e carica il body come istruzioni operative. Lo script Python resta accanto al SKILL.md ed è richiamabile direttamente: niente copia-incolla di codice nel prompt.

Esempio: skill per il workflow di commit

Un secondo caso d’uso tipico è codificare il modo in cui il team fa commit. Invece di spiegarlo ogni volta, si mette in .claude/skills/commit/SKILL.md:

• lanciare git status e git diff --staged prima di proporre il messaggio
• verificare che non ci siano file .env o credenziali in stage
• seguire il formato Conventional Commits usato nel repo
• non aggiungere -A automaticamente, elencare i file uno per uno
• se il pre-commit hook fallisce, creare un nuovo commit, mai fare --amend

Risultato: chiunque nel team fa “committa le modifiche” ottiene lo stesso comportamento, senza dover allineare i prompt o sperare che ricordino le convenzioni.

Skill vs slash command vs sub-agent

Tre meccanismi vicini, confusi spesso. La distinzione netta:

• Skill: pacchetto riusabile di conoscenza + asset. Claude decide da solo se attivarla in base alla description. Ottimo per “quando lavori con X, segui queste regole”. Vedi https://www.smartworkers.cloud/?p=3419 per il confronto diretto.
• Slash command: shortcut per un task specifico, invocato esplicitamente con /nome. Non ha logica riusabile, è un template di prompt.
• Sub-agent: processo separato con proprio context window. Utile per task isolati che non devono sporcare la conversazione principale. Approfondimento su https://www.smartworkers.cloud/?p=3427.

Regola pratica: se serve un comportamento ripetibile che Claude deve riconoscere da solo, è una skill. Se serve un comando che l’utente lancia, è uno slash command. Se serve parallelismo o isolamento di contesto, è un sub-agent.

Come Claude decide di invocare una skill

Il match è semantico, non letterale. Claude legge tutte le description disponibili, le confronta con il contesto della conversazione (ultimi messaggi, file aperti, comandi eseguiti) e decide se attivarne una. Non c’è un sistema di regex o keyword matching: conta solo quanto bene la description descrive la situazione attuale.

Conseguenza pratica: description vaghe tipo “helper per vari task” non si attivano mai. Description specifiche con casi d’uso elencati funzionano. Meglio sbilanciarsi verso la verbosità: elencare i trigger (“usare quando…”, “attivare se…”), citare le estensioni di file o i comandi coinvolti.

Skills di default di Anthropic

Su claude.ai sono già disponibili skills ufficiali per la Office suite (Word, Excel, PowerPoint), Canva e altri tool. Su Claude Code si parte da zero: nessuna skill preinstallata, va costruito tutto. Anthropic pubblica esempi nel proprio repo GitHub che vale la pena leggere prima di scrivere la prima skill da soli, per capire il livello di dettaglio atteso nel body.

Quando scriverne una e quando no

Non tutto merita una skill. Tre criteri utili per decidere:

• Riusabilità: il comportamento va ripetuto su progetti diversi o da persone diverse? Sì → skill. No → basta un paragrafo in CLAUDE.md.
• Complessità: servono script helper, asset, esempi? Una skill è il contenitore giusto. Una singola regola da due righe no.
• Frequenza: il trigger capita spesso? Se succede una volta al mese, si può gestire a prompt. Se capita ogni giorno, vale la pena automatizzarlo.

L’errore comune è scrivere skill per tutto, saturare la cartella, e poi ritrovarsi Claude che attiva la skill sbagliata perché le description si sovrappongono. Meglio poche skill molto mirate che dieci generiche.

Da quale workflow ripetitivo vale la pena partire? Probabilmente quello che si è già spiegato tre volte a colleghi diversi con tre risultati diversi.