mechanical-engineering-plugins/CLAUDE.md

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

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.