--- name: doc-offerta description: "Crea offerte tecnico-economiche professionali in formato .docx da contenuti .md con infografiche AI generate da Gemini. Usa questa skill quando l'utente vuole creare un'offerta, proposta commerciale, proposta tecnica, preventivo, documento professionale con visual, o dice: genera offerta, crea proposta, converti in docx, offerta con infografiche, documento professionale." --- # doc-offerta — Documenti Professionali con Infografiche AI Crea offerte tecnico-economiche, proposte commerciali e documenti professionali in formato .docx partendo da contenuti Markdown, con infografiche generate automaticamente da Google Gemini AI. ## Prerequisiti - **Chiave API Google Gemini** caricata in uno di questi modi (in ordine di priorità): 1. `export GEMINI_API_KEY="..."` (convenzione primaria) 2. `export GOOGLE_API_KEY="..."` (alias accettato) 3. File `.env` con `GEMINI_API_KEY=...` — cercato automaticamente in CWD, directory ascendenti, directory dello script e `~/.env` 4. Flag CLI `--api-key "..."` - **Node.js 18+**: per gli script TypeScript - **Pacchetto npm `docx`**: `npm install docx` (nella directory del progetto o globale) - Opzionale: `sharp` per conversione SVG→PNG nel fallback Verifica rapida: ```bash # Test chiave + modello immagini attivo npx tsx doc-production/scripts/generate-infografica.ts --help npx tsx --version node -e "require('docx')" ``` ## Modello di generazione immagini Default: `gemini-3-pro-image-preview` (miglior qualità disponibile su Google AI Studio). Alias supportati via `--model`: | Alias | Modello reale | Uso | |-------|---------------|-----| | `best` / `pro` *(default)* | `gemini-3-pro-image-preview` | Offerte commerciali, documenti fine | | `nano` | `nano-banana-pro-preview` | Immagini espressive, stile illustrativo | | `flash-3` | `gemini-3.1-flash-image-preview` | Veloce, qualità elevata | | `fast` / `flash` | `gemini-2.5-flash-image` | Batch rapidi, molti asset | ## Template Aziendali Se `$ARGUMENTS` contiene `--template `: | Template | Tipo offerta | DOCX Template | Istruzioni | Placeholder | |----------|-------------|---------------|------------|-------------| | `nexadata` | Sviluppo software a commessa (corpo o T&M) | `Template_Offerta_NexaData.docx` | `ISTRUZIONI_TEMPLATE.md` | 31 placeholder `{{...}}` | | `iridia` | Servizio/prodotto SaaS (crediti, abbonamento) | `Template_Offerta_Iridia.docx` | `template-iridia.md` | placeholder `{{...}}` | ### Risoluzione path template (IMPORTANTE) **MAI usare path relativi** come `doc-production/skills/doc-offerta/references/...` — funzionano SOLO se CWD = root del repo MUCC, quindi falliscono in qualsiasi altro progetto. **Usa SEMPRE path assoluti** risolti via home dell'utente: ```bash # Path canonici (funzionano da QUALSIASI progetto) TEMPLATE_NEXADATA="$HOME/.claude/skills/doc-offerta/references/Template_Offerta_NexaData.docx" TEMPLATE_IRIDIA="$HOME/.claude/skills/doc-offerta/references/Template_Offerta_Iridia.docx" INSTRUCTIONS_NEXADATA="$HOME/.claude/skills/doc-offerta/references/ISTRUZIONI_TEMPLATE.md" INSTRUCTIONS_IRIDIA="$HOME/.claude/skills/doc-offerta/references/template-iridia.md" STYLE_CATALOG="$HOME/.claude/skills/doc-offerta/references/style-catalog.md" PROMPT_TEMPLATES="$HOME/.claude/skills/doc-offerta/references/prompt-templates.md" ``` Il path `~/.claude/skills/doc-offerta/` e un **symlink** all'installazione MUCC. Funziona sempre, indipendentemente da dove stai lanciando la skill. ### Mapping `--template ` → path Quando l'utente passa `--template iridia`, devi risolvere a: ``` $HOME/.claude/skills/doc-offerta/references/Template_Offerta_Iridia.docx ``` Quando l'utente passa `--template nexadata`, a: ``` $HOME/.claude/skills/doc-offerta/references/Template_Offerta_NexaData.docx ``` Prima di usarlo, **verifica con `ls` o `test -f`** che il file esista. Se non esiste, mostra errore esplicito con il path completo cercato, cosi l'utente sa dove guardare. ### Flusso con template DOCX (PREFERITO) Quando esiste un template `.docx` con placeholder: 1. **Raccogli dati**: chiedi all'utente i valori per ogni placeholder (o leggili da un .json) 2. **Genera contenuto**: per i placeholder di contenuto lungo (Descrizione_Offerta, Componenti, etc.), genera il testo completo 3. **Genera infografiche**: per ogni sezione che ne beneficia, genera l'infografica con Gemini 4. **Compila il template** usando path ASSOLUTO del template: ```bash # Per Iridia python3 "$HOME/.claude/skills/doc-offerta/../../scripts/compile-iridia-template.py" \ --template "$HOME/.claude/skills/doc-offerta/references/Template_Offerta_Iridia.docx" \ --data ./dati-offerta.json \ --images ./output/infografiche/ \ --output ./output/offerta-iridia.docx # Per NexaData python3 "$HOME/.claude/skills/doc-offerta/../../scripts/compile-template.py" \ --template "$HOME/.claude/skills/doc-offerta/references/Template_Offerta_NexaData.docx" \ --data ./dati-offerta.json \ --images ./output/infografiche/ \ --output ./output/offerta-nexadata.docx ``` **Come funzionano questi path**: - `$HOME/.claude/skills/doc-offerta` e un **symlink** al plugin MUCC installato - macOS (e Linux) risolvono il symlink PRIMA di processare `..`, quindi `../../scripts/` risolve a `doc-production/scripts/` dentro il repo - Il path e **assoluto**, funziona da qualsiasi progetto, CWD indipendente - Non servono path relativi tipo `doc-production/skills/...` che funzionano SOLO se lanci dal root del plugin 5. **Verifica**: controlla placeholder non sostituiti Questo approccio preserva tutta la formattazione, logo, stili e layout del template originale. ### Flusso senza template (da .md) Se nessun template DOCX e disponibile: 1. Leggi il reference del template per la struttura sezioni 2. Genera il .md con marker infografica automatici 3. Genera infografiche con Gemini 4. Assembla DOCX con `md-to-docx.ts` ### Formato dati JSON per compile-template.py ```json { "PROTOCOLLO": "ND.ENG.2026.095", "DATA_OFFERTA": " Roma 15/04/2026", "NOME_CLIENTE": "Acme Corporation S.p.A.", "INDIRIZZO_CLIENTE": "Via Roma 100", "CAP_CITTA_CLIENTE": "20100,", "PROVINCIA_CLIENTE": "Milano (MI)", "REFERENTE_CLIENTE": "Dott. Marco Bianchi", "TITOLO_OFFERTA": "Piattaforma E-commerce B2B", "TESTO_INTRODUTTIVO": "In relazione ai colloqui intercorsi...", "Descrizione_Offerta": "Il progetto prevede...", "Componenti_del_sistema": "2.1 Infrastruttura...\n2.2 Gestione...", "Team_di_progetto": "...", "Stima_dettagliata_di_impegno": "...", "PIANO_DI_SVILUPPO": "...", "MODALITA_CONTRATTUALE": "...", "ASSUNZIONE": "...", "RISCHIO": "...", "REF_COMMERCIALE_NOME": "Andrea Palermo", "REF_COMMERCIALE_EMAIL": "apalermo@nexadata.it", "REF_COMMERCIALE_TEL": "+39 339 229 5298", "REF_IT_NOME": "Maurizio Verde", "REF_IT_EMAIL": "mverde@nexadata.it", "REF_IT_TEL": "+39 335 499 007", "REF_AMM_NOME": "Gennaro Vallo", "REF_AMM_EMAIL": "gvallo@nexadata.it", "REF_AMM_TEL": "+39 351 568 2072", "FIRMATARIO": "Gennaro Vallo" } ``` ## Modalita Auto Se `$ARGUMENTS` contiene `--auto`: - Usa stile default del template (o `modern-light` senza template) - Non chiede conferme sulle infografiche da generare - Genera tutte le infografiche trovate nei marker - Annota nel log: "(modalita auto)" ## Workflow ### 1. Identifica il contenuto sorgente Se `$ARGUMENTS` contiene un path a file `.md`: - Leggi il file indicato Altrimenti: - Chiedi all'utente di fornire il contenuto (path a un .md, testo libero, o descrizione dell'offerta) - Se l'utente descrive a voce, genera tu il .md dell'offerta prima di procedere ### 1b. Auto-inserimento marker infografica **REGOLA CRITICA**: quando generi o modifichi un .md per un'offerta/proposta, DEVI inserire automaticamente i marker `` seguendo le regole in `references/auto-infografica-rules.md`. Leggi `references/auto-infografica-rules.md` per i 10 trigger automatici. In sintesi: - **Architettura/struttura** → marker architettura - **Processo/flusso/step** → marker processo - **Confronto A vs B** → marker confronto - **Timeline/roadmap** → marker timeline - **KPI/metriche** → marker KPI - **Pricing/pacchetti** → marker pricing - **Diagramma a blocchi** → marker diagramma - **Stack tecnologico** → marker stack - **Team/organigramma** → marker team - **Sicurezza** → marker sicurezza **Obiettivo**: ogni documento di 3+ pagine deve avere almeno 3-5 marker infografica, posizionati subito dopo il paragrafo introduttivo di ogni sezione visivamente ricca. Se il .md fornito dall'utente NON contiene marker: 1. Analizza il contenuto con le regole auto-infografica 2. Inserisci automaticamente i marker dove appropriato 3. Mostra all'utente: "Ho aggiunto N marker infografica nel documento" 4. Chiedi conferma prima di procedere alla generazione ### 2. Scegli lo stile Leggi `references/style-catalog.md` per i 5 stili disponibili. Presenta all'utente: ``` Stili disponibili per il documento: 1. Corporate Dark — Tech, cybersecurity, startup (navy scuro + rosso) 2. Modern Light — SaaS, digital agency, enterprise (bianco + blu) 3. Minimal — Design, architettura, luxury (bianco + nero + ambra) 4. Elegant Gold — Finance, legal, consulenza (navy + oro) 5. Tech Blue — DevOps, cloud, AI/ML (blu notte + sky blue) Quale stile preferisci? (default: 2 - Modern Light) ``` Se `--style ` e' in `$ARGUMENTS`, usa quello direttamente. Se `--auto`, usa `modern-light`. ### 3. Analizza il Markdown e identifica i punti infografica Parsa il file `.md` cercando i marker: ``` ``` Per ogni marker trovato: 1. Estrai la descrizione 2. Classifica il tipo: `processo`, `confronto`, `timeline`, `architettura`, `kpi`, `pricing` 3. Seleziona il prompt template appropriato da `references/prompt-templates.md` Se il .md NON contiene marker ma il contenuto ha sezioni che beneficerebbero di visual: - Suggerisci all'utente dove inserire infografiche - Chiedi conferma prima di procedere #### Auto-conversione blocchi Mermaid Se il .md contiene blocchi ` ```mermaid ``` ` (diagrammi, flowchart, Gantt, sequence), `md-to-docx.ts` li **converte automaticamente in marker infografica** estraendo le label dei nodi. In pratica: ogni `graph TD`, `graph LR`, `gantt`, `sequenceDiagram` diventa un'infografica generata da Gemini. Questo elimina il bug per cui il codice Mermaid raw veniva riversato come testo nel DOCX. Se vuoi un maggior controllo sulle descrizioni, **sostituisci manualmente** i blocchi Mermaid con marker espliciti `` PRIMA di invocare lo script. ### 4. Genera le infografiche con Gemini Per ogni marker ``: a. **Costruisci il prompt Gemini**: - Prendi il template da `references/prompt-templates.md` in base al tipo - Inietta la descrizione specifica dal marker - Inietta il "Gemini style prompt" dallo stile scelto (`references/style-catalog.md`) - Lingua: italiano (default) o come specificato b. **Chiama Gemini API**: ```bash npx tsx doc-production/scripts/generate-infografica.ts \ --prompt "il prompt completo" \ --style corporate-dark \ --output ./output/infografiche/ \ --name "infografica-01" ``` c. **Gestisci errori**: - 429 Rate Limit: attendi 30s, riprova (max 3 tentativi) - Safety block: riformula il prompt rimuovendo termini problematici - Nessuna immagine: il modello ha risposto solo testo — aggiungi "Generate an image, do not just describe it" - Dopo 3 fallimenti: genera un SVG programmatico come fallback d. **Mostra progresso**: "Infografica 2/5 generata: [nome]" ### 5. Assembla il documento DOCX ```bash npx tsx doc-production/scripts/md-to-docx.ts \ --input ./contenuto.md \ --style modern-light \ --images ./output/infografiche/ \ --output ./output/offerta-finale.docx ``` Lo script: 1. Parsa il .md in sezioni (heading, paragrafi, tabelle, liste, marker infografica) 2. Applica lo stile scelto (colori, font, margini) 3. Genera la **cover page** con: - Titolo dell'offerta - Nome cliente - Data - Logo placeholder (se fornito) - Barra accent dello stile scelto 4. Genera l'**indice** (Table of Contents) 5. Converte ogni sezione in elementi DOCX 6. Inserisce le infografiche generate nei punti marcati 7. Aggiunge **header** (titolo abbreviato) e **footer** (numero pagina + "Confidenziale") 8. Salva il .docx finale ### 6. Verifica e consegna Checklist pre-consegna: - [ ] DOCX aperto senza errori - [ ] Tutte le infografiche inserite e visibili - [ ] Cover page con dati corretti - [ ] Tabelle formattate correttamente - [ ] Numeri di pagina presenti - [ ] Stile coerente (colori, font) in tutto il documento Mostra all'utente: ``` Documento generato: ./output/offerta-finale.docx Contenuto: - N pagine - M infografiche generate - Stile: [nome stile] - Cover page: Si File infografiche singole in: ./output/infografiche/ ``` ## Formato Marker Infografica nel .md ```markdown ``` Esempi: ```markdown ``` ## Esempio d'uso ``` > /doc-offerta ./proposta-acme.md --style elegant-gold Leggo proposta-acme.md... Trovati 5 marker infografica: 1. [architettura] Panoramica soluzione 4 blocchi 2. [processo] Flusso gestione ordine 5 step 3. [architettura] Architettura tecnica React+FastAPI 4. [confronto] Custom vs SaaS 5. [timeline] Piano progetto 4 mesi Stile: Elegant Gold (navy + oro) Genero infografiche con Gemini... ✓ 1/5 — panoramica-soluzione.png ✓ 2/5 — flusso-ordine.png ✓ 3/5 — architettura-tecnica.png ✓ 4/5 — confronto-custom-saas.png ✓ 5/5 — piano-progetto.png Assemblo DOCX... ✓ Cover page ✓ Indice ✓ 7 sezioni + 5 infografiche ✓ Header/footer Documento generato: ./output/proposta-acme.docx (12 pagine) ``` ## Riferimenti - `references/style-catalog.md` — 5 stili predefiniti - `references/prompt-templates.md` — 6 template prompt Gemini - `references/sample-offerta.md` — Esempio completo di input .md ## Prossimo passo Dopo aver generato il documento: - Apri il .docx e verifica visivamente - Se serve, rigenerare singole infografiche con `/doc-infografica` - Per personalizzare ulteriormente lo stile, modifica `references/style-catalog.md`