framework-translator/SKILL.md

---
name: framework-translator
description: Trasformare framework testuali eterogenei (multi-cartella, multi-agente, workflow) in set di skills AgentSkills-compatibili usando analisi semantica LLM. Usare quando: (1) convertire framework esistente in skills eseguibili con comprensione contestuale, (2) standardizzare documentazione multi-agente in formato AgentSkills, (3) estrarre knowledge da framework e centralizzare in references, (4) generare pipeline di skills coordinate da orchestratore. Output: Cartella <framework>-skills/ con N skills AgentSkills-compatibili, references centralizzate, script INSTALL.sh, documentazione installazione.
---

# Framework Translator — Trasformazione Framework in AgentSkills (LLM-Native)

Analizzare framework testuali complessi e trasformarli in suite di skills AgentSkills-compatibili usando **analisi semantica LLM** invece di parsing automatico.

## Quando Usare Questa Skill

- **Conversione framework:** Hai un framework esistente (multi-agente, workflow, knowledge) da trasformare in skills eseguibili
- **Standardizzazione:** Documentazione eterogenea va normalizzata in formato AgentSkills
- **Estrazione knowledge:** Knowledge sparsa in più file va centralizzata in references condivise
- **Generazione pipeline:** Servono skills coordinate con orchestratore per workflow end-to-end

## Supporto Multi-Lingua e Multi-Dominio

Questa skill supporta framework in **qualsiasi lingua** (italiano, inglese, spagnolo, etc.) e **qualsiasi dominio** (orto, finanza, salute, educazione, etc.).

- **Lingua input:** Rilevata automaticamente, mantenuta nell'output
- **Lingua output:** Stessa lingua dell'input (o specificata dall'utente)
- **Dominio:** Irrilevante — pattern di trasformazione sono dominio-agnostici

## Panoramica del Processo

```
┌─────────────────────────────────────────────────────────────────┐
│  FASE 1: Analisi Framework (LLM legge e comprende)              │
│  Input: Percorso framework                                      │
│  Output: test/<framework>/test-<framework>_v1/analysis_report.md│
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│  FASE 2: Mappatura (LLM propone, utente approva)                │
│  Input: analysis_report.md                                      │
│  Output: test/<framework>/test-<framework>_v1/mapping_plan.md   │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│  FASE 3: Estrazione Knowledge (LLM estrae e centralizza)        │
│  Input: mapping_plan.md + file framework                        │
│  Output: test/<framework>/test-<framework>_v1/references/*.md   │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│  FASE 4: Generazione Skills (LLM scrive SKILL.md)               │
│  Input: mapping_plan.md + references/                           │
│  Output: test/<framework>/test-<framework>_v1/skills/*/SKILL.md │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│  FASE 5: Packaging (Script meccanici)                           │
│  Input: skills generate + references                            │
│  Output: test/<framework>/<framework>-skills-suite/             │
└─────────────────────────────────────────────────────────────────┘
```

**Nota:** Tutti i output dei test vanno nella cartella `test/` come documentato in `test/README.md`.

---

## Fase 1: Analisi Framework (LLM)

**Obiettivo:** Leggere e comprendere la struttura del framework, identificando agenti, workflow, knowledge e script.

### Step 1.1: Scansione Iniziale

**Azione:** Chiedi all'utente il percorso del framework, poi esegui:

```bash
# Lista tutti i file markdown nel framework
find /path/to/framework -type f -name "*.md" | sort
```

**Output atteso:** Lista di 20-100 file markdown.

---

### Step 1.2: Identificazione Cartelle Chiave

**Azione:** Analizza la struttura directory e identifica cartelle per:

| Tipo | Pattern da cercare | Esempi |
|------|-------------------|--------|
| **Agenti** | `agents`, `agenti`, `actors`, `roles` | `docs/agents/`, `agenti/` |
| **Workflow** | `workflows`, `flussi`, `processes` | `docs/workflows/`, `flussi/` |
| **Knowledge** | `knowledge`, `docs`, `references` | `docs/knowledge/`, `references/` |
| **Scripts** | `scripts`, `tools`, `utilities` | `scripts/`, `tools/` |
| **Prompts** | `prompts`, `templates` | `prompts/`, `templates/` |

**Output:** Lista cartelle identificate con percorsi.

---

### Step 1.3: Lettura File Index/Overview

