Migliori pratiche per la creazione di Skills

## Estrai testo da PDF

Usa pdfplumber per l'estrazione del testo:

```python
import pdfplumber

with pdfplumber.open("file.pdf") as pdf:
    text = pdf.pages[0].extract_text()
```

## Estrai testo da PDF

PDF (Portable Document Format) sono un formato di file comune che contiene
testo, immagini e altri contenuti. Per estrarre testo da un PDF, dovrai
utilizzare una libreria. Ci sono molte librerie disponibili per l'elaborazione
dei PDF, ma consigliamo pdfplumber perché è facile da usare e gestisce bene
la maggior parte dei casi. Per prima cosa, dovrai installarla usando pip.
Quindi puoi usare il codice sottostante...

## Processo di revisione del codice

1. Analizza la struttura e l'organizzazione del codice
2. Controlla i potenziali bug o casi limite
3. Suggerisci miglioramenti per la leggibilità e la manutenibilità
4. Verifica l'aderenza alle convenzioni del progetto

## Genera report

Usa questo modello e personalizza secondo le necessità:

```python
def generate_report(data, format="markdown", include_charts=True):
    # Elabora i dati
    # Genera output nel formato specificato
    # Opzionalmente includi visualizzazioni
```

## Migrazione del database

Esegui esattamente questo script:

```bash
python scripts/migrate.py --verify --backup
```

Non modificare il comando o aggiungere flag aggiuntivi.

description: Estrai testo e tabelle da file PDF, compila moduli, unisci documenti. Usa quando lavori con file PDF o quando l'utente menziona PDF, moduli o estrazione di documenti.

description: Analizza fogli di calcolo Excel, crea tabelle pivot, genera grafici. Usa quando analizzi file Excel, fogli di calcolo, dati tabulari o file .xlsx.

description: Genera messaggi di commit descrittivi analizzando i diff di git. Usa quando l'utente chiede aiuto per scrivere messaggi di commit o per rivedere le modifiche in staging.

description: Aiuta con i documenti

description: Elabora i dati

description: Fa cose con i file

pdf/
├── SKILL.md              # Istruzioni principali (caricate quando attivate)
├── FORMS.md              # Guida alla compilazione di moduli (caricata secondo le necessità)
├── reference.md          # Riferimento API (caricato secondo le necessità)
├── examples.md           # Esempi di utilizzo (caricati secondo le necessità)
└── scripts/
    ├── analyze_form.py   # Script di utilità (eseguito, non caricato)
    ├── fill_form.py      # Script di compilazione moduli
    └── validate.py       # Script di convalida

---
name: pdf-processing
description: Estrae testo e tabelle da file PDF, compila moduli e unisce documenti. Usa quando lavori con file PDF o quando l'utente menziona PDF, moduli o estrazione di documenti.
---

# Elaborazione PDF

## Avvio rapido

Estrai testo con pdfplumber:
```python
import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
    text = pdf.pages[0].extract_text()
```

## Funzionalità avanzate

**Compilazione moduli**: Consulta [FORMS.md](FORMS.md) per la guida completa
**Riferimento API**: Consulta [REFERENCE.md](REFERENCE.md) per tutti i metodi
**Esempi**: Consulta [EXAMPLES.md](EXAMPLES.md) per i modelli comuni

bigquery-skill/
├── SKILL.md (panoramica e navigazione)
└── reference/
    ├── finance.md (metriche di ricavi, fatturazione)
    ├── sales.md (opportunità, pipeline)
    ├── product.md (utilizzo API, funzionalità)
    └── marketing.md (campagne, attribuzione)

# Elaborazione DOCX

## Creazione di documenti

Usa docx-js per nuovi documenti. Consulta [DOCX-JS.md](DOCX-JS.md).

## Modifica di documenti

Per modifiche semplici, modifica direttamente l'XML.

**Per modifiche tracciate**: Consulta [REDLINING.md](REDLINING.md)
**Per dettagli OOXML**: Consulta [OOXML.md](OOXML.md)

# SKILL.md
Consulta [advanced.md](advanced.md)...

# advanced.md
Consulta [details.md](details.md)...

# details.md
Ecco l'informazione effettiva...

# SKILL.md

**Utilizzo di base**: [istruzioni in SKILL.md]
**Funzionalità avanzate**: Consulta [advanced.md](advanced.md)
**Riferimento API**: Consulta [reference.md](reference.md)
**Esempi**: Consulta [examples.md](examples.md)

# Riferimento API

## Contenuti
- Autenticazione e configurazione
- Metodi principali (create, read, update, delete)
- Funzionalità avanzate (operazioni batch, webhook)
- Modelli di gestione degli errori
- Esempi di codice

## Autenticazione e configurazione
...

## Metodi principali
...

## Flusso di lavoro di sintesi della ricerca

Copia questa checklist e traccia il tuo progresso:

```
Progresso della ricerca:
- [ ] Passaggio 1: Leggi tutti i documenti di origine
- [ ] Passaggio 2: Identifica i temi chiave
- [ ] Passaggio 3: Fai riferimenti incrociati alle affermazioni
- [ ] Passaggio 4: Crea un riassunto strutturato
- [ ] Passaggio 5: Verifica le citazioni
```

