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

name

description

agency-archivist

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:

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

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

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

## ⚠️ 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/

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

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

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 — 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