**Azione:** Leggi i file index di ogni cartella chiave:

```bash
# Leggi file index agenti
cat docs/agents/00_agent_index.md

# Leggi file index workflow
cat docs/workflows/00_workflow_index.md

# Leggi README principale
cat README.md
```

**Cosa estrarre:**

- Lista agenti con nomi e ID
- Lista workflow con nomi e ID
- Panoramica dominio e scopo framework

---

### Step 1.4: Analisi Semantica Agenti

**Azione:** Per ogni file agente (es. `docs/agents/01_orchestratore.md`), leggi e estrai:

```markdown
## Agente: <Nome>

**ID:** <ID o numero file>

**Missione:** (1-2 frasi che descrivono lo scopo principale)

**Responsabilità principali:**
- [Lista 3-6 responsabilità chiave]

**Input richiesti:**
- [Lista input principali]

**Output prodotti:**
- [Lista output principali]

**Dipendenze da altri agenti:**
- [Lista agenti correlati o prerequisiti]

**Livello priorità:** MUST / SHOULD / MEDIUM / LOW

**Note contestuali:** (eventuali osservazioni su ruolo nel framework)
```

**Criteri di analisi:**

- **Leggere missione** — Capire scopo fondamentale
- **Identificare overlap** — Notare se responsabilità si sovrappongono ad altri agenti
- **Valutare complessità** — Stimare se agente è semplice (operativo) o complesso (coordinamento)

---

### Step 1.5: Analisi Semantica Workflow

**Azione:** Per ogni file workflow, leggi e estrai:

```markdown
## Workflow: <Nome>

**ID:** <ID o numero file>

**Trigger:** (Quando viene eseguito? Es. "Nuovo utente", "Ogni settimana")

**Fasi principali:**
1. [Fase 1]
2. [Fase 2]
3. [Fase 3]

**Agenti coinvolti:** [Lista agenti]

**Output finale:** (Cosa produce? Es. "Piano stagionale", "Struttura directory")

**Note contestuali:** (osservazioni su complessità, dipendenze)
```

---

### Step 1.6: Analisi Knowledge Base

**Azione:** Per ogni file in cartelle knowledge/docs, stima:

```markdown
## File: <nome file>

**Argomento principale:** (1 frase)

**Dimensione stimata:** <numero> linee / <KB> KB

**Contenuto tipo:** Tabelle / Liste / Narrative / Misto

**Condivisione potenziale:** Questo file è probabilmente usato da:
- [Agente/Skill 1]
- [Agente/Skill 2]

**Raccomandazione:** REFERENCE (se >500 linee o condiviso) / INLINE (se piccolo e specifico)
```

---

### Step 1.7: Valutazione Scripts

**Azione:** Per ogni script (`.py`, `.sh`), valuta:

```markdown
## Script: <nome file>

**Scopo:** (1 frase)

**Dimensione:** <KB> KB

**Complessità:** SEMPLICE (<50 linee) / MEDIO (50-200) / COMPLESSO (>200)

**Riutilizzabilità:** ONE-TIME (migrazione, setup) / RUNTIME (eseguito spesso)

**Raccomandazione:** 
- INCLUDE (se runtime e riutilizzabile)
- INLINE (se semplice, converti in descrizione markdown)
- ELIMINA (se one-time o ridondante)
```

---

### Step 1.8: Generazione analysis_report.md

**Azione:** Compila il report e salva in `test/<framework>/test-<framework>_v1/analysis_report.md`

**Template:**