**Passaggio 1: Leggi tutti i documenti di origine**

Rivedi ogni documento nella directory `sources/`. Nota gli argomenti principali e le prove di supporto.

**Passaggio 2: Identifica i temi chiave**

Cerca modelli tra le fonti. Quali temi appaiono ripetutamente? Dove le fonti concordano o discordano?

**Passaggio 3: Fai riferimenti incrociati alle affermazioni**

Per ogni affermazione principale, verifica che appaia nel materiale di origine. Nota quale fonte supporta ogni punto.

**Passaggio 4: Crea un riassunto strutturato**

Organizza i risultati per tema. Includi:
- Affermazione principale
- Prove di supporto dalle fonti
- Punti di vista conflittuali (se presenti)

**Passaggio 5: Verifica le citazioni**

Controlla che ogni affermazione faccia riferimento al documento di origine corretto. Se le citazioni sono incomplete, torna al Passaggio 3.

## Flusso di lavoro di compilazione moduli PDF

Copia questa checklist e spunta gli elementi man mano che li completi:

```
Progresso dell'attività:
- [ ] Passaggio 1: Analizza il modulo (esegui analyze_form.py)
- [ ] Passaggio 2: Crea mappatura dei campi (modifica fields.json)
- [ ] Passaggio 3: Convalida la mappatura (esegui validate_fields.py)
- [ ] Passaggio 4: Compila il modulo (esegui fill_form.py)
- [ ] Passaggio 5: Verifica l'output (esegui verify_output.py)
```

**Passaggio 1: Analizza il modulo**

Esegui: `python scripts/analyze_form.py input.pdf`

Questo estrae i campi del modulo e le loro posizioni, salvando in `fields.json`.

**Passaggio 2: Crea mappatura dei campi**

Modifica `fields.json` per aggiungere valori per ogni campo.

**Passaggio 3: Convalida la mappatura**

Esegui: `python scripts/validate_fields.py fields.json`

Correggi eventuali errori di convalida prima di continuare.

**Passaggio 4: Compila il modulo**

Esegui: `python scripts/fill_form.py input.pdf fields.json output.pdf`

**Passaggio 5: Verifica l'output**

Esegui: `python scripts/verify_output.py output.pdf`

Se la verifica fallisce, torna al Passaggio 2.

## Processo di revisione dei contenuti

1. Bozza dei tuoi contenuti seguendo le linee guida in STYLE_GUIDE.md
2. Rivedi rispetto alla checklist:
   - Controlla la coerenza della terminologia
   - Verifica che gli esempi seguano il formato standard
   - Conferma che tutte le sezioni richieste siano presenti
3. Se vengono trovati problemi:
   - Nota ogni problema con riferimento a sezione specifica
   - Rivedi il contenuto
   - Rivedi di nuovo la checklist
4. Procedi solo quando tutti i requisiti sono soddisfatti
5. Finalizza e salva il documento

## Processo di modifica di documenti

1. Fai le tue modifiche a `word/document.xml`
2. **Convalida immediatamente**: `python ooxml/scripts/validate.py unpacked_dir/`
3. Se la convalida fallisce:
   - Rivedi attentamente il messaggio di errore
   - Correggi i problemi nell'XML
   - Esegui di nuovo la convalida
4. **Procedi solo quando la convalida passa**
5. Ricostruisci: `python ooxml/scripts/pack.py unpacked_dir/ output.docx`
6. Testa il documento di output

Se stai facendo questo prima di agosto 2025, usa l'API vecchia.
Dopo agosto 2025, usa la nuova API.

## Metodo attuale

Usa l'endpoint API v2: `api.example.com/v2/messages`

## Modelli vecchi

<details>
<summary>API v1 legacy (deprecato 2025-08)</summary>

L'API v1 usava: `api.example.com/v1/messages`

Questo endpoint non è più supportato.
</details>

## Struttura del report

UTILIZZA SEMPRE questa struttura di template esatta:

```markdown
# [Titolo dell'analisi]

## Riassunto esecutivo
[Panoramica di una riga dei risultati chiave]

## Risultati chiave
- Risultato 1 con dati di supporto
- Risultato 2 con dati di supporto
- Risultato 3 con dati di supporto

## Raccomandazioni
1. Raccomandazione specifica e attuabile
2. Raccomandazione specifica e attuabile
```

## Struttura del report

Ecco un formato predefinito sensato, ma usa il tuo miglior giudizio in base all'analisi:

```markdown
# [Titolo dell'analisi]

## Riassunto esecutivo
[Panoramica]

## Risultati chiave
[Adatta le sezioni in base a quello che scopri]

## Raccomandazioni
[Personalizza al contesto specifico]
```

Adatta le sezioni secondo le necessità per il tipo di analisi specifico.

## Formato del messaggio di commit

Genera messaggi di commit seguendo questi esempi:

