From 172bfde0e426d242078e5033cd53088efadfc64a Mon Sep 17 00:00:00 2001 From: Davide Grilli Date: Sat, 11 Jul 2026 23:32:56 +0200 Subject: [PATCH] Scaffold iniziale del marketplace di plugin per ingegneria meccanica Struttura marketplace.json + plugin machine-design, documentazione di architettura e linee guida per la scrittura delle skill. Co-Authored-By: Claude Sonnet 5 --- .claude-plugin/marketplace.json | 14 +++++ .gitignore | 3 ++ CLAUDE.md | 49 ++++++++++++++++++ README.md | 13 +++++ docs/architecture.md | 51 +++++++++++++++++++ docs/skill-guidelines.md | 33 ++++++++++++ .../machine-design/.claude-plugin/plugin.json | 8 +++ plugins/machine-design/CHANGELOG.md | 10 ++++ plugins/machine-design/README.md | 13 +++++ 9 files changed, 194 insertions(+) create mode 100644 .claude-plugin/marketplace.json create mode 100644 .gitignore create mode 100644 CLAUDE.md create mode 100644 README.md create mode 100644 docs/architecture.md create mode 100644 docs/skill-guidelines.md create mode 100644 plugins/machine-design/.claude-plugin/plugin.json create mode 100644 plugins/machine-design/CHANGELOG.md create mode 100644 plugins/machine-design/README.md diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json new file mode 100644 index 0000000..9d00000 --- /dev/null +++ b/.claude-plugin/marketplace.json @@ -0,0 +1,14 @@ +{ + "name": "mechanical-engineering-plugins", + "owner": { + "name": "Davide" + }, + "description": "Marketplace di plugin Claude per l'ingegneria meccanica: progettazione di organi meccanici, scienza dei materiali, meccanica applicata e tecnologia meccanica.", + "plugins": [ + { + "name": "machine-design", + "source": "./plugins/machine-design", + "description": "Skill per la progettazione e verifica di organi meccanici (alberi, cuscinetti, ingranaggi, collegamenti filettati, saldature, molle)." + } + ] +} diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..7cfd02b --- /dev/null +++ b/.gitignore @@ -0,0 +1,3 @@ +.DS_Store +*.log +node_modules/ diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..87fdb26 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,49 @@ +# 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//` 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// +├── .claude-plugin/plugin.json # manifest del plugin +├── skills//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//skills//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//` 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. diff --git a/README.md b/README.md new file mode 100644 index 0000000..88fb7cc --- /dev/null +++ b/README.md @@ -0,0 +1,13 @@ +# mechanical-engineering-plugins + +Marketplace di plugin Claude per l'ingegneria meccanica, pensato come supporto all'ufficio tecnico nella chat normale di Claude (web e tab Chat di Claude Desktop). + +## Installazione + +In Claude: Customize → Plugins → "+" → Add marketplace → Add from a repository, indicando l'URL di questo repository. Poi installare il plugin desiderato (es. `machine-design`). + +## Plugin disponibili + +- [machine-design](plugins/machine-design/README.md) — progettazione e verifica di organi meccanici. + +Vedi [docs/architecture.md](docs/architecture.md) per la struttura del repository e i plugin previsti in futuro. diff --git a/docs/architecture.md b/docs/architecture.md new file mode 100644 index 0000000..752cb36 --- /dev/null +++ b/docs/architecture.md @@ -0,0 +1,51 @@ +# Architettura del repository + +Questo repository è un **marketplace di plugin Claude** per l'ingegneria meccanica, pensato per essere usato come supporto all'ufficio tecnico nella chat normale di Claude (web e tab Chat di Claude Desktop), non nel tab "Code". + +## Come funziona l'installazione (target reale) + +Un plugin bundla più skill in un unico pacchetto installabile. Per installarlo: +1. In Claude: Customize → Plugins → "+" → Add marketplace → Add from a repository, indicando l'URL di questo repository. +2. Installare il plugin desiderato (es. `machine-design`): tutte le sue skill diventano disponibili in chat (web e tab Chat di Desktop) e in Cowork. + +Disponibile su tutti i piani a pagamento (Pro, Max, Team, Enterprise). Nota: hook e sub-agent eventualmente presenti in un plugin funzionano solo in Cowork, ma le skill funzionano ovunque. + +Questo è lo stesso formato marketplace.json/plugin.json usato da Claude Code — non serve nulla di diverso per il nostro target. + +## Plugin attivi + +- **machine-design** (`plugins/machine-design/`): progettazione e verifica di organi meccanici (alberi, cuscinetti, ingranaggi, collegamenti filettati, saldature, molle). + +## Plugin previsti (non ancora creati) + +Verranno aggiunti come nuova cartella in `plugins/` + entry in `.claude-plugin/marketplace.json` solo quando si inizia a lavorarci concretamente: + +- **engineering-materials**: scienza e tecnologia dei materiali (proprietà, trattamenti termici, criteri di scelta materiali). +- **applied-mechanics**: meccanica applicata alle macchine (cinematica, dinamica, vibrazioni, meccanismi). +- **manufacturing-engineering**: tecnologia meccanica e processi di produzione (lavorazioni, tolleranze e rugosità, saldatura come processo). + +## Perché non creare subito le cartelle vuote + +Una cartella placeholder senza skill reali non aiuta: meglio tenere qui il piano e creare la struttura di un nuovo plugin nel momento in cui si scrive la prima skill di quel dominio. + +## Struttura di un plugin + +``` +plugins// +├── .claude-plugin/ +│ └── plugin.json +├── skills/ +│ └── / +│ └── SKILL.md +├── README.md +└── CHANGELOG.md +``` + +## Vincoli reali sul frontmatter di SKILL.md + +Campi obbligatori: `name` e `description`. + +- `name`: max 64 caratteri, solo lettere minuscole/numeri/trattini, niente tag XML, non può contenere "claude" o "anthropic". +- `description`: non vuota, max 1024 caratteri, niente tag XML. Deve descrivere sia cosa fa la skill sia quando Claude deve usarla (guida l'attivazione automatica). + +Vedi [skill-guidelines.md](skill-guidelines.md) per le convenzioni di scrittura complete. diff --git a/docs/skill-guidelines.md b/docs/skill-guidelines.md new file mode 100644 index 0000000..8fb6df5 --- /dev/null +++ b/docs/skill-guidelines.md @@ -0,0 +1,33 @@ +# 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// +├── 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. diff --git a/plugins/machine-design/.claude-plugin/plugin.json b/plugins/machine-design/.claude-plugin/plugin.json new file mode 100644 index 0000000..fb29030 --- /dev/null +++ b/plugins/machine-design/.claude-plugin/plugin.json @@ -0,0 +1,8 @@ +{ + "name": "machine-design", + "description": "Skill per la progettazione e verifica di organi meccanici (alberi, cuscinetti, ingranaggi, collegamenti filettati, saldature, molle).", + "version": "0.1.0", + "author": { + "name": "Davide" + } +} diff --git a/plugins/machine-design/CHANGELOG.md b/plugins/machine-design/CHANGELOG.md new file mode 100644 index 0000000..f5620f3 --- /dev/null +++ b/plugins/machine-design/CHANGELOG.md @@ -0,0 +1,10 @@ +# Changelog + +Tutte le modifiche rilevanti a questo plugin sono documentate in questo file. + +Il formato si basa su [Keep a Changelog](https://keepachangelog.com/it/1.1.0/). + +## [Non rilasciato] + +### Aggiunto +- Struttura iniziale del plugin. diff --git a/plugins/machine-design/README.md b/plugins/machine-design/README.md new file mode 100644 index 0000000..4b4e3f7 --- /dev/null +++ b/plugins/machine-design/README.md @@ -0,0 +1,13 @@ +# machine-design + +Skill per la progettazione e verifica di organi meccanici: alberi, cuscinetti, ingranaggi, collegamenti filettati, saldature, molle. + +Le skill di questo plugin si installano tutte insieme aggiungendo questo repository come marketplace in Claude (Customize → Plugins → "+" → Add marketplace → Add from a repository) e installando il plugin `machine-design`. + +## Skill disponibili + +_Nessuna skill ancora presente._ + +## Convenzioni + +Vedi [docs/skill-guidelines.md](../../docs/skill-guidelines.md) nella root del repository.