```markdown
# Analysis Report — <Framework Name>

## Panoramica

- **Framework:** <nome>
- **Percorso:** <percorso>
- **Lingua rilevata:** Italian / English / Other
- **Dominio stimato:** Orto / Finance / Health / Education / General
- **Data analisi:** YYYY-MM-DD

---

## Struttura Identificata

### Cartelle Chiave

| Tipo | Percorso | Note |
|------|----------|------|
| Agenti | `docs/agents/` | 12 file agente |
| Workflow | `docs/workflows/` | 5 file workflow |
| Knowledge | `docs/knowledge/` | 8 file, ~100 KB totali |
| Scripts | `scripts/` | 7 script |

---

## Agenti Identificati (<N> totale)

| # | ID | Nome | Missione (breve) | Priorità | Overlap Note |
|---|----|------|------------------|----------|--------------|
| 1 | agent_01 | Orchestratore | Coordina workflow | MUST | Coordinamento |
| 2 | agent_02 | Agronomo | Piano colture | MUST | - |
| 3 | agent_03 | Fitopatologo | Diagnosi malattie | MUST | Overlap con trattamenti |
| ... | ... | ... | ... | ... | ... |

---

## Workflow Identificati (<N> totale)

| # | ID | Nome | Trigger | Agenti Coinvolti | Output |
|---|----|------|---------|------------------|--------|
| 1 | wf_00 | Init | Nuovo progetto | Orchestratore | Struttura directory |
| 2 | wf_01 | Onboarding | Utente nuovo | Agronomo, Layout | GardenConfig |
| ... | ... | ... | ... | ... | ... |

---

## Knowledge Base (<N> file, <KB> KB totali)

| # | File | Argomento | Dimensione | Usato Da | Raccomandazione |
|---|------|-----------|------------|----------|-----------------|
| 1 | colture.md | Catalogo colture | 20 KB | Agronomo, Layout | REFERENCE |
| 2 | malattie.md | Diagnosi malattie | 15 KB | Fitopatologo | REFERENCE |
| ... | ... | ... | ... | ... | ... |

---

## Scripts Valutati (<N> totale)

| # | Script | Scopo | Dimensione | Raccomandazione | Motivo |
|---|--------|-------|------------|-----------------|--------|
| 1 | init_new_orto.py | Crea progetto | 20 KB | INCLUDE | Runtime, riutilizzabile |
| 2 | json_to_md.py | Migrazione | 3 KB | ELIMINA | One-time, non runtime |
| ... | ... | ... | ... | ... | ... |

---

## Metriche e Complessità

- **Totale agenti:** <N>
- **Totale workflow:** <N>
- **Totale knowledge:** <KB> KB
- **Totale scripts:** <N>
- **Complessità stimata:** LOW (<10 entità) / MEDIUM (10-25) / HIGH (>25)

---

## Raccomandazioni Iniziali

- **Skills stimate:** ~<N> (dettagli in Fase 2)
- **References stimate:** ~<M>
- **Note:** [Osservazioni preliminari su sfide o particolarità]

---

_Fine report — Pronto per Fase 2 (Mappatura)_
```

---

### Step 1.9: Validazione Fase 1

**Checklist prima di procedere:**

- [ ] Tutti i file agenti sono stati letti e analizzati
- [ ] Tutti i file workflow sono stati letti e analizzati
- [ ] Knowledge base è stata catalogata con dimensioni
- [ ] Scripts sono stati valutati (include/inline/elimina)
- [ ] Lingua e dominio sono stati rilevati
- [ ] Report è leggibile e strutturato

**Se tutto OK:** Procedi a Fase 2.

---

## Fase 2: Mappatura Entità → Skills (LLM + Approvazione Utente)

**Obiettivo:** Proporre trasformazione di agenti + workflow in skills, richiedendo approvazione esplicita dell'utente.

### Step 2.1: Applicazione Pattern di Mappatura

**Azione:** Usa `references/mapping_patterns.md` per applicare pattern:

| Pattern | Quando Applicare | Esempio |
|---------|------------------|---------|
| **Pattern 1:** 1 Agente → 1 Skill | Agente auto-contenuto, overlap <30% | Agronomo → orto-agronomo |
| **Pattern 2:** 2+ Agenti → 1 Skill | Overlap >50%, stesse responsabilità | Fitopatologo + Trattamenti → orto-fitopatologo |
| **Pattern 3:** Workflow → Skill | Workflow operativo con script | Init → orto-init |
| **Pattern 4:** Orchestratore | Agente coordinamento + workflow multipli | Orchestratore + QA → orto-orchestratore |
| **Pattern 5:** Eliminato | Non essenziale per MVP | UI/UX Agent → ELIMINATO |
| **Pattern 6:** Assorbito | Funzionalità micro/ridondante | QA → assorbito in orchestratore |

---

### Step 2.2: Calcolo Overlap Semantico

**Azione:** Per ogni coppia di agenti, valuta overlap:

