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 -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: analysis_report.md                                     │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│  FASE 2: Mappatura (LLM propone, utente approva)                │
│  Input: analysis_report.md                                      │
│  Output: mapping_plan.md (approvato)                            │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│  FASE 3: Estrazione Knowledge (LLM estrae e centralizza)        │
│  Input: mapping_plan.md + file framework                        │
│  Output: references/*.md                                        │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│  FASE 4: Generazione Skills (LLM scrive SKILL.md)               │
│  Input: mapping_plan.md + references/                           │
│  Output: <framework>-skills/*/SKILL.md                          │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│  FASE 5: Packaging (Script meccanici)                           │
│  Input: skills generate + references                            │
│  Output: Suite pronta per distribuzione                         │
└─────────────────────────────────────────────────────────────────┘

---

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:

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

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

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

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

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

## 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 usando questo template:

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

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

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

Template:

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

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

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

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

<framework>-suite/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:

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

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:

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

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

<framework>-suite/<skill-name>/
└── SKILL.md

Struttura directory completa:

<framework>-suite/
├── <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:

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 01_create_dirs.sh

#!/bin/bash
# Crea struttura directory per distribuzione

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

# Crea cartella distribuzione
DIST_DIR="${FRAMEWORK_NAME}-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

#!/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

#!/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

#!/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 — 13 pattern di trasformazione
• skill_template.md — Template standardizzato SKILL.md
• 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)