davide
172bfde0e4
Struttura marketplace.json + plugin machine-design, documentazione di architettura e linee guida per la scrittura delle skill. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
50 lines
3.7 KiB
Markdown
50 lines
3.7 KiB
Markdown
# 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.
|