```
Overlap BASSO (<30%):
- Missioni distinte
- Responsabilità non sovrapposte
- Output separati

Overlap MEDIO (30-50%):
- Alcune responsabilità condivise
- Output parzialmente sovrapposti

Overlap ALTO (>50%):
- Missioni simili o complementari
- Responsabilità fortemente sovrapposte
- Stesso output/documento
```

**Decisione:**
- Overlap ALTO → Pattern 2 (Merge)
- Overlap MEDIO → Valuta caso per caso
- Overlap BASSO → Pattern 1 (Skill separata)

---

### Step 2.3: Identificazione Orchestratore

**Cerca keyword:** `orchestrator`, `planner`, `coordinator`, `coordinatore`, `master`

**Se trovato:**
- Applica Pattern 4
- Skill includerà: coordinamento + risoluzione conflitti + QA

**Se non trovato:**
- Valuta se creare orchestratore ex-novo (se workflow multipli)
- Oppure: nessuna skill orchestratore (se workflow indipendenti)

---

### Step 2.4: Identificazione References

**Criteri:**

```
REFERENCE (centralizzata) se:
- Dimensione >10 KB OPPURE
- Usata da 2+ skills OPPURE
- Conoscenza dominio-statica (tabelle, parametri)

INLINE (nel corpo SKILL.md) se:
- Dimensione <10 KB E
- Usata da 1 sola skill E
- Specifica del dominio della skill
```

---

### Step 2.5: Generazione Proposta di Mappatura

**Azione:** Compila proposta usando questo template:

```markdown
# Proposta di Mappatura — <Framework Name>

## Skills Proposte (<N> totale)

| # | Nome Skill | Origine | Pattern | Giustificazione | References | Complessità |
|---|------------|---------|---------|-----------------|------------|-------------|
| 1 | framework-init | Workflow 00 | Pattern 3 | Operativo, con script | Nessuna | Bassa |
| 2 | framework-agronomo | Agente 02 | Pattern 1 | Auto-contenuto | colture.md | Media |
| 3 | framework-fitopatologo | Agente 04 + 07 | Pattern 2 | Overlap >50% | malattie.md | Media |
| 4 | framework-orchestratore | Agente 01 + QA | Pattern 4 | Coordinamento + QA | conflitti.md, qa.md | Alta |
| ... | ... | ... | ... | ... | ... | ... |

---

## References Proposte (<M> totale)

| # | Nome File | Contenuto | Dimensione | Usato Da |
|---|-----------|-----------|------------|----------|
| 1 | colture.md | Catalogo colture, varietà | 20 KB | agronomo, layout |
| 2 | malattie.md | Diagnosi, trattamenti | 15 KB | fitopatologo |
| 3 | conflitti.md | Risoluzione conflitti | 9 KB | orchestratore |
| ... | ... | ... | ... | ... |

---

## Eliminazioni / Assorbimenti

| Entità Origine | Decisione | Motivo | Assorbito Da |
|----------------|-----------|--------|--------------|
| Agente 09 (UI/UX) | ELIMINATO | Non essenziale per MVP | - |
| Agente 10 (QA) | ASSORBITO | Funzionalità in orchestratore | orchestratore |
| Agente 12 (Ops) | ELIMINATO | Integrazioni gestite da singole skills | - |

---

## Riepilogo

- **Skills:** <N> (da <M> agenti + workflow originali)
- **References:** <K> (da <L> file knowledge originali)
- **Eliminati/Assorbiti:** <P> entità
- **Complessità stimata:** LOW / MEDIUM / HIGH

---

## Approvazione Richiesta

**Approvi questa mappatura?**

- ✅ **SÌ, procedi** con questa mappatura
- ✏️ **MODIFICA:** [Specifica cambiamenti richiesti]
- ❌ **NO, rivedi:** [Specifica obiezioni o alternative]

**Nota:** La mappatura non procede senza approvazione esplicita.
```

---

### Step 2.6: Presentazione all'Utente

**Azione:** Mostra la proposta all'utente e attendi feedback.

**Messaggio tipo:**

```
📋 PROPOSTA DI MAPPATURA PRONTA

Ho analizzato il framework <nome> e proposto:
- <N> skills (da <M> agenti + workflow originali)
- <K> references centralizzate
- <P> eliminazioni/assorbimenti

La proposta è in: mapping_plan.md

Vuoi:
1) Approvare e procedere con Fase 3
2) Richiedere modifiche (specifica quali)
3) Rivedere la mappatura (specifica obiezioni)

Attendo tuo feedback prima di procedere.
```

