my-skills/skills/pdf.md

# pdf

- **Autore:** Anthropic
- **Repository:** [anthropics/skills](https://github.com/anthropics/skills), la raccolta di skill di esempio di Anthropic
- **Sorgente:** [skills/pdf/SKILL.md](https://github.com/anthropics/skills/blob/main/skills/pdf/SKILL.md), con le guide [forms.md](https://github.com/anthropics/skills/blob/main/skills/pdf/forms.md) e [reference.md](https://github.com/anthropics/skills/blob/main/skills/pdf/reference.md) e una cartella `scripts/`
- **Pagina su skills.sh:** [anthropics/skills/pdf](https://skills.sh/anthropics/skills/pdf)
- **Diffusione (ottobre 2026):** circa 219.700 installazioni (su skills.sh dal 20 gennaio 2026); il repository ha circa 184.900 stelle e 21.900 fork su GitHub
- **Controlli di sicurezza su skills.sh:** Gen Agent Trust Hub e Socket superati; Snyk segnala un avviso (la pagina non spiega il motivo)
- **Licenza:** proprietaria (termini in `LICENSE.txt`). Il README del repository precisa che le skill per i documenti (`docx`, `pdf`, `pptx`, `xlsx`) sono *source-available*, non open source, e che le skill del repository sono dimostrative: conviene provarle bene prima di affidarsi a loro.

## A cosa serve

Dà all'agente un metodo per lavorare sui file PDF: leggerli, unirli e dividerli, compilarli, crearne di nuovi e ripulire quelli scansionati. Invece di improvvisare ogni volta con la libreria che gli viene in mente, sceglie lo strumento indicato per ciascun compito.

## Cosa fa

### Quando si attiva

Ogni volta che la richiesta riguarda un file PDF o la sua creazione:

- leggere o estrarre testo e tabelle, leggere i metadati;
- unire più PDF in uno, dividerne uno in più file, ruotare le pagine;
- aggiungere una filigrana;
- creare un PDF nuovo;
- compilare un modulo;
- proteggere con password o togliere la password;
- estrarre le immagini incorporate;
- fare l'OCR di un PDF scansionato per renderlo ricercabile.

### Come lavora

L'agente sceglie lo strumento in base al compito:

| Compito | Strumento | Come |
|---|---|---|
| Unire | pypdf | aggiunge le pagine di ogni file a un unico file di uscita |
| Dividere | pypdf | scrive una pagina per file |
| Estrarre il testo | pdfplumber | testo pagina per pagina, con il layout |
| Estrarre le tabelle | pdfplumber | tabelle pagina per pagina; si possono convertire in pandas ed esportare in Excel |
| Creare PDF | reportlab | `Canvas` per impaginazioni semplici, `Platypus` per documenti di più pagine con testo che scorre |
| Unire da riga di comando | qpdf | opzione `--empty --pages` |
| OCR | pytesseract | prima converte le pagine in immagini con pdf2image |
| Compilare moduli | pdf-lib o pypdf | segue `forms.md` |

Esempio di unione, dalla guida:

```python
from pypdf import PdfWriter, PdfReader

writer = PdfWriter()
for pdf_file in ["doc1.pdf", "doc2.pdf", "doc3.pdf"]:
    reader = PdfReader(pdf_file)
    for page in reader.pages:
        writer.add_page(page)

with open("merged.pdf", "wb") as output:
    writer.write(output)
```

Altre operazioni previste:

- **Strumenti da riga di comando:** `pdftotext` (poppler-utils) per estrarre il testo, anche con il layout o solo un intervallo di pagine; `qpdf` per unire, dividere per intervallo, ruotare pagine e togliere una password; `pdftk` se è installato.
- **Filigrane:** carica una pagina di filigrana e la sovrappone a ogni pagina.
- **Immagini:** `pdfimages` esporta le immagini incorporate.
- **Password:** copia le pagine in un nuovo file e lo cifra con password utente e proprietario.
- **Pedici e apici:** nei PDF creati con reportlab non usa i caratteri Unicode per pedici e apici, perché i font integrati non li hanno e compaiono come quadrati neri; usa i marcatori `<sub>` e `<super>` dentro i `Paragraph`.
- **Casi avanzati:** `reference.md` copre pypdfium2, pdf-lib per JavaScript e la risoluzione dei problemi. Non l'ho letto per intero.

### Compilare i moduli

Il flusso è in `forms.md` e dipende dal tipo di PDF. Il primo passo è controllare se il modulo ha campi compilabili (`scripts/check_fillable_fields.py`).

**PDF con campi compilabili:**

1. `extract_form_field_info.py` elenca i campi (identificatore, pagina, posizione, tipo: testo, casella, gruppo di opzioni, scelta).
2. `convert_pdf_to_images.py` crea un'immagine per pagina, per capire a cosa serve ogni campo.
3. Si scrive `field_values.json` con i valori da inserire.
4. `fill_fillable_fields.py` compila il modulo; se segnala errori, si correggono e si rilancia.

**PDF senza campi compilabili:**

1. `extract_form_structure.py` estrae etichette, linee, caselle e righe.
2. Due approcci: *strutturale* (preferito, se ci sono etichette di testo utili) o *visivo* (per le scansioni, con ingrandimenti fatti con ImageMagick); si possono combinare.
3. `check_bounding_boxes.py` valida i riquadri, perché riquadri sovrapposti o troppo piccoli rovinano il testo.
4. `fill_pdf_form_with_annotations.py` scrive il testo come annotazioni.
5. Si controlla il risultato rendendolo di nuovo in immagini.

Avvertenze della guida: i passi vanno fatti in ordine; identificatori e valori devono coincidere con quelli estratti; l'estrazione strutturale riconosce solo le caselle quadrate; i sistemi di coordinate dei campi compilabili e dell'approccio strutturale hanno origini diverse, e mescolarli sposta il testo; il risultato va sempre controllato a vista.

### Da sapere

- **Requisiti:** librerie Python pypdf, pdfplumber, reportlab, pandas (per esportare le tabelle), pytesseract e pdf2image (per l'OCR); strumenti poppler-utils e qpdf, pdftk facoltativo; ImageMagick per l'approccio visivo dei moduli. Per l'OCR serve anche il programma Tesseract (installato a parte; la guida non lo spiega).
- **Script eseguiti:** per i moduli l'agente lancia gli script della cartella `scripts/` (otto file Python). Non li ho letti uno per uno.
- **Nessun accesso esterno** dichiarato: lavora sui file locali.
- **Limite di fedeltà:** estrazione e OCR non sono perfette su layout complessi o scansioni di bassa qualità; l'autore invita a verificare il risultato.

## Installazione

### Claude Code e Codex

```bash
npx skills add anthropics/skills --skill pdf -g -a codex -a claude-code
```

| Opzione | Significato |
|---|---|
| `--skill pdf` | installa solo questa skill del repository |
| `-g` | installazione globale (`~/.claude/skills/`, `~/.codex/skills/`); senza, solo nel progetto corrente (`.claude/skills/`, `.agents/skills/`) |
| `-a <agente>` | agente di destinazione, ripetibile (`claude-code`, `codex`, ...) |
| `-y` | salta le domande di conferma |
| `--copy` | copia i file invece di creare collegamenti simbolici |

Non ho trovato il comando esatto sulla pagina di skills.sh: è la forma standard dello strumento `skills`, la stessa usata per le altre schede.

Alternativa solo per Claude Code, dal marketplace di Anthropic (installa tutte le skill per i documenti: `docx`, `pdf`, `pptx`, `xlsx`):

```text
/plugin marketplace add anthropics/skills
/plugin install document-skills@anthropic-agent-skills
```

Dopo l'installazione riavvia la sessione. Claude Code la usa da solo quando la richiesta è pertinente, oppure puoi citarla ("usa la skill PDF per estrarre i campi del modulo `percorso/file.pdf`"). In Codex la richiami con `$pdf` o la vedi con `/skills`.

Gestione:

```bash
npx skills list -g              # skill installate
npx skills update pdf           # aggiornamento
npx skills remove pdf           # rimozione
```

```text
/plugin uninstall document-skills@anthropic-agent-skills   # rimozione del plugin
```

### App desktop di Claude e ChatGPT

Queste app richiedono di caricare la skill come ZIP. Preparalo così:

```bash
git clone --depth 1 https://github.com/anthropics/skills.git
cd skills/skills && zip -r ~/pdf.zip pdf
```

Lo ZIP deve contenere la cartella `pdf/` con dentro `SKILL.md` (e gli altri file della cartella: `forms.md`, `reference.md`, `scripts/`).

**Claude (desktop o web)**

1. Attiva l'esecuzione del codice in **Settings → Capabilities**.
2. Vai in **Customize → Skills → + → Create skill → Upload a skill** e scegli lo ZIP.
3. Attiva l'interruttore della skill.

**ChatGPT (desktop o web)**

1. Vai in **Skills** nella barra laterale, poi **Create → Upload from your computer**, e scegli lo ZIP o la cartella.
2. Attendi l'analisi di sicurezza di ChatGPT.
3. Richiamala con `@` nella chat.

Le skill personali caricate su desktop e web non si sincronizzano: vanno caricate su ciascuna.

> **Limite:** nelle app di chat la skill gira in un ambiente isolato con esecuzione del codice. Funziona solo se lì sono disponibili le librerie e gli strumenti elencati sopra (non l'ho verificato), e legge solo i file che alleghi alla conversazione. Il README del repository dice che le skill di esempio sono già disponibili sui piani a pagamento di Claude.ai, ma non specifica se `pdf` sia tra queste.

## Fonti

- [README di anthropics/skills](https://github.com/anthropics/skills)
- [SKILL.md di pdf](https://github.com/anthropics/skills/blob/main/skills/pdf/SKILL.md)
- [forms.md di pdf](https://github.com/anthropics/skills/blob/main/skills/pdf/forms.md)
- [Cartella skills/pdf](https://github.com/anthropics/skills/tree/main/skills/pdf) e [scripts/](https://github.com/anthropics/skills/tree/main/skills/pdf/scripts)
- [pdf su skills.sh](https://skills.sh/anthropics/skills/pdf)
- [Use skills in Claude – Claude Help Center](https://support.claude.com/en/articles/12512180-use-skills-in-claude)
- [Skills in ChatGPT – OpenAI Help Center](https://help.openai.com/en/articles/20001066-skills-in-chatgpt)