Claude Skills: guida pratica e confronto con MCP

Loading the

In questa guida ti spiego cos’è una Claude Skills, come attivarla, come installare gli esempi ufficiali, come crearne una tua (con un tutorial concreto) e, soprattutto, quando usare le Skills e quando invece serve un server MCP. Alla fine trovi FAQ, troubleshooting e una checklist pronta all’uso.

Ho anche realizzato un video tutorial completo che ti guida passo passo attraverso tutti questi concetti, mostrandoti l’intero processo in azione, inclusa la demo pratica per creare un generatore di preventivi.

Cosa sono le Skills (in concreto)

Una Skill è un pacchetto (cartella o ZIP) che contiene:

• SKILL.md: istruzioni chiare su cosa fa la Skill e come usarla.
• /scripts: codice eseguibile (per attività affidabili: es. Python).
• /resources: file di supporto (template DOCX/PPTX/XLSX/PDF, font, immagini, CSV).

Come funziona: quando chiedi qualcosa in chat, Claude scansiona le Skill disponibili e carica solo quelle rilevanti on-demand (quindi è veloce e usa solo ciò che serve).

Per cosa sono ideali: documenti, presentazioni, fogli di calcolo, PDF, immagini e, in generale, workflow deterministici e ripetibili. Le Skill sono componibili, portatili (Claude Apps, Claude Code, API) ed efficienti per design.

🔗 Repository ufficiale (esempi pronti):
https://github.com/anthropics/skills
Trovi Skill come brand-guidelines, artifacts-builder, document-skills (DOCX/PPTX/XLSX/PDF), skill-creator, template-skill, webapp-testing, mcp-builder, ecc.

Requisiti

• Un piano Claude a pagamento (Pro, Max, Team o Enterprise).
• Accesso a Claude App (per usare le Skill nella chat) e/o Claude Code (per sviluppatori).
• Facoltativo: accesso API se vuoi gestire le Skill via endpoint /v1/skills.

Attivazione (Claude App) – Passo per passo

1. Apri Claude e vai su Impostazioni
2. Entra in Funzionalità / Capabilities
3. Attiva: Code Execution & File Creation
4. Scorri fino a Skills
5. Abilita le Skill predefinite o Carica un tuo ZIP (drag-and-drop)

Se tutto è ok, vedrai la Skill nell’elenco e Claude la userà automaticamente quando pertinente.

Piani supportati: Pro, Max, Team, Enterprise.

Tip: la Skill “skill-creator” guida passo-passo alla creazione di nuove Skill (Q&A → struttura cartelle → SKILL.md → script → bundle ZIP). Nel repo ufficiale trovi template-skill/ e agent_skills_spec.md.

Installare esempi ufficiali (in 2 minuti)

A) Da Claude App

• Vai in Impostazioni → Skills
• Attiva alcune Skill “ufficiali” già disponibili (es. brand-guidelines, document-skills).
• Fatto: usale in chat (“Crea una presentazione seguendo le mie brand guidelines”).

B) Da Claude Code (Marketplace)

Se usi Claude Code:

/plugin marketplace add anthropics/skills

Poi installa:

/plugin install example-skills@anthropic-agent-skills
/plugin install document-skills@anthropic-agent-skills

Creare una Skill “da zero” (metodo veloce)

Opzione 1: guidata con “skill-creator”

1. Abilita la Skill skill-creator.
2. Scrivi in chat:

“Crea una Skill chiamata report-invoice-builder che riceve CSV/JSON, calcola totali/IVA/sconti e compila un template DOCX/PDF. Documenta parametri e comandi in SKILL.md.”

3. Claude farà Q&A, genererà struttura + SKILL.md + script e produrrà lo ZIP pronto.

Opzione 2: partire dal template ufficiale

1. Vai su anthropics/skills e copia template-skill/.
2. Rinomina (es. report-invoice-builder/).
3. Compila il frontmatter in SKILL.md:

---
name: report-invoice-builder
description: Genera report/fatture da CSV/JSON con template DOCX/PDF e regole di calcolo.
---
# Report & Invoice Builder
Istruzioni, esempi di prompt, parametri (input_file, currency, tax_rate, ecc.).

4. Aggiungi i tuoi script in /scripts e i template in /resources/templates/.
5. Comprimi in ZIP e carica in Impostazioni → Skills.

Tutorial pratico: “Report & Invoice Builder Skill”

Cosa fa:

• Importa CSV/JSON (righe fattura, ordini, anagrafiche)
• Applica regole (IVA, sconti, arrotondamenti)
• Compila template DOCX/PDF (fatture, preventivi, report vendite)
• Esporta con naming deterministico (es. FATT-2025-01023.pdf)

Struttura consigliata

report-invoice-builder/
├─ SKILL.md
├─ scripts/
│  ├─ csv_to_json.py         # pulizia/normalizzazione
│  ├─ compute_totals.py      # calcoli fiscali/contabili
│  ├─ render_doc.py          # merge dati + template -> DOCX/PDF
│  └─ utils.py               # round, currency, id fattura, date
└─ resources/
   ├─ templates/
   │  ├─ invoice_template.docx
   │  └─ sales_report.docx
   └─ examples/
      ├─ orders.csv
      └─ invoice.json