---

### Step 2.7: Gestione Feedback Utente

**Se approvato:**
- Aggiorna `mapping_plan.md` con:
  ```markdown
  **Status:** APPROVED
  **Approvato da:** <nome utente>
  **Data approvazione:** YYYY-MM-DD
  ```
- Procedi a Fase 3

**Se modifiche richieste:**
- Applica modifiche alla mappatura
- Ripresenta proposta aggiornata
- Attendi nuova approvazione

**Se rifiutato:**
- Discuti alternative con utente
- Rivedi pattern applicati
- Genera nuova proposta

---

### Step 2.8: Generazione mapping_plan.md Finale

**Azione:** Salva in `test/<framework>/test-<framework>_v1/mapping_plan.md`

**Template:**

```markdown
# Mapping Plan — <Framework Name>

**Status:** APPROVED / PENDING / REJECTED
**Data analisi:** YYYY-MM-DD
**Approvato da:** <nome> (se approvato)
**Data approvazione:** YYYY-MM-DD (se approvato)

---

## Skills da Generare

[Tabella skills approvate]

---

## References da Creare

[Tabella references approvate]

---

## Decisioni di Mappatura

[Giustificazione dettagliata per ogni decisione di merge/elimina/assorbi]

---

## Approvazione

- **Approvato da:** <nome>
- **Data:** YYYY-MM-DD
- **Note:** [Eventuali condizioni o raccomandazioni]

---

_Fine piano — Pronto per Fase 3 (Estrazione Knowledge)_
```

---

## Fase 3: Estrazione Knowledge → References (LLM)

**Obiettivo:** Estrarre knowledge dai file sorgente e creare references centralizzati, strutturati e leggibili.

### Step 3.1: Lettura File Sorgente

**Azione:** Per ogni reference proposta in `mapping_plan.md`:

1. Identifica file sorgente nel framework (usa percorso da report o cerca per keyword)
2. Leggi contenuto completo
3. Identifica sezioni rilevanti (tabelle, liste, parametri, regole)

---

### Step 3.2: Estrazione Contenuto

**Cosa estrarre:**

| Tipo | Cosa Estrarre | Cosa Escludere |
|------|---------------|----------------|
| **Tabelle** | Tutte le tabelle markdown | Tabelle vuote o malformate |
| **Liste** | Liste strutturate (>3 elementi) | Liste narrative |
| **Parametri** | Valori numerici, soglie, formule | Descrizioni lunghe |
| **Regole** | Regole decisionali, criteri | Narrative esplicative |
| **Esempi** | Esempi concreti, casi d'uso | Esempi ridondanti |

---

### Step 3.3: Riformattazione Reference

**Template per ogni reference:**

```markdown
# <Titolo Reference>

_Framework: <framework-name> | Estratto: YYYY-MM-DD_
_Usato da: <skill-1>, <skill-2>, ..._

## Sommario

[Breve descrizione del contenuto, 2-3 frasi]

---

## Tabella dei Contenuti

*(Solo se >100 linee)*

1. [Sezione 1](#sezione-1)
2. [Sezione 2](#sezione-2)
...

---

## Sezione 1: <Titolo>

[Contenuto strutturato: tabelle, liste, parametri]

### Sottosezione 1.1

[Dettaglio se necessario]

---

## Sezione 2: <Titolo>

...

---

## Note

[Eventuali note di trasformazione, avvertenze, limitazioni]

---

_Reference generato da framework-translator_
```

---

### Step 3.4: Esempio Concreto di Estrazione

**Input (file originale):**

```markdown
# Catalogo Colture Italiane

Questo documento contiene un catalogo completo delle colture orticole più comuni in Italia, con informazioni su varietà, requisiti di coltivazione, stagionalità e caratteristiche.

## Pomodoro (Solanum lycopersicum)

Il pomodoro è una delle colture più importanti per l'orto italiano. Esistono numerose varietà, tra cui:

- San Marzano: varietà determinata, ideale per conserve
- Ciliegino: varietà indeterminata, frutti piccoli e dolci
- Cuor di Bue: varietà grande, per insalate

### Requisiti

- Temperatura: min 15°C notte, 25°C giorno
- Acqua: medio-alta (classe ALTO)
- Spaziatura: 40-60cm tra piante
- Ciclo: 70-90 giorni post-trapianto

## Zucchina (Cucurbita pepo)

...
```

