--- name: doc-manuale description: "Genera manuali tecnici e manuali utente per webapp (.docx) professionali con screenshot Playwright inline, infografiche AI Gemini e template brandizzati NexaData/Iridia. Flusso md-driven: i capitoli del manuale sono liberamente strutturabili da un .md sorgente con heading VERI che alimentano il TOC. Supporta user guide, webapp manual, documentazione tecnica, runbook, SOP. Segue framework Diátaxis, Microsoft Style Guide, Google Tech Writing, WCAG 2.2. Usa questa skill quando l'utente dice manuale, user guide, manuale utente, manuale webapp, documentazione web app, guida utente, runbook, SOP, doc manuale." --- # doc-manuale — Manuali Utente Web App + Technical Docs (md-driven) Genera manuali professionali in formato .docx con **contenuto libero** strutturato da un .md sorgente: - Template guscio brandizzato (NexaData tecnico, Iridia commerciale) con cover + frontespizio + TOC + appendice supporto - **Capitoli e sotto-sezioni decisi dal .md sorgente** (non hard-coded): numerazione, titoli e gerarchia sono liberi - **Heading veri** (`# H1`, `## H2`, `### H3` nel .md → stili Heading 1/2/3 nel .docx → appaiono nel TOC) - **Screenshot inline**: marker `` inserisce l'immagine subito dopo il testo - **Infografiche inline**: marker `` ugualmente inline - **Blockquote stilizzati**: `> **NOTA:**`, `> **ATTENZIONE:**`, `> **TIP:**` diventano callout con emoji - **Tabelle markdown** renderizzate con stile Table Grid del template - Conformita: **Diátaxis** (tutorial/how-to/reference/explanation), **Microsoft Style Guide** (verbi UI), **WCAG 2.2** ## Architettura skill vs agente (v0.3.4+) La knowledge di **"come si scrive un manuale"** (Diátaxis, Microsoft Style, WCAG, schema procedura) vive nell'agente **@Giorgio (Doc Writer)** del plugin brainstorming, non in questa skill. - **Skill** (questo file) → workflow operativo: quali script lanciare, in che ordine, con quali flag, quale template usare, come gestire i marker screenshot, come compilare il .docx finale. - **Agente @Giorgio** → expertise di dominio: regole di writing, framework Diátaxis, terminologia UI Microsoft, accessibilita WCAG, schema procedura. Single source of truth. Beneficio: se domani aggiorni WCAG o cambi le regole procedura, lo fai in UN posto (l'agente) e tutte le skill che producono documenti lo usano consistente. I reference di writing in `$HOME/.claude/skills/doc-manuale/references/` sono **copie legacy** mantenute per compat retro finche tutti i workflow puntano al path agente. ## Cambio rispetto a v0.3.2 (importante) **Vecchio flusso (obsoleto)**: template con 27 placeholder fissi `{{INTRODUZIONE}}` / `{{CAPITOLO_TITOLO}}` / `{{CAPITOLO_CONTENUTO}}` ecc., riempiti da JSON. Problemi: numerazione hard-coded in conflitto con contenuto utente, screenshot confinati in appendice separata, TOC incoerente. **Nuovo flusso (v0.3.3+)**: - Template guscio minimo (solo 11 placeholder metadata: titolo, versione, autore, email supporto, ecc.) - **Contenuto libero** da un .md sorgente - Marker screenshot/infografica inline PROCESSED dal nuovo script `compile-manuale.py` - Heading nel .md mantengono il loro stile gerarchico e popolano il TOC in modo coerente ## Quando usarla ### Manuali utente webapp (flusso principale) - Manuale utente di applicazione web (dashboard, gestionale, SaaS) - Guida a flussi e procedure con screenshot reali dell'app - Help online da esportare in PDF accessibile - Onboarding materiale per nuovi utenti ### Altri tipi manuale - Documentazione tecnica per sviluppatori (API, SDK, integrazioni) - Runbook operativo (procedure IT, sysadmin, incident response) - SOP (Standard Operating Procedure) - Guida installazione / configurazione software Per offerte commerciali usa `/doc-offerta`. Per marketing usa `/doc-marketing`. Per report di analisi usa `/doc-report`. Per presentazioni board usa `/doc-presentazione`. ## Chiavi API richieste | Chiave | Scopo | Dove impostarla | |--------|-------|-----------------| | `GEMINI_API_KEY` | Infografiche | `~/.env` o `~/.zshrc` (`export GEMINI_API_KEY="..."`) | | — | Screenshot webapp | Non serve API: usa Playwright locale (`npm install -g playwright && npx playwright install chromium`) | ## Sintassi ``` /doc-manuale [OPZIONI] ``` ### Opzioni base - `--brand iridia|nexadata` — brand del template (default: `iridia` per user-guide, `nexadata` per runbook/tecnico) - `--output ` — path .docx output - `--auto` — modalita non interattiva (tutti i default, nessuna conferma) - `--metadata ` — metadata file (titolo, versione, autore, ecc.) ### Opzioni modalita webapp - `--url ` — attiva modalita webapp: genera screenshot reali - `--credentials ` — credenziali login automatico - `--viewport desktop|tablet|mobile` — viewport default screenshot - `--headless` — Playwright in background (default true) - `--skip-screenshots` — forza disattivazione screenshot anche se `--url` passato - `--tipo-manuale user-webapp|user-generic|technical|runbook|sop` — override auto-detection Se `` non fornito: chiedi descrizione prodotto/sistema da manualare. ## Auto-detection tipo manuale | Trigger nel testo/prompt | Tipo applicato | |--------------------------|----------------| | "web app", "applicazione web", "dashboard web", "SaaS", URL passato con `--url` | `user-webapp` | | "manuale utente", "guida utente" (senza webapp) | `user-generic` | | "API", "SDK", "sviluppatori" | `technical` | | "runbook", "incident", "sysadmin", "procedure IT" | `runbook` | | "SOP", "procedura aziendale", "compliance" | `sop` | ## Template guscio Path canonici: ```bash TEMPLATE_IRIDIA="$HOME/.claude/skills/doc-offerta/references/templates-variants/Template_Manuale_Iridia.docx" TEMPLATE_NEXADATA="$HOME/.claude/skills/doc-offerta/references/templates-variants/Template_Manuale_NexaData.docx" ``` Struttura del guscio (fissa): 1. **Cover page**: `{{TITOLO_MANUALE}}`, `{{VERSIONE}}`, `{{DATA_PUBBLICAZIONE}}`, `{{AUTORE}}`, `{{AZIENDA}}` 2. **Frontespizio**: Informazioni sul documento + Cronologia versioni (tabella) 3. **Indice** (campo TOC auto-aggiornato in Word) 4. **`<<>>`** ← qui `compile-manuale.py` inietta il .md parsato 5. **Supporto** (appendice finale con `{{EMAIL_SUPPORTO}}`, `{{TELEFONO_SUPPORTO}}`, `{{SITO_SUPPORTO}}`) Placeholder totali: **11** (tutti metadata, zero placeholder di contenuto). ## Metadata JSON (formato) ```json { "TITOLO_MANUALE": "Manuale Utente Presenta", "VERSIONE": "1.0", "DATA_PUBBLICAZIONE": "23 Aprile 2026", "AUTORE": "Team Iridia", "AZIENDA": "Iridia S.r.l.", "DESCRIZIONE_BREVE": "la webapp Presenta per gestione presentazioni", "PUBBLICO_TARGET": "commerciali Iridia e agency partner", "EMAIL_SUPPORTO": "support@iridia.it", "TELEFONO_SUPPORTO": "+39 06 1234567", "SITO_SUPPORTO": "https://iridia.it/supporto" } ``` ## Reference da consultare La knowledge di **come si scrive un manuale utente** vive nell'agente **@Giorgio (Doc Writer)** del plugin brainstorming — non in questa skill. Questo separa il workflow operativo (qui) dalla expertise di dominio (Giorgio). ### Knowledge di writing (dominio Giorgio) - **`$HOME/.claude/agents/references/doc-writer/manual-writing.md`** — Framework Diátaxis + Microsoft Style + WCAG 2.2 + troubleshooting Atlassian + checklist 13 punti pre-pubblicazione - **`$HOME/.claude/agents/references/doc-writer/manual-procedure-template.md`** — Template copia-incolla per singola procedura In alternativa (se il symlink agenti non e attivo) puoi leggerli dal repo: - `brainstorming/agents/references/doc-writer/manual-writing.md` - `brainstorming/agents/references/doc-writer/manual-procedure-template.md` **Prima di generare il contenuto del manuale, leggi questi due file** per applicare Diátaxis, terminologia UI, schema procedura Microsoft, accessibilita WCAG. ### Workflow tecnico (dominio skill) - **`$HOME/.claude/skills/doc-manuale/references/auto-screenshot-rules.md`** — Sintassi marker ``, 8 trigger automatici, credentials format per Playwright ### Copia legacy (compat, sara rimossa in 0.4.0) - `$HOME/.claude/skills/doc-manuale/references/webapp-manual-guidelines.md` — **deprecato**: duplicato del file nell'agente. Mantenuto per compat finche tutti i path sono aggiornati. - `$HOME/.claude/skills/doc-manuale/references/procedure-template.md` — **deprecato**: idem. ## Sintassi Markdown supportata dal parser Il .md sorgente può usare: | Markdown | Output .docx | |----------|--------------| | `# Titolo` (H1) | Heading 1 → TOC | | `## Titolo` (H2) | Heading 2 → TOC | | `### Titolo` (H3) | Heading 3 → TOC | | `paragrafo su piu righe` | Body Text | | `**bold**` | Grassetto inline | | `*italic*` | Corsivo inline | | `` `code` `` | Font monospace inline | | `- item` / `* item` / `• item` | List Paragraph (unordered, bullet) | | `1. item` / `2. item` | List Paragraph (ordered, numerata) | | ` ```lang \n codice \n ``` ` | Code block monospace | | tabella markdown con `\|` | Tabella .docx con stile Table Grid | | `> testo` | Blockquote generico | | `> **NOTA:** testo` | Callout NOTA con emoji 📝 | | `> **ATTENZIONE:** testo` | Callout ATTENZIONE con emoji ⚠️ | | `> **TIP:** testo` | Callout SUGGERIMENTO con emoji 💡 | | `` | Immagine inline + Caption sotto | | `` | Immagine inline + Caption sotto | ### Marker screenshot / infografica — parametri ```markdown ``` - `file` (required): path relativo a `--images-dir` oppure assoluto - `caption` (opzionale): testo didascalia (stile Caption, centrato) - `width` (opzionale, default 15): larghezza in cm - `alt` (opzionale): alt text per accessibilita (default = caption) ## Workflow completo (user-webapp con screenshot) ### 1. Delega a @Giorgio per la knowledge di writing Prima di generare contenuto, **leggi il reference di Giorgio**: ``` $HOME/.claude/agents/references/doc-writer/manual-writing.md ``` (Fallback repo: `brainstorming/agents/references/doc-writer/manual-writing.md`) Applica da quel file: - Struttura Diátaxis (Tutorial/How-to/Reference/Explanation) - Terminologia UI Microsoft (Seleziona, Inserisci, Attiva) - Schema procedura Microsoft+Google - Troubleshooting 4 colonne (Atlassian) - Accessibilita WCAG 2.2 AA Se l'utente lancia questa skill chiedendo di invocare esplicitamente l'agente (es. "fai scrivere a Giorgio"), puoi aprire una sotto-task e passarla a `@Giorgio` usando il plugin brainstorming. Altrimenti, applica direttamente le regole dal reference. ### 2. Genera il .md sorgente Struttura tipica per user-webapp (liberamente adattabile — la numerazione può seguire qualunque schema perche i heading sono VERI nel .docx): ```markdown # Introduzione [scopo + destinatari] ## Obiettivi del manuale ## Pubblico destinatario ## Convenzioni tipografiche # Primo accesso [tutorial guidato] ## Accedere all'applicazione [procedura numerata] ## Recuperare la password # Dashboard e navigazione # Procedure operative ## Creare una richiesta ## Modificare una richiesta ## Cercare e filtrare # Sezioni per ruolo ## Utente base ## Responsabile ## Amministratore # Riferimento ## Campi e stati ## Icone e pulsanti ## Permessi # Risoluzione problemi [tabella 4 colonne: Problema | Causa | Soluzione | Quando contattare supporto] # FAQ # Glossario ``` Non scrivere "vedi sezione 2.1" o "come visto nel capitolo 3" — usa rimandi **per titolo**: "Vedi la sezione **Recuperare la password**". ### 3. Screenshot reali con Playwright (se `--url`) ```bash # Step 3a: genera screenshot da marker + update del .md npx tsx "$HOME/.claude/skills/doc-offerta/../../scripts/capture-screenshots.ts" \ --input ./manuale-presenta.md \ --url https://presenta.iridia.tech \ --credentials ./presenta-credentials.json \ --output ./output/screenshots/ \ --update-md \ --output-md ./manuale-presenta.with-screenshots.md ``` Gli screenshot finiscono in `./output/screenshots/` e il .md viene aggiornato sostituendo i marker con `![alt](path.png)` — ma per avere immagini inline + Caption è meglio **lasciare i marker** e far gestire l'inserimento a `compile-manuale.py` (step 5). ### 4. Infografiche Gemini (opzionale) ```bash npx tsx "$HOME/.claude/skills/doc-offerta/../../scripts/generate-infografica.ts" \ --prompt "flusso autenticazione SSO con OAuth e JWT" \ --style modern-light \ --output ./output/infografiche/ \ --name "manuale-auth-flow" ``` Poi aggiungi al .md: ```markdown ``` ### 5. Compila il .docx ```bash python3 "$HOME/.claude/skills/doc-offerta/../../scripts/compile-manuale.py" \ --template "$HOME/.claude/skills/doc-offerta/references/templates-variants/Template_Manuale_Iridia.docx" \ --md ./manuale-presenta.md \ --metadata ./metadata.json \ --images-dir ./output \ --output ./output/manuale-presenta.docx ``` `--images-dir` è la directory base dove risolvere i path relativi dei marker screenshot/infografica. ### 6. Verifica output Apri in Word e controlla: - [ ] **Cover**: titolo, versione, data, autore (no `{{...}}` residui) - [ ] **TOC**: click destro → "Aggiorna intero sommario" → mostra TUTTI i titoli del tuo .md - [ ] **Gerarchia heading**: H1 grande, H2 medio, H3 piccolo — visibile - [ ] **Screenshot**: inline nel punto giusto (subito dopo il testo di riferimento), con Caption centrata - [ ] **Procedure numerate**: 1. 2. 3. invece di bullet - [ ] **Tabelle**: con bordi e header in grassetto - [ ] **Callout NOTA/ATTENZIONE/TIP**: con emoji e indentati - [ ] **No duplicati** di titoli (fix v0.3.1) - [ ] **Appendice Supporto**: in fondo con contatti da metadata - [ ] **Header/Footer brand** su tutte le pagine ## Modalita Auto (`--auto`) - Brand: `iridia` (adatto user-guide) - Tipo: auto-detection (web-app se URL o testo coerente) - Stile infografiche: `modern-light` - Viewport screenshot: `desktop` - Headless Playwright: true - Output: `./output/manuale-{timestamp}.docx` ## Esempi d'uso ### Manuale utente webapp completo ```bash # 1. Genera screenshot da URL con login demo npx tsx ~/.claude/skills/doc-offerta/../../scripts/capture-screenshots.ts \ --input manuale-presenta.md \ --url https://presenta.iridia.tech \ --credentials /tmp/presenta-credentials.json \ --output ./output/screenshots/ # 2. Compila .docx python3 ~/.claude/skills/doc-offerta/../../scripts/compile-manuale.py \ --template ~/.claude/skills/doc-offerta/references/templates-variants/Template_Manuale_Iridia.docx \ --md manuale-presenta.md \ --metadata metadata.json \ --images-dir ./output/screenshots \ --output ./output/manuale-presenta.docx ``` ### Runbook IT (no webapp, no screenshot) ```bash python3 ~/.claude/skills/doc-offerta/../../scripts/compile-manuale.py \ --template ~/.claude/skills/doc-offerta/references/templates-variants/Template_Manuale_NexaData.docx \ --md runbook-incident-response.md \ --metadata metadata.json \ --output ./output/runbook.docx ``` ### Claude genera tutto (da prompt) ``` /doc-manuale --brand iridia --url https://presenta.iridia.tech --auto ``` Claude: 1. Chiede descrizione applicazione e audience 2. Genera il .md strutturato Diátaxis con marker screenshot 3. Lancia Playwright per catturare screenshot 4. Compila con `compile-manuale.py` 5. Restituisce `.docx` finale in `./output/` ## Best practice contenuto 1. **Titoli orientati all'azione**: "Creare una richiesta" non "Nuove richieste" 2. **Verbi Microsoft Style**: Seleziona (non clicca/premi/tocca) 3. **Stessa label dell'UI** in grassetto: `Seleziona **Salva bozza**` 4. **Ogni procedura**: scopo + prerequisiti + passi numerati + risultato atteso + errori comuni 5. **Troubleshooting a 4 colonne**: Problema | Causa | Soluzione | Quando contattare supporto 6. **Screenshot inline + Caption**: `` 7. **Rimandi per titolo** non per numero: "Vedi **Recuperare la password**" non "Vedi sezione 2.1" 8. **Gerarchia heading corretta**: no salti H1 → H3 9. **Alt text nei marker**: `alt="descrizione"` per accessibilita 10. **Cronologia versioni** (tabella già nel template) da aggiornare a ogni release ## Script disponibili - **`compile-manuale.py`** (v0.3.3+) — compila guscio + .md con marker inline - **`capture-screenshots.ts`** (v0.3.2) — cattura screenshot Playwright dai marker - **`generate-infografica.ts`** — genera infografiche Gemini - **`compile-template.py`** (legacy) — per altri tipi documento con placeholder fissi - **`create-template-variant.py`** — rigenera template guscio se necessario ## File correlati - Template: `$HOME/.claude/skills/doc-offerta/references/templates-variants/Template_Manuale_{Iridia,NexaData}.docx` - Script compile manuale: `$HOME/.claude/skills/doc-offerta/../../scripts/compile-manuale.py` - Script screenshot: `$HOME/.claude/skills/doc-offerta/../../scripts/capture-screenshots.ts` - Script infografica: `$HOME/.claude/skills/doc-offerta/../../scripts/generate-infografica.ts` - **Knowledge writing (Giorgio)**: - `$HOME/.claude/agents/references/doc-writer/manual-writing.md` - `$HOME/.claude/agents/references/doc-writer/manual-procedure-template.md` - **Workflow tecnico (skill)**: - `$HOME/.claude/skills/doc-manuale/references/auto-screenshot-rules.md` - **Legacy (deprecato v0.3.4+, rimosso v0.4.0)**: - `$HOME/.claude/skills/doc-manuale/references/webapp-manual-guidelines.md` (copia) - `$HOME/.claude/skills/doc-manuale/references/procedure-template.md` (copia) ## Limitazioni note - **Cronologia versioni**: la tabella nel template è vuota per default. Per popolarla bisogna modificare il .docx in Word dopo la generazione, oppure in futuro estendere `compile-manuale.py` per accettare array di versioni nei metadata. - **Pagebreak manuali**: non supportati dal parser markdown. Se serve forzare un cambio pagina, usa il workaround Word (Ctrl+Invio) nel .docx finale. - **Immagini SVG**: python-docx supporta solo PNG/JPG. Converti SVG in PNG prima. ## Prossimo passo Dopo la generazione: - Apri il .docx e aggiorna l'indice (click destro → Aggiorna intero sommario) - Verifica screenshot inline (sostituibili con altri custom) - Raccogli feedback da utenti reali sulle procedure principali - Aggiorna cronologia versioni con ogni release Per offerte commerciali legate al prodotto: `/doc-offerta`. Per materiale marketing: `/doc-marketing`.