Esempi di prompt da incollare in chat

• “Genera una fattura da resources/examples/orders.csv, IVA 22%, valuta EUR. Salva FATT-2025-01023.pdf.”
• “Crea report vendite mensile da sales_oct.json, somma per categoria e esporta report-ottobre.pdf.”

Consigli pratici

• Mantieni gli script invocabili da CLI con --help (utile per test e debug).
• Nei template DOCX usa placeholder chiari (es. {{CLIENT_NAME}}, {{TOTAL}}).
• Definisci una sola policy di arrotondamento (commerciale, 2 decimali) per evitare discrepanze.

Skills o MCP? La regola d’oro

• Se devi leggere/scrivere su API esterne, DB o hai dati live, ti serve MCP (server “always-on”, con connettori).
• Se devi eseguire codice deterministico e generare/modificare file (doc, pptx, xlsx, pdf, immagini), ti bastano le Skills (niente server da gestire).
• Spesso la soluzione migliore è ibrida: MCP raccoglie i dati live → Skill li trasforma in documenti standardizzati.

Tabella di confronto

Aspetto	Custom Instructions	Claude Skills	MCP Server
Setup	Solo testo	ZIP on-demand	Server always-on
Esecuzione	Sempre attive (statico)	On-demand (caricamento mirato)	Always-on (heavyweight)
Capacità	Regole/tono/policy	Esecuzione codice, FileGen	API/DB/dati live
Use case	Stile, policy, persona	Doc/Excel/PPTX, PDF, automazioni locali	ERP/CRM, e-commerce, RAG live
OPS	Minima	Bassa	Media/Alta

Come si usano via API (per sviluppatori)

• Le Skills si aggiungono alle richieste Messages API.
• Esiste un endpoint dedicato /v1/skills per versioning e gestione.
• Serve il Code Execution Tool (beta) abilitato.

Suggerimento: gestisci le versioni come fai con le release: tag semantici (v1.2.0), changelog, ZIP firmato (checksum) e rollback pronto.

Best practice (impostazione “da azienda”)

1. SKILL.md chiarissimo: scopo, quando usarla, parametri richiesti, esempi completi, limiti.
2. Modularità: separa parsing, calcolo, rendering (manutenibilità e test migliori).
3. Determinismo: stessi input ⇒ stessi output; naming prevedibile (es. out-{yyyy}-{seq}.pdf).
4. Dipendenze: elencale in requirements.txt; preferisci librerie stabili.
5. Testing: fixture in /resources/examples/, casi base + edge, CLI --help.
6. Versioning: Git + tag, CHANGELOG, artefatto ZIP firmato.
7. Governance: approvazioni, ambienti staging/prod, log sintetici (start/end, esito).
8. Sicurezza: codice da fonti fidate, nessun segreto hard-coded, principio del minimo privilegio (limita formati e percorsi).

Errori comuni (e come evitarli)

• SKILL.md vago → aggiungi esempi con parametri e output attesi.
• Script monolitico → dividi per responsabilità.
• Placeholder del template non allineati ai campi JSON → sincronizza nomi e tipi.
• Arrotondamenti incoerenti → definisci una sola regola e testala.
• ZIP non versionato → adotta tag + changelog (facilita rollback).

Troubleshooting rapido

• La Skill non parte: verifica che sia abilitata in Impostazioni → Skills e che l’oggetto della richiesta in chat corrisponda a quanto descritto nel SKILL.md.
• Errore su script: prova ad eseguirlo da CLI con gli stessi parametri; controlla dipendenze in requirements.txt.
• File generato errato: stampa i parametri di input nei log; controlla placeholder nel template.
• Conflitti tra Skill: specifica meglio quando usarla in SKILL.md (sezione “Use this when…”) e rendi i nomi univoci.

FAQ essenziali

Posso usare più Skill insieme?
Sì. Claude compone le Skill pertinenti in automatico.

Posso usare le Skill anche in Claude Code e via API?
Sì. Il formato è lo stesso; in Claude Code hai anche il Marketplace e la cartella ~/.claude/skills.

Le Skills sostituiscono MCP?
No. Le complementano: Skills per logica deterministica e file; MCP per integrazioni esterne e dati live.

Dove trovo esempi affidabili?
Nel repo ufficiale: https://github.com/anthropics/skills (contiene anche lo spec e il template-skill).

Checklist finale (copia/incolla)

☐ Obiettivo & output definiti (es. FATT-YYYY-NNNNN.pdf).
☐ Scelta architettura: Skill (file/compute) / MCP (API/DB/live) / ibrido.
☐ Struttura Skill con SKILL.md, /scripts, /resources.
☐ Template DOCX/PPTX/XLSX/PDF con placeholder allineati ai dati.
☐ Test locali (CLI + fixture), determinismo verificato.
☐ Versioning (tag, changelog) e ZIP firmato (checksum).
☐ Abilitata in Claude (Impostazioni → Skills) e provata in chat.
☐ Sicurezza & governance (review, staging/prod, log).