**Output (reference estratta):**

```markdown
# Colture It

_Framework: orto_v1 | Estratto: 2026-03-07_
_Usato da: orto-agronomo, orto-layout_

## Sommario

Catalogo colture orticole italiane con varietà, requisiti di coltivazione, classi acqua e spaziature.

---

## Pomodoro (Solanum lycopersicum)

### Varietà

| Varietà | Tipo | Uso | Note |
|---------|------|-----|------|
| San Marzano | Determinato | Conserve | Classica italiana |
| Ciliegino | Indeterminato | Fresco | Frutti piccoli, dolci |
| Cuor di Bue | Indeterminato | Insalate | Frutti grandi |

### Requisiti

- **Temperatura:** min 15°C notte, 25°C giorno
- **Acqua:** Classe ALTO (medio-alta)
- **Spaziatura:** 40-60cm tra piante
- **Ciclo:** 70-90 giorni post-trapianto

---

## Zucchina (Cucurbita pepo)

...

---

_Reference generato da framework-translator_
```

---

### Step 3.5: Salvataggio References

**Azione:** Salva ogni reference in:

```
test/<framework>/test-<framework>_v1/references/<nome>.md
```

**Naming convention:**
- Lowercase con underscore: `colture_it.md`, `malattie_trattamenti.md`
- Suffisso lingua se necessario: `_it`, `_en`, `_es`

---

### Step 3.6: Validazione References

**Checklist per ogni reference:**

- [ ] Header con metadata (framework, data, usato da)
- [ ] Sommario breve (2-3 frasi)
- [ ] TOC se >100 linee
- [ ] Contenuto strutturato (tabelle, liste, sezioni)
- [ ] Narrative rimosse o minimizzate
- [ ] Note finali (se necessarie)

---

## Fase 4: Generazione Skills (LLM)

**Obiettivo:** Generare N skills AgentSkills-compatibili usando `references/skill_template.md`.

### Step 4.1: Preparazione Contesto

**Per ogni skill in `mapping_plan.md`:**

1. Leggi origine (agente/workflow di provenienza)
2. Leggi references richieste
3. Leggi pattern applicato
4. Leggi giustificazione

---

### Step 4.2: Generazione Frontmatter

**Template:**

```yaml
---
name: <skill-name>
description: <descrizione>
---
```

**Linee guida description:**

```
<Verbo all'infinito> <oggetto> per <framework>. Usare quando: 
(1) <scenario 1>, 
(2) <scenario 2>, 
(3) <scenario 3>. 
Output: <output finale>.
```

**Esempio:**

```yaml
description: Selezionare e pianificare colture per calendario annuale dell'orto basato su dieta, spazio, clima e principi agronomici. Usare quando: (1) generare selezione colture corrispondente a preferenze dieta comunitaria, (2) applicare regole consociazione e rotazione, (3) stimare rese e pianificare successioni. Output: Piano colture annuale (markdown) con varietà, date, spaziature, rese attese.
```

---

### Step 4.3: Generazione Corpo SKILL.md

**Usa `references/skill_template.md` come base.**

**Sezioni obbligatorie:**

1. **Titolo + Sottotitolo**
2. **Introduzione** (2-3 frasi)
3. **Quando Usare** (3-5 scenari)
4. **Input** (tabella con validazione)
5. **Processo** (Fase 1, Fase 2, Fase 3 — con nomi descrittivi)
6. **Output** (descrizione + esempio)
7. **References** (link a file centralizzati)
8. **Note** (edge cases, limitazioni)

---

### Step 4.4: Adattamento Contestuale

**Importante:** Non usare template generico — adatta al dominio specifico.

**Esempio per orto-agronomo:**

```markdown
### Fase 1: Filtra Colture per Vincoli

**Obiettivo:** Ridurre colture candidate applicando filtri sequenziali.

**Azioni:**

1. Carica GardenConfig da `config/garden_config.md`
2. Applica filtri in sequenza:

**Regole decisionali:**

```
se zona == "nord":
  → Filtra per date gelate nord (ultima gelata: 25 aprile)
  → Finestra semina: aprile-maggio
