# Linee guida per la scrittura delle skill

## Lingua

- **Chiavi/campi degli schema** (`name`, `description`, `version` in `plugin.json` e nel frontmatter di `SKILL.md`): nomi di campo fissi in inglese, non traducibili.
- **Valori di quei campi e tutto il contenuto** (description, istruzioni, esempi, commenti nel codice): in italiano. L'utilizzatore e il materiale tecnico di riferimento (norme UNI, letteratura italiana) sono in italiano; la description in italiano matcha meglio semanticamente le richieste dell'utente, che scrive sempre in italiano.
- Nomi di file/cartelle/skill (slug): kebab-case, in italiano (es. `verifica-trave-flessione`).

## Struttura di una skill

```
skills/<nome-skill>/
├── SKILL.md
├── scripts/       # eventuali script di calcolo (se necessari)
└── references/    # tabelle, formulari, estratti di norme
```

## Vincoli sul frontmatter (obbligatori, imposti da Claude)

- `name`: max 64 caratteri, solo lettere minuscole (a-z, niente accentate), numeri e trattini, niente tag XML, non può contenere "claude" o "anthropic". Deve coincidere con il nome della cartella della skill.
- `description`: non vuota, max 1024 caratteri, niente tag XML.

## Contenuto di SKILL.md

- Frontmatter con `name` e `description` accurati: la description determina quando Claude attiva la skill, deve descrivere chiaramente il caso d'uso (es. "verifica a fatica di un albero rotante sollecitato a flessione e torsione").
- Riportare sempre le **norme/riferimenti** usati (UNI, ISO, manuali) quando la skill implementa un metodo di calcolo codificato.
- Esplicitare le **ipotesi e i limiti di validità** del metodo di calcolo (es. campo di applicabilità di una formula).
- Preferire formule e simbologia standard della manualistica italiana di meccanica applicata/costruzione di macchine.

## Cosa evitare

- Non duplicare in una skill calcoli già coperti da un'altra: verificare prima le skill esistenti nel plugin.
- Non inventare valori numerici (coefficienti, tabelle) senza fonte: se manca il riferimento, chiederlo esplicitamente prima di scrivere la skill.