# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Cos'è questo repository

Marketplace di plugin Claude per l'ingegneria meccanica (`.claude-plugin/marketplace.json`), pensato come supporto per un ufficio tecnico che usa la chat normale di Claude (web e tab Chat di Claude Desktop) — non il tab "Code". È lo stesso formato marketplace.json/plugin.json di Claude Code, ma il target di installazione è Customize → Plugins in Claude, non la CLI. Ogni plugin in `plugins/<nome-plugin>/` raggruppa skill relative a un sotto-dominio dell'ingegneria meccanica. Ad oggi esiste un solo plugin, `machine-design` (progettazione e verifica di organi meccanici). Altri plugin previsti sono elencati in [docs/architecture.md](docs/architecture.md) ma non vanno creati finché non si inizia a scriverne davvero le skill.

Non esiste ancora build/lint/test tooling: il repository contiene solo manifest JSON e skill in markdown. Se in futuro si aggiungono script di calcolo con dipendenze (es. Python), documentare qui i comandi per eseguirli/testarli.

## Struttura

```
.claude-plugin/marketplace.json      # manifest del marketplace, elenca i plugin
plugins/<nome-plugin>/
├── .claude-plugin/plugin.json       # manifest del plugin
├── skills/<nome-skill>/SKILL.md     # una skill per cartella, auto-discovered
├── README.md
└── CHANGELOG.md
docs/
├── architecture.md                  # piano dei plugin, perché non si creano cartelle vuote
└── skill-guidelines.md              # convenzioni di lingua e struttura per le skill
```

## Convenzione di lingua (importante)

- Campi schema (`name`, `description`, `version` nei manifest e nel frontmatter SKILL.md) sono chiavi fisse in inglese, non tradurre.
- Tutto il resto — valori di quei campi, contenuto delle skill, commenti nel codice, documentazione — **in italiano**. L'utilizzatore e il materiale tecnico di riferimento (norme UNI, manualistica) sono in italiano.
- Slug di file/cartelle/skill: kebab-case in italiano.

Dettagli completi in [docs/skill-guidelines.md](docs/skill-guidelines.md).

Vincoli reali sul campo `name` del frontmatter SKILL.md (imposti da Claude, non convenzione nostra): max 64 caratteri, solo lettere minuscole a-z/numeri/trattini (niente accentate), non può contenere "claude" o "anthropic". `description`: non vuota, max 1024 caratteri.

## Workflow per aggiungere una skill

1. Verificare in `plugins/machine-design/README.md` (o nel plugin pertinente) che la skill non esista già o sovrapponga una esistente.
2. Creare `plugins/<plugin>/skills/<nome-skill-kebab-case>/SKILL.md` con frontmatter `name`/`description` accurati (la description guida l'attivazione automatica della skill).
3. Citare sempre la norma/riferimento (UNI, ISO, manuale) su cui si basa un metodo di calcolo, ed esplicitare ipotesi/limiti di validità.
4. Aggiornare `README.md` e `CHANGELOG.md` del plugin.
5. Non inventare valori numerici (coefficienti, tabelle) senza fonte: se manca il riferimento, chiederlo all'utente prima di scrivere la skill.

## Workflow per aggiungere un nuovo plugin

Solo quando si inizia a scrivere skill reali per quel dominio: creare `plugins/<nome>/` con la struttura standard (vedi sopra), aggiungere l'entry in `.claude-plugin/marketplace.json`, aggiornare `docs/architecture.md` spostando il plugin da "previsti" ad "attivi".

## Come collaborare in questo repository

L'utente vuole un confronto attivo, non una semplice esecuzione di richieste: se una proposta (struttura, formula, ipotesi di calcolo) sembra imprecisa o migliorabile, dirlo esplicitamente e motivare l'alternativa prima di implementare, invece di procedere e basta.