altrimenti se zona == "centro":
  → Filtra per date gelate centro (ultima gelata: 15 aprile)
  → Finestra semina: marzo-aprile
altrimenti:
  → Filtra per date gelate sud (ultima gelata: 1 aprile)
  → Finestra semina: febbraio-marzo
```
```

**Esempio per orchestratore:**

```markdown
### Fase 2: Rilevazione e Risoluzione Conflitti

**Obiettivo:** Identificare conflitti tra output di skills e applicare politiche di risoluzione.

**Conflitti da rilevare:**

| Tipo | Rilevamento | Politica Risoluzione |
|------|-----------|---------------------|
| Zona irrigazione vs. Consociazioni | Coltura A (ALTA) + Coltura B (BASSA) stessa aiuola | Dividi aiuola OPPURE adatta irrigazione (ALTA priority) |
| Task calendario vs. Meteo | Task "Trapianto" con vento >8kn | Auto-riprogramma +2 gg (notifica utente) |
```

---

### Step 4.5: Generazione Output

**Azione:** Per ogni skill, genera:

```
test/<framework>/test-<framework>_v1/skills/<skill-name>/
└── SKILL.md
```

**Struttura directory completa:**

```
test/<framework>/test-<framework>_v1/
├── skills/
│   ├── <skill-1>/
│   │   └── SKILL.md
│   ├── <skill-2>/
│   │   └── SKILL.md
│   └── ...
└── references/
    ├── reference-1.md
    ├── reference-2.md
    └── ...
```

---

### Step 4.6: Creazione Symlink

**Azione:** Per ogni skill, crea symlink a references:

```bash
cd <framework>-suite/<skill-name>
ln -s ../references references
```

**Alternativa (se symlink non supportati):** Copia references in ogni skill (meno efficiente).

---

### Step 4.7: Validazione Skills Generate

**Checklist per ogni skill:**

- [ ] Frontmatter YAML valido (name + description)
- [ ] Description con 3+ scenari trigger
- [ ] Corpo <500 linee (o references usati)
- [ ] Titolo + sottotitolo presenti
- [ ] "Quando Usare" con 3-5 scenari
- [ ] Input tabella completa
- [ ] Processo con 3 fasi (nomi descrittivi)
- [ ] Output documentato (file, formato, esempio)
- [ ] References linkati (percorsi corretti)
- [ ] Note per edge cases/limitazioni

---

## Fase 5: Packaging (Script Meccanici)

**Obiettivo:** Rendere la suite pronta per distribuzione.

### Step 5.1: Script 02_create_structure.sh

```bash
#!/bin/bash
# Crea struttura distribuzione in test/<framework>/

FRAMEWORK_NAME="$1"
SOURCE_DIR="$2"  # test/<framework>/test-<framework>_v1/

if [ -z "$FRAMEWORK_NAME" ] || [ -z "$SOURCE_DIR" ]; then
    echo "Usage: $0 <framework-name> <source-dir>"
    exit 1
fi

# Crea cartella distribuzione
DIST_DIR="test/${FRAMEWORK_NAME}/${FRAMEWORK_NAME}-skills-suite"
mkdir -p "$DIST_DIR"

# Sposta references in root
mv "$DIST_DIR/references" "${DIST_DIR}_temp" 2>/dev/null || true
find "$DIST_DIR" -mindepth 1 -maxdepth 1 -type d ! -name "references" -exec rm -rf {} \;
mkdir -p "$DIST_DIR/references"

# Sposta skills e references
# ... (logica di organizzazione)

echo "✅ Struttura creata: $DIST_DIR"
```

---

### Step 5.2: Script 02_create_symlinks.sh

```bash
#!/bin/bash
# Crea symlink references in ogni skill

DIST_DIR="$1"
if [ -z "$DIST_DIR" ]; then
    echo "Usage: $0 <dist-dir>"
    exit 1
fi

for skill_dir in "$DIST_DIR"/*/; do
    if [ -d "$skill_dir" ] && [ "$skill_dir" != "$DIST_DIR/references/" ]; then
        ln -sf ../references "$skill_dir/references"
        echo "✓ Symlink: $skill_dir/references → ../references"
    fi
done

echo "✅ Symlink creati"
```

---

### Step 5.3: Script 03_generate_install.sh

