# Claude Skills: guida pratica e confronto con MCP

> Fonte: https://francescogruner.it/claude-skills-guida-pratica-e-confronto-con-mcp/

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.

      

Indice dei contenuti

 [Toggle](#) 

- [Cosa sono le Skills (in concreto)](#Cosa_sono_le_Skills_in_concreto)
- [Requisiti](#Requisiti)
- [Ti sta piacendo?](#Ti_sta_piacendo)
- [Attivazione (Claude App) - Passo per passo](#Attivazione_Claude_App_-_Passo_per_passo)
- [Installare esempi ufficiali (in 2 minuti)](#Installare_esempi_ufficiali_in_2_minuti)

- [A) Da Claude App](#A_Da_Claude_App)
- [B) Da Claude Code (Marketplace)](#B_Da_Claude_Code_Marketplace)
- [Creare una Skill “da zero” (metodo veloce)](#Creare_una_Skill_%E2%80%9Cda_zero%E2%80%9D_metodo_veloce)

- [Opzione 1: guidata con “skill-creator”](#Opzione_1_guidata_con_%E2%80%9Cskill-creator%E2%80%9D)
- [Opzione 2: partire dal template ufficiale](#Opzione_2_partire_dal_template_ufficiale)
- [Tutorial pratico: “Report & Invoice Builder Skill”](#Tutorial_pratico_%E2%80%9CReport_Invoice_Builder_Skill%E2%80%9D)
- [Skills o MCP? La regola d’oro](#Skills_o_MCP_La_regola_doro)
- [Come si usano via API (per sviluppatori)](#Come_si_usano_via_API_per_sviluppatori)
- [Best practice (impostazione “da azienda”)](#Best_practice_impostazione_%E2%80%9Cda_azienda%E2%80%9D)
- [Errori comuni (e come evitarli)](#Errori_comuni_e_come_evitarli)
- [Troubleshooting rapido](#Troubleshooting_rapido)
- [FAQ essenziali](#FAQ_essenziali)
- [Checklist finale (copia/incolla)](#Checklist_finale_copiaincolla)

 

## 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).

 

![Struttura di una Claude Skill: file SKILL.md, cartella Resources, brand-guidelines.pdf e archivio ZIP pronto per l’upload in Claude](https://francescogruner.it/wp-content/uploads/2025/10/Claude-Skills-Struttura-del-pacchetto-SKILL.md-Resources-ZIP-1024x655.png)

Struttura minima di una Skill: SKILL.md + Resources e asset (es. brand-guidelines.pdf), compressi in uno ZIP da caricare in Claude. 

**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](https://github.com/anthropics/skills/tree/main)  
> 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`.

                  

## Ti sta piacendo?

 

Ricevi una guida pratica ogni settimana. AI, tool e automazioni.

            Iscriviti gratis             Perfetto, sei dentro.         

## 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.

 

![Schermata di Claude con Funzionalità > Skills: pulsante “Carica competenza” e toggle attivi per abilitare le Claude Skills](https://francescogruner.it/wp-content/uploads/2025/10/Claude-Skills---Impostazioni-Funzionalita-Carica-competenza-1024x867.png)

Attiva “Code Execution & File Creation”, poi vai in Funzionalità → Skills per abilitare le competenze o caricare lo ZIP. 

**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**

 AspettoCustom Instructions**Claude Skills****MCP Server**SetupSolo testo**ZIP on-demand****Server always-on**EsecuzioneSempre attive (statico)**On-demand** (caricamento mirato)**Always-on** (heavyweight)CapacitàRegole/tono/policy**Esecuzione codice, FileGen****API/DB/dati live**Use caseStile, policy, persona**Doc/Excel/PPTX, PDF, automazioni locali****ERP/CRM, e-commerce, RAG live**OPSMinima**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](https://github.com/anthropics/skills/tree/main) (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).