**Esempio 1:**
Input: Aggiunto autenticazione utente con token JWT
Output:
```
feat(auth): implementa autenticazione basata su JWT

Aggiungi endpoint di login e middleware di convalida token
```

**Esempio 2:**
Input: Corretto bug dove le date venivano visualizzate in modo errato nei report
Output:
```
fix(reports): correggi la formattazione della data nella conversione del fuso orario

Usa timestamp UTC in modo coerente in tutta la generazione dei report
```

**Esempio 3:**
Input: Aggiornate le dipendenze e refactored la gestione degli errori
Output:
```
chore: aggiorna dipendenze e refactor gestione degli errori

- Aggiorna lodash a 4.17.21
- Standardizza il formato di risposta degli errori su tutti gli endpoint
```

Segui questo stile: type(scope): breve descrizione, quindi spiegazione dettagliata.

## Flusso di lavoro di modifica di documenti

1. Determina il tipo di modifica:

   **Creazione di nuovo contenuto?** → Segui il "Flusso di lavoro di creazione" sottostante
   **Modifica di contenuto esistente?** → Segui il "Flusso di lavoro di modifica" sottostante

2. Flusso di lavoro di creazione:
   - Usa la libreria docx-js
   - Costruisci il documento da zero
   - Esporta nel formato .docx

3. Flusso di lavoro di modifica:
   - Estrai il documento esistente
   - Modifica direttamente l'XML
   - Convalida dopo ogni modifica
   - Ricompatta quando completato

{
  "skills": ["pdf-processing"],
  "query": "Estrai tutto il testo da questo file PDF e salvalo in output.txt",
  "files": ["test-files/document.pdf"],
  "expected_behavior": [
    "Legge con successo il file PDF usando una libreria appropriata di elaborazione PDF o uno strumento da riga di comando",
    "Estrae il contenuto di testo da tutte le pagine del documento senza perdere alcuna pagina",
    "Salva il testo estratto in un file denominato output.txt in un formato chiaro e leggibile"
  ]
}

**Cattivo esempio: Troppe scelte** (confuso):
"Puoi usare pypdf, o pdfplumber, o PyMuPDF, o pdf2image, o..."

**Buon esempio: Fornisci un predefinito** (con via di fuga):
"Usa pdfplumber per l'estrazione del testo:
```python
import pdfplumber
```

Per PDF scansionati che richiedono OCR, usa pdf2image con pytesseract invece."

def process_file(path):
    """Elabora un file, creandolo se non esiste."""
    try:
        with open(path) as f:
            return f.read()
    except FileNotFoundError:
        # Crea il file con contenuto predefinito invece di fallire
        print(f"File {path} non trovato, creazione predefinito")
        with open(path, 'w') as f:
            f.write('')
        return ''
    except PermissionError:
        # Fornisci un'alternativa invece di fallire
        print(f"Impossibile accedere a {path}, utilizzo predefinito")
        return ''

def process_file(path):
    # Semplicemente fallisci e lascia che Claude lo capisca
    return open(path).read()

# Le richieste HTTP in genere si completano entro 30 secondi
# Un timeout più lungo tiene conto delle connessioni lente
REQUEST_TIMEOUT = 30

# Tre tentativi bilanciano l'affidabilità rispetto alla velocità
# La maggior parte dei fallimenti intermittenti si risolvono al secondo tentativo
MAX_RETRIES = 3

TIMEOUT = 47  # Perché 47?
RETRIES = 5   # Perché 5?

## Script di utilità

**analyze_form.py**: Estrai tutti i campi del modulo da PDF

```bash
python scripts/analyze_form.py input.pdf > fields.json
```

Formato di output:
```json
{
  "field_name": {"type": "text", "x": 100, "y": 200},
  "signature": {"type": "sig", "x": 150, "y": 500}
}
```

**validate_boxes.py**: Controlla i riquadri di delimitazione sovrapposti

```bash
python scripts/validate_boxes.py fields.json
# Restituisce: "OK" o elenca i conflitti
```

**fill_form.py**: Applica i valori dei campi al PDF

```bash
python scripts/fill_form.py input.pdf fields.json output.pdf
```

## Analisi del layout del modulo

1. Converti PDF in immagini:
   ```bash
   python scripts/pdf_to_images.py form.pdf
   ```

2. Analizza ogni immagine di pagina per identificare i campi del modulo
3. Claude può vedere visivamente le posizioni e i tipi di campo

bigquery-skill/
├── SKILL.md (panoramica, punta ai file di riferimento)
└── reference/
    ├── finance.md (metriche di ricavi)
    ├── sales.md (dati della pipeline)
    └── product.md (analitiche di utilizzo)

Usa lo strumento BigQuery:bigquery_schema per recuperare gli schemi delle tabelle.
Usa lo strumento GitHub:create_issue per creare problemi.

**Cattivo esempio: Assume l'installazione**:
"Usa la libreria pdf per elaborare il file."

**Buon esempio: Esplicito sulle dipendenze**:
"Installa il pacchetto richiesto: `pip install pypdf`

Quindi usalo:
```python
from pypdf import PdfReader
reader = PdfReader("file.pdf")
```"