agency-skills-suite/agency-archivist/SKILL.md

---
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 {project}/assets/, (3) catalogare risorse con descrizioni e tag, (4) cercare risorse per altre skill, (5) richiedere risorse mancanti con 3 opzioni: blocco/upload, placeholder mode per continuità workflow, o skip asset. Supporta pattern placeholder per lavorare senza asset reali."
---


# 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:

```
{project}/
├── 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:** `{project}/assets/archive/`
4. **Copia/Download:** Sposta file in archive/
5. **Log operazione:** Registra in `{project}/ops/run_log.md`

**Esempio Log:**
```markdown
## 2026-03-10 23:30 — Archivist Upload

- **Input:** `brand_assets.zip` (allegato)
- **Destinazione:** `{project}/assets/archive/`
- **Dimensioni:** 15.4 MB
- **Status:** ✅ Completato
```

---

### Fase 2: Estrazione Archivi

**Obiettivo:** Decomprimere e organizzare risorse per tipologia.

**Script:** `scripts/extract_archive.js`

**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.js` + `scripts/generate_catalog.js`

**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:** `{project}/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 `{project}/assets/catalog.md`
2. Cerca risorse per tag/tipo/descrizione
3. Se trovi: Usa path completo ✅
4. Se NON trovi: **Scegli una delle 3 opzioni:**

   **OPZIONE A — Blocco Task (strict):**
   - "🔒 Bloccato: servono [descrizione risorse]"
   - Tagga: @agency-archivist
   - Descrivi: Cosa manca
   - Attendi upload prima di procedere

   **OPZIONE B — Placeholder Mode (consigliata per prototipi):**
   - Continua con asset placeholder/generici
   - Documenta in output: "⚠️ Usati placeholder per [asset] — aggiorna con asset reali"
   - Crea sezione "Assets Placeholder" nel deliverable
   - Non bloccare il workflow

   **OPZIONE C — Skip Asset (se opzionale):**
   - Procedi senza quella risorsa specifica
   - Adatta il design/contenuto di conseguenza
   - Documenta: "⏭️ Asset [nome] omesso — spazio riservato"
```

### **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 con 3 opzioni:**
   ```
   ⚠️ **Risorse Mancanti per [task]**

   Per completare questo task servono:
   - [ ] Foto prodotto (sfondo bianco, minimo 1000x1000px)
   - [ ] Logo aziendale (PNG trasparente)
   - [ ] Brand colors (codici esadecimali)

   **Come vuoi procedere?**

   1️⃣ **Upload asset** — Allega zip/URL con le risorse reali
   2️⃣ **Descrivi cosa hai** — Fornisci dettagli per orientare la ricerca
   3️⃣ **Continua con placeholder** ⚡ — Procedi con asset generici/placeholder
      (consigliato per prototipi, wireframe, o quando l'asset non è critico)
   ```
4. **Dopo upload:** Esegui re-scan e aggiorna catalogo
5. **Sblocca skill:** Notifica: "✅ Risorse pronte, puoi procedere"

---

## Pattern Placeholder per Asset Mancanti

Quando si sceglie l'**Opzione 3 — Continua con placeholder**, seguire questo pattern standardizzato:

### 1. Identificazione Placeholder

Per ogni asset mancante, crea un placeholder con:
- **Tipo:** `placeholder`
- **Nome:** `placeholder_[tipo]_[descrizione_breve].[ext]`
- **Dimensioni:** Specificare dimensioni target (es. "1200x800px")
- **Note:** Cosa dovrebbe rappresentare

### 2. Documentazione nel Deliverable

Includi sempre una sezione **"Assets Placeholder"** nel deliverable:

```markdown
## ⚠️ Assets Placeholder

I seguenti elementi sono stati realizzati con asset generici/placeholder:

| Posizione | Asset Mancante | Tipo Richiesto | Note |
|-----------|----------------|----------------|------|
| Hero section | `placeholder_hero_product.jpg` | Foto prodotto 1920x1080 | Sfondo hero, prodotto su bianco |
| Logo header | `placeholder_logo.png` | Logo PNG trasparente 512x512 | Logo aziendale |
| Team section | `placeholder_team_01.jpg` | Foto team 800x600 | 3 placeholder per 3 membri |

**Per completare:** Sostituire i placeholder con asset reali mantenendo le stesse dimensioni e nomi file.
```

### 3. Comportamento delle Skill Consumatrici

Le skill che usano asset (es. agency-visual-generator, agency-web-developer) devono:

1. **Controllare catalogo:** Verificare se asset esiste o è placeholder
2. **Se placeholder:**
   - Procedere con il placeholder (non bloccare)
   - Aggiungere nota nel deliverable
   - Mantenere struttura/layout come se fosse reale
3. **Se asset reale:** Usare normalmente
4. **Documentare sempre:** Lista asset usati (reali o placeholder) nel deliverable

### 4. Vantaggi del Pattern Placeholder

- **Prototipi veloci:** Non bloccare workflow per asset mancanti
- **Chiarezza:** Cliente vede esattamente cosa manca
- **Iterazione:** Facile sostituire placeholder con asset reali
- **Testing:** Verificare layout/design prima di avere asset finali

---

## Script

### `scripts/extract_archive.js`

**Input:** Path archivio o URL
**Output:** Risorse estratte in `assets/`

```bash
node scripts/extract_archive.js <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.js`

**Input:** Cartella `assets/`
**Output:** Metadata JSON in `assets/.metadata.json`

```bash
node scripts/scan_resources.js --client <client_name> --pass 1|2
```

**Opzioni:**
- `--pass 1`: Solo metadata base (veloce)
- `--pass 2`: Analisi avanzata (richiede ImageMagick/ffprobe)
- `--output`: Path output JSON (default: assets/.metadata.json)

### `scripts/generate_catalog.js`

**Input:** Metadata da scan
**Output:** `catalog.md` formattato

```bash
node scripts/generate_catalog.js --client <client_name>
```

---

## Output

| File | Formato | Descrizione |
|------|---------|-------------|
| `{project}/assets/catalog.md` | Markdown | Catalogo completo risorse |
| `{project}/ops/run_log.md` | Markdown | Log operazioni archivist |
| `{project}/assets/archive/` | Cartella | Archivi originali (opzionale) |

---

## References

- [resource_types.md](../agency-shared-references/references/resource_types.md) — Tipologie risorse e use case

---

## 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_