```bash
#!/bin/bash
# Genera INSTALL.sh

DIST_DIR="$1"
FRAMEWORK_NAME="$(basename "$DIST_DIR")"

cat > "$DIST_DIR/INSTALL.sh" << EOF
#!/bin/bash
# Installazione ${FRAMEWORK_NAME}-skills

SOURCE="\$(cd "\$(dirname "\${BASH_SOURCE[0]}")" && pwd)"
TARGET="\$HOME/.openclaw/skills/${FRAMEWORK_NAME}-skills"

echo "Installing ${FRAMEWORK_NAME}-skills..."
cp -r "\$SOURCE" "\$TARGET"
echo "Installation complete!"
echo ""
echo "Skills installate in: \$TARGET"
EOF

chmod +x "$DIST_DIR/INSTALL.sh"
echo "✅ INSTALL.sh generato"
```

---

### Step 5.4: Script 04_generate_readme.sh

```bash
#!/bin/bash
# Genera README.md per distribuzione

DIST_DIR="$1"
FRAMEWORK_NAME="$(basename "$DIST_DIR")"

# Conta skills e references
SKILLS_COUNT=$(find "$DIST_DIR" -mindepth 1 -maxdepth 1 -type d ! -name "references" | wc -l)
REFS_COUNT=$(find "$DIST_DIR/references" -name "*.md" 2>/dev/null | wc -l)

cat > "$DIST_DIR/README.md" << EOF
# ${FRAMEWORK_NAME}-skills

Suite di AgentSkills generate da framework-translator.

## Panoramica

- **Skills:** ${SKILLS_COUNT}
- **References:** ${REFS_COUNT}
- **Lingua:** [Da rilevare]
- **Dominio:** [Da rilevare]

## Installazione

### Metodo 1: Script Automatico

\`\`\`bash
./INSTALL.sh
\`\`\`

### Metodo 2: Copia Manuale

\`\`\`bash
cp -r . ~/.openclaw/skills/${FRAMEWORK_NAME}-skills
\`\`\`

## Skills Incluse

EOF

# Lista skills
for skill_dir in "$DIST_DIR"/*/; do
    if [ -d "$skill_dir" ] && [ "$skill_dir" != "$DIST_DIR/references/" ]; then
        skill_name=$(basename "$skill_dir")
        echo "- **$skill_name**" >> "$DIST_DIR/README.md"
    fi
done

echo "" >> "$DIST_DIR/README.md"
echo "---" >> "$DIST_DIR/README.md"
echo "_Generato da framework-translator_" >> "$DIST_DIR/README.md"

echo "✅ README.md generato"
```

---

## Output Finale Atteso

```
<framework>-suite/
├── README.md                    # Panoramica + installazione
├── INSTALL.sh                   # Script installazione
├── <skill-1>/
│   ├── SKILL.md                 # Skill AgentSkills-compatibile
│   └── references → ../references (symlink)
├── <skill-2>/
│   ├── SKILL.md
│   └── references → ../references
├── ...
└── references/
    ├── reference-1.md
    ├── reference-2.md
    └── ...
```

---

## References

- [`mapping_patterns.md`](references/mapping_patterns.md) — 13 pattern di trasformazione
- [`skill_template.md`](references/skill_template.md) — Template standardizzato SKILL.md
- [`output_examples.md`](references/output_examples.md) — Esempi di output atteso per ogni fase

---

## Note

**Questa skill è LLM-native:** Gli script sono solo per operazioni meccaniche (mkdir, ln, cp). Tutta l'analisi semantica e generazione è fatta da LLM.

**Token usage stimato:**
- Fase 1: ~5-10K token (lettura framework)
- Fase 2: ~3-5K token (mappatura)
- Fase 3: ~10-20K token (estrazione knowledge)
- Fase 4: ~15-30K token (generazione N skills)
- **Totale:** ~35-65K token per framework medio

**Vantaggi vs. script Python:**
- ✅ Comprensione semantica (non regex)
- ✅ Adattabilità a formati eterogenei
- ✅ Output specifico per dominio
- ✅ Manutenzione: ~500 linee vs. ~2000 linee

**Svantaggi:**
- ⚠️ Costo token (~35-65K per framework)
- ⚠️ Tempo: 4-8 chiamate LLM
- ⚠️ Non deterministico (mitigato con esempi)

---

_Aggiornato: 2026-03-07 | Versione: 2.0 (LLM-Native)_