f205028145
- agency-archivist/SKILL.md: 2 riferimenti (Fase 2, Fase 3) - agency-orchestrator/SKILL.md: 3 riferimenti (sezione Script) - AGENCY_ARCHIVIST_DELIVERY.md: 7 riferimenti (file creati + esempi) Totale: 12 riferimenti corretti da Python a Node.js
336 lines
10 KiB
Markdown
336 lines
10 KiB
Markdown
---
|
|
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.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:** `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.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 |
|
|
|------|---------|-------------|
|
|
| `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_
|