STEP 2: agency-archivist - Nuova skill gestione risorse

- agency-archivist/SKILL.md: Skill per upload, estrazione, catalogazione - scripts/extract_archive.py: Estrazione zip/URL in clients/{client}/assets/ - scripts/scan_resources.py: Scansione metadata (2 passate: base + vision) - scripts/generate_catalog.py: Generazione catalogo.md con tag e use case - references/resource_types.md: Tipologie risorse e use case per skill - agency-orchestrator/SKILL.md: Integrazione archivist in Fase 1 - Step opzionale upload risorse - Sezione dedicata gestione risorse - Comportamento proattivo (richiesta risorse mancanti) - Pattern per altre skill Integrazione completa: orchestrator → archivist → visual-generator/design/web/social
2026-03-10 23:29:41 +01:00 · 2026-03-10 23:29:41 +01:00 · b1f3ba033e
commit b1f3ba033e
parent 6c1b04d39a
7 changed files with 1658 additions and 3 deletions
--- a/agency-archivist/SKILL.md
+++ b/agency-archivist/SKILL.md
@ -0,0 +1,336 @@
+---
+name: agency-archivist
+description: "Gestire archivi di risorse (immagini, video, documenti) per progetti agency. Usare quando: (1) cliente invia zip/URL di asset, (2) estrarre e organizzare risorse in clients/{client}/assets/, (3) catalogare risorse con descrizioni e tag, (4) cercare risorse per altre skill, (5) richiedere risorse mancanti in modo proattivo."
+---
+
+# Agency Archivist — Gestione Risorse e Asset
+
+Gestisce upload, estrazione, catalogazione e ricerca di risorse multimediali per i progetti della suite.
+
+## Quando Usare
+
+- **Upload risorse:** Cliente fornisce zip, URL o cartella con asset
+- **Estrazione archivi:** Decomprimere zip/tar in struttura organizzata
+- **Catalogazione:** Creare catalogo descrittivo delle risorse
+- **Ricerca risorse:** Trovare asset specifici per altre skill
+- **Proattivo:** Segnalare risorse mancanti e richiedere integrazione
+
+---
+
+## Struttura Archivio Progetti
+
+Ogni progetto ha una cartella dedicata per le risorse:
+
+```
+clients/{client}/
+├── assets/              ← Gestito da agency-archivist
+│   ├── archive/         # Archivi originali (zip, tar, rar)
+│   ├── images/          # Immagini estratte
+│   │   ├── logo/        # Loghi aziendali
+│   │   ├── prodotto/    # Foto prodotto
+│   │   ├── team/        # Foto team/ufficio
+│   │   └── stock/       # Immagini generiche
+│   ├── videos/          # Video estratti
+│   │   ├── promo/       # Video promozionali
+│   │   ├── tutorial/    # Tutorial/dimostrazioni
+│   │   └── raw/         # Footage grezzo
+│   ├── documents/       # Documenti di riferimento
+│   │   ├── brand/       # Linee guida brand
+│   │   ├── product/     # Schede prodotto
+│   │   └── legal/       # Documenti legali
+│   └── catalog.md       # Catalogo generato (indice centrale)
+├── knowledge/
+├── research/
+├── strategy/
+├── design/
+├── content/
+├── ops/
+└── published/
+```
+
+---
+
+## Processo
+
+### Fase 1: Ricezione Archivi
+
+**Obiettivo:** Accettare input da diverse fonti.
+
+**Input Supportati:**
+
+| Tipo | Formato | Esempio | Azione |
+|------|---------|---------|--------|
+| **Zip allegato** | `.zip`, `.tar.gz`, `.rar` | `brand_assets.zip` | Estrai in `assets/archive/` |
+| **URL HTTP/HTTPS** | Link diretto | `https://example.com/assets.zip` | Download + estrai |
+| **URL FTP** | FTP server | `ftp://server.com/file.zip` | Download + estrai |
+| **Cartella locale** | Path filesystem | `/home/user/assets/` | Copia in `assets/` |
+
+**Procedura:**
+
+1. **Ricevi input:** Path file, URL o allegato
+2. **Valida formato:** Verifica estensione supportata
+3. **Crea cartella archive:** `clients/{client}/assets/archive/`
+4. **Copia/Download:** Sposta file in archive/
+5. **Log operazione:** Registra in `clients/{client}/ops/run_log.md`
+
+**Esempio Log:**
+```markdown
+## 2026-03-10 23:30 — Archivist Upload
+
+- **Input:** `brand_assets.zip` (allegato)
+- **Destinazione:** `clients/demo_co_srl/assets/archive/`
+- **Dimensioni:** 15.4 MB
+- **Status:** ✅ Completato
+```
+
+---
+
+### Fase 2: Estrazione Archivi
+
+**Obiettivo:** Decomprimere e organizzare risorse per tipologia.
+
+**Script:** `scripts/extract_archive.py`
+
+**Procedura:**
+
+1. **Leggi archivio:** Identifica formato (zip, tar, rar)
+2. **Estrai temporaneo:** Decomprimi in cartella temporanea
+3. **Analizza contenuti:** Per ogni file:
+   - Rileva tipo (immagine, video, documento)
+   - Estrai metadata (dimensioni, risoluzione, formato)
+   - Assegna categoria (logo, prodotto, team, etc.)
+4. **Organizza:** Copia file in sottocartelle appropriate
+5. **Pulisci:** Elimina archivio originale (opzionale, su conferma)
+6. **Log:** Registra file estratti
+
+**Categorizzazione Automatica:**
+
+| Parola chiave nel nome | Cartella destinazione |
+|------------------------|----------------------|
+| `logo`, `brand`, `marchio` | `images/logo/` |
+| `prodotto`, `product`, `item` | `images/prodotto/` |
+| `team`, `staff`, `ufficio`, `office` | `images/team/` |
+| `sfondo`, `background`, `texture` | `images/stock/` |
+| `video`, `promo`, `reel` | `videos/promo/` |
+| `tutorial`, `howto`, `demo` | `videos/tutorial/` |
+| `brand`, `guideline`, `manual` | `documents/brand/` |
+| `scheda`, `datasheet`, `spec` | `documents/product/` |
+
+**Fallback:** File non categorizzabili → cartella radice (`images/`, `videos/`, `documents/`)
+
+---
+
+### Fase 3: Catalogazione Risorse
+
+**Obiettivo:** Generare catalogo descrittivo per ricerca futura.
+
+**Script:** `scripts/scan_resources.py` + `scripts/generate_catalog.py`
+
+**Due Passate di Analisi:**
+
+#### **Passata 1: Metadata Base (Sempre)**
+
+Per ogni risorsa, estrai:
+- Nome file
+- Estensione
+- Dimensione (KB/MB)
+- Tipo MIME
+- Data creazione/modifica
+- Risoluzione (per immagini/video)
+
+#### **Passata 2: Analisi Contenuto (Se Modello Supporta Vision)**
+
+Per immagini e video:
+- Descrizione semantica (cosa raffigura)
+- Colori dominanti
+- Presenza testo/logo
+- Contesto (interno/esterno, prodotto/persone)
+- Tag automatici
+
+**Output:** `clients/{client}/assets/catalog.md`
+
+---
+
+### Fase 4: Generazione Catalogo
+
+**Obiettivo:** Creare indice ricercabile delle risorse.
+
+**Formato Catalogo:**
+
+```markdown
+# Asset Catalog — {Nome Cliente}
+
+_Generato: {data} | Totale: {N} risorse_
+
+## Riepilogo
+
+| Tipo | Count | Dimensione Totale |
+|------|-------|-------------------|
+| Immagini | 18 | 24.5 MB |
+| Video | 3 | 156 MB |
+| Documenti | 5 | 2.1 MB |
+
+---
+
+## Immagini ({count})
+
+| File | Tipo | Dimensioni | Risoluzione | Descrizione | Tag | Use Case |
+|------|------|------------|-------------|-------------|-----|----------|
+| `logo_primary.png` | PNG | 45 KB | 512x512 | Logo aziendale, sfondo trasparente | #logo #brand #trasparente | Header sito, social profile |
+| `prodotto_01.jpg` | JPG | 2.3 MB | 3000x2000 | Foto prodotto su sfondo bianco | #prodotto #whitebg #ecommerce | E-commerce, social post |
+| `team_photo.jpg` | JPG | 4.1 MB | 4000x3000 | Foto team (8 persone, ufficio luminoso) | #team #ufficio #people | About page, LinkedIn |
+
+---
+
+## Video ({count})
+
+| File | Tipo | Dimensioni | Durata | Risoluzione | Descrizione | Tag | Use Case |
+|------|------|------------|--------|-------------|-------------|-----|----------|
+| `promo_30sec.mp4` | MP4 | 45 MB | 0:30 | 1920x1080 | Video promozionale prodotto, musica upbeat | #promo #prodotto #video | Social ads, homepage |
+
+---
+
+## Documenti ({count})
+
+| File | Tipo | Dimensioni | Descrizione | Tag | Use Case |
+|------|------|------------|-------------|-----|----------|
+| `brand_guidelines.pdf` | PDF | 1.2 MB | Linee guida brand (colori, font, logo) | #brand #guidelines #pdf | Design system, coerenza visiva |
+
+---
+
+## Tag Globali
+
+#logo #prodotto #team #brand #ufficio #milano #ecommerce #b2b
+
+---
+
+## Note
+
+- **Ultimo aggiornamento:** {data}
+- **Archivi originali:** `assets/archive/`
+- **Per richiedere risorse:** Contatta @agency-archivist
+```
+
+---
+
+## Integrazione con Altre Skills
+
+### **Come le Altre Skill Usano Archivist**
+
+**Pattern di Ricerca:**
+
+```markdown
+**Prima di eseguire task che richiedono asset:**
+
+1. Leggi `clients/{client}/assets/catalog.md`
+2. Cerca risorse per tag/tipo/descrizione
+3. Se trovi: Usa path completo
+4. Se NON trovi: "🔒 Bloccato: servono [descrizione risorse]"
+   - Tagga: @agency-archivist
+   - Descrivi: Cosa manca (es. "foto prodotto su sfondo bianco")
+   - Specifica: Requisiti tecnici (es. "minimo 1000x1000px, JPG")
+```
+
+### **Comportamento Proattivo di Archivist**
+
+**Quando una skill segnala risorse mancanti:**
+
+1. **Analizza richiesta:** Cosa serve esattamente?
+2. **Verifica catalogo:** Conferma che manca davvero
+3. **Risposta strutturata:**
+   ```
+   ⚠️ **Risorse Mancanti**
+   
+   Per eseguire [task], servono:
+   - [ ] Foto prodotto (sfondo bianco, minimo 1000x1000px)
+   - [ ] Logo aziendale (PNG trasparente)
+   - [ ] Brand colors (codici esadecimali)
+   
+   **Vuoi caricare queste risorse ora?**
+   
+   Opzioni:
+   1. Allega zip/URL con gli asset
+   2. Descrivi cosa hai a disposizione
+   3. Salta per ora (usa placeholder)
+   ```
+4. **Dopo upload:** Esegui re-scan e aggiorna catalogo
+5. **Sblocca skill:** Notifica: "✅ Risorse pronte, puoi procedere"
+
+---
+
+## Script
+
+### `scripts/extract_archive.py`
+
+**Input:** Path archivio o URL
+**Output:** Risorse estratte in `assets/`
+
+```bash
+python scripts/extract_archive.py <path_or_url> --client <client_name>
+```
+
+**Opzioni:**
+- `--keep-archive`: Mantieni file originale (default: elimina dopo estrazione)
+- `--verbose`: Log dettagliato
+- `--dry-run`: Simula senza estrazione
+
+### `scripts/scan_resources.py`
+
+**Input:** Cartella `assets/`
+**Output:** Metadata JSON temporaneo
+
+```bash
+python scripts/scan_resources.py --client <client_name> --pass 1|2
+```
+
+**Opzioni:**
+- `--pass 1`: Solo metadata base (veloce)
+- `--pass 2`: Analisi contenuto (richiede modello vision)
+- `--output`: Path output JSON (default: temporaneo)
+
+### `scripts/generate_catalog.py`
+
+**Input:** Metadata da scan
+**Output:** `catalog.md` formattato
+
+```bash
+python scripts/generate_catalog.py --client <client_name>
+```
+
+---
+
+## Output
+
+| File | Formato | Descrizione |
+|------|---------|-------------|
+| `clients/{client}/assets/catalog.md` | Markdown | Catalogo completo risorse |
+| `clients/{client}/ops/run_log.md` | Markdown | Log operazioni archivist |
+| `clients/{client}/assets/archive/` | Cartella | Archivi originali (opzionale) |
+
+---
+
+## References
+
+- [resource_types.md](./references/resource_types.md) — Tipologie risorse e use case
+- [metadata_schema.md](./references/metadata_schema.md) — Schema metadata per catalogazione
+
+---
+
+## Edge Cases
+
+**Gestione Errori:**
+
+- **Archivio corrotto:** "⚠️ Archivio corrotto o non valido. Richiedi nuovo upload."
+- **Formato non supportato:** "❌ Formato .xyz non supportato. Usa zip, tar.gz, o rar."
+- **URL non raggiungibile:** "❌ URL non accessibile. Verifica link o usa download diretto."
+- **Nessuna risorsa trovata:** "⚠️ Archivio vuoto o solo file non multimediali."
+
+**Limitazioni:**
+
+- **Dimensioni max:** 500 MB per archivio (configurabile)
+- **Formati video:** Solo MP4, MOV, AVI (altri richiedono codec aggiuntivi)
+- **Analisi contenuto:** Richiede modello con supporto vision (opzionale)
+
+---
+
+_Agency Skills Suite v1.0_