Quando chiedi contenuti a un'AI, il formato di output conta quanto il contenuto stesso. Markdown è il formato ideale per contenuti che un umano deve leggere (documenti, guide, dispense): usa simboli semplici (#, *, -) per titoli, elenchi e enfasi, ed è ciò che l'AI produce "naturalmente" quando scrive. JSON è il formato ideale per dati che un altro programma deve leggere (una tabella, una lista strutturata, la configurazione di uno strumento): chiavi e valori precisi, nessuna ambiguità. Sapere quale chiedere — e come chiederlo bene — trasforma l'AI da "scrittore" a "fornitore di dati pronti all'uso".
# Titolo, ## Sottotitolo — la gerarchia dei cancelletti definisce i livelli, esattamente come in questa guida.**grassetto**, *corsivo* — nessun tag HTML, solo simboli attorno al testo.- voce per elenchi puntati, 1. voce per elenchi numerati — l'AI li usa automaticamente quando elenca cose.Il problema più comune con il JSON generato dall'AI: risposte con preamboli ("Ecco il JSON richiesto:"), markdown attorno (```json), o troncamenti su output lunghi. La soluzione è dare istruzioni esplicite sul formato E un esempio della struttura attesa.
Una Skill è una cartella con un file SKILL.md che Claude carica automaticamente quando un compito corrisponde alla sua descrizione — niente più copia-incolla dello stesso prompt lungo ad ogni conversazione. È il modo in cui una procedura scritta bene una volta (come questa stessa collana di guide didattiche!) diventa qualcosa che Claude sa applicare in modo coerente ogni volta che serve, senza doverla ripetere.
preventivo-standard) e coincidere col nome dichiarato nei metadati. Massimo 64 caratteri per il nome, 200 per la descrizione. I nomi non possono contenere le parole "claude" o "anthropic", riservate da Anthropic.Se ogni Skill installata caricasse subito tutto il proprio contenuto, avere più di 2-3 competenze attive appesantirebbe ogni conversazione. La divulgazione progressiva risolve il problema su 3 livelli:
quiz-contabilita-generator/ — il nome deve coincidere con quello nei metadati del file.name e description.assets/, script di validazione in scripts/, documentazione estesa in references/ — solo se il task lo richiede davvero.Il modo più veloce per creare una prima Skill non è scriverla a mano, ma usare skill-creator — una Skill ufficiale di Anthropic pensata apposta per generarne altre. Si lancia in Claude Code (o si richiama in una conversazione), risponde a poche domande su cosa deve fare la nuova Skill e quando va usata, e genera automaticamente la cartella con il file SKILL.md già impostato correttamente. Il tuo compito a quel punto è rivedere e rifinire soprattutto la description, che resta la parte più delicata.
Il modo più rapido per imparare a scrivere buone Skill non è partire da zero, ma studiare quelle scritte bene da altri e "smontarle" per capirne il pattern. Anthropic mantiene pubblico su GitHub il repository anthropics/skills: è il riferimento migliore per vedere come sono strutturate le Skill professionali reali — inclusa la Skill che genera altre Skill (skill-creator) e quelle che permettono a Claude di creare documenti Word, PDF, PowerPoint ed Excel.
| Esigenza | Formato/Strumento giusto | Perché |
|---|---|---|
| Output singolo | ||
| Documento da leggere/pubblicare | Markdown | Struttura leggibile, facile da convertire in HTML/Word/PDF |
| Dati da passare a un programma | JSON | Struttura precisa, parsabile automaticamente senza ambiguità |
| Procedura ripetuta nel tempo | ||
| Una task che rifai identica ogni volta | Skill | Scritta una volta, richiamata automaticamente, coerente ad ogni uso |
| Task una tantum, non ripetuta | Prompt diretto | Non vale la pena strutturarla come Skill permanente |
| Punto di partenza | ||
| Prima Skill mai scritta | skill-creator o template-skill | Struttura già corretta, tu completi solo i contenuti |
| Pattern non chiaro in mente | Reverse engineering da GitHub | Studiare un esempio reale è più veloce che indovinare la struttura |
assets/ come template di riferimento?