Initial commit: framework-translator skill (LLM-native approach)
- SKILL.md: Istruzioni complete per LLM (Fasi 1-5) - references/mapping_patterns.md: 13 pattern di trasformazione - references/skill_template.md: Template standardizzato SKILL.md - scripts/: 3 script meccanici bash (scan, structure, packaging) - PIANO_SVILUPPO.md: Piano di sviluppo originale (documentazione) Approccio: LLM-native con script minimali per operazioni meccaniche. Token usage stimato: ~35-65K per framework. Vantaggi: comprensione semantica, adattabilità, manutenzione semplice.
This commit is contained in:
AgentePotente
commit
c40ddf4b59
9 changed files with 3344 additions and 0 deletions
22
.gitignore
vendored
Normal file
22
.gitignore
vendored
Normal file
|
|
@ -0,0 +1,22 @@
|
||||||
|
# Output generati
|
||||||
|
output/
|
||||||
|
test-output/
|
||||||
|
*.json
|
||||||
|
!package.json
|
||||||
|
|
||||||
|
# File temporanei
|
||||||
|
*.tmp
|
||||||
|
*.bak
|
||||||
|
*.swp
|
||||||
|
*~
|
||||||
|
|
||||||
|
# Directory di sistema
|
||||||
|
.DS_Store
|
||||||
|
Thumbs.db
|
||||||
|
|
||||||
|
# Script archiviati (opzionale, tienili fuori dal repo principale)
|
||||||
|
scripts-archive/
|
||||||
|
|
||||||
|
# Log
|
||||||
|
*.log
|
||||||
|
logs/
|
||||||
700
PIANO_SVILUPPO.md
Normal file
700
PIANO_SVILUPPO.md
Normal file
|
|
@ -0,0 +1,700 @@
|
||||||
|
# Framework → AgentSkills Translator
|
||||||
|
|
||||||
|
**Piano di Sviluppo per Skill Generalizzata di Trasformazione**
|
||||||
|
|
||||||
|
_Versione: 1.0 | Data: 2026-03-07 | Autore: AgentePotente_
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🎯 Obiettivo
|
||||||
|
|
||||||
|
Creare una skill **`framework-translator`** che trasformi framework testuali eterogenei (come `orto_v1`) in un set di skills AgentSkills-compatibili, strutturate e pronte per la distribuzione.
|
||||||
|
|
||||||
|
**Problema:** I framework sono spesso documenti complessi, multi-cartella, con strutture arbitrarie (agenti, workflow, knowledge, script, prompt). Trasformarli manualmente in AgentSkills richiede lavoro ripetitivo e conoscenza del formato target.
|
||||||
|
|
||||||
|
**Soluzione:** Una skill che:
|
||||||
|
1. Analizza la struttura del framework input
|
||||||
|
2. Identifica entità trasformabili (agenti, workflow, knowledge)
|
||||||
|
3. Applica pattern di mappatura predefiniti
|
||||||
|
4. Genera skills AgentSkills-compatibili con struttura standardizzata
|
||||||
|
5. Produce references centralizzate e documentazione
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📊 Analisi del Caso di Studio: orto_v1 → orto-skills
|
||||||
|
|
||||||
|
### Input: orto_v1 Framework
|
||||||
|
|
||||||
|
```
|
||||||
|
orto_v1/
|
||||||
|
├── README.md # Panoramica framework
|
||||||
|
├── orti_registry.json # Registry centrale
|
||||||
|
├── docs/
|
||||||
|
│ ├── 00_indice.md # Index documentazione
|
||||||
|
│ ├── 01_visione_e_requisiti.md # Visione prodotto
|
||||||
|
│ ├── 02_scope_e_assunzioni.md # Scope e assunzioni
|
||||||
|
│ ├── 03_architettura_multiagente.md # Architettura agenti (12)
|
||||||
|
│ ├── 04_contratti_e_messaggistica.md
|
||||||
|
│ ├── 05_sicurezza_privacy_affidabilita.md
|
||||||
|
│ ├── architettura_storage.md # Storage markdown
|
||||||
|
│ ├── agents/ # 12 agenti specializzati
|
||||||
|
│ │ ├── 00_agent_index.md
|
||||||
|
│ │ ├── 01_orchestratore_planner.md
|
||||||
|
│ │ ├── 02_agronomo_colture.md
|
||||||
|
│ │ ├── 03_stagionalita_calendario.md
|
||||||
|
│ │ ├── 04_fitopatologo_trattamenti.md
|
||||||
|
│ │ ├── 05_irrigazione_automazione.md
|
||||||
|
│ │ ├── 06_layout_zoning.md
|
||||||
|
│ │ ├── 07_nutrizione_consumi.md
|
||||||
|
│ │ ├── 08_data_knowledge_manager.md
|
||||||
|
│ │ ├── 09_ui_ux_agent.md
|
||||||
|
│ │ ├── 10_qa_safety_agent.md
|
||||||
|
│ │ ├── 11_weather_intelligence_agent.md
|
||||||
|
│ │ └── 12_ops_integrazioni_agent.md
|
||||||
|
│ ├── workflows/ # 5 workflow end-to-end
|
||||||
|
│ │ ├── 00_workflow_index.md
|
||||||
|
│ │ ├── 00_init_orto.md
|
||||||
|
│ │ ├── 01_onboarding.md
|
||||||
|
│ │ ├── 02_piano_stagionale.md
|
||||||
|
│ │ ├── 03_esecuzione_settimanale.md
|
||||||
|
│ │ ├── 04_diagnosi_problemi.md
|
||||||
|
│ │ └── 05_irrigazione_dinamica_meteo.md
|
||||||
|
│ ├── data/ # Data model
|
||||||
|
│ ├── schemas/ # JSON schemas
|
||||||
|
│ ├── gui/ # GUI specification
|
||||||
|
│ ├── skills/ # Skills catalog (17 skills)
|
||||||
|
│ │ ├── 00_skills_overview.md
|
||||||
|
│ │ └── 01_skill_catalog.md
|
||||||
|
│ ├── knowledge/ # Knowledge base
|
||||||
|
│ └── allegati/ # Templates + examples
|
||||||
|
├── prompts/
|
||||||
|
│ ├── master_prompt_openclaw.md
|
||||||
|
│ ├── prompt_onboarding.md
|
||||||
|
│ ├── prompt_init_orto.md
|
||||||
|
│ └── prompt_demo_sessione_tipo.md
|
||||||
|
└── scripts/
|
||||||
|
├── README_SCRIPTS.md
|
||||||
|
├── init_new_orto.py
|
||||||
|
├── init_orto.sh
|
||||||
|
├── json_to_md_converter.py
|
||||||
|
├── sync_md_from_agents.py
|
||||||
|
├── register_orto.py
|
||||||
|
├── template_garden_config.md
|
||||||
|
└── template_questionnaire_responses.md
|
||||||
|
```
|
||||||
|
|
||||||
|
### Output: orto-skills Suite
|
||||||
|
|
||||||
|
```
|
||||||
|
orto-suite/
|
||||||
|
├── 9 skills AgentSkills:
|
||||||
|
│ ├── orto-init/ # Da: Workflow 00 + init_new_orto.py
|
||||||
|
│ ├── orto-onboarding/ # Da: Workflow 01 + prompt_onboarding.md
|
||||||
|
│ ├── orto-agronomo/ # Da: Agente 02 + skill AGR-CROP-MIX
|
||||||
|
│ ├── orto-calendario/ # Da: Agente 03 + skill AGR-SEASONALITY
|
||||||
|
│ ├── orto-fitopatologo/ # Da: Agente 04 + skill PHYTO-DIAG + PHYTO-TREAT-BIO
|
||||||
|
│ ├── orto-layout/ # Da: Agente 06 + skill AGR-COMPANION
|
||||||
|
│ ├── orto-irrigazione/ # Da: Agente 05 + skill IRR-ZONING + IRR-SCHEDULING
|
||||||
|
│ ├── orto-meteo-decisioni/ # Da: Agente 11 + skill MET-IRR-DECISION
|
||||||
|
│ └── orto-orchestratore/ # Da: Agente 01 + QA-CONSISTENCY + merge workflow
|
||||||
|
│
|
||||||
|
├── references/ (8 file, 88 KB)
|
||||||
|
│ ├── colture_it.md # Da: docs/knowledge/ + colture catalog
|
||||||
|
│ ├── calendario_it.md # Da: docs/workflows/ + stagionalità
|
||||||
|
│ ├── malattie_trattamenti.md # Da: docs/agents/04 + knowledge fitopatologia
|
||||||
|
│ ├── irrigazione_parametri.md # Da: docs/agents/05 + knowledge irrigazione
|
||||||
|
│ ├── consociazioni_layout.md # Da: docs/agents/06 + knowledge consociazioni
|
||||||
|
│ ├── meteo_soglie.md # Da: docs/agents/11 + knowledge meteo
|
||||||
|
│ ├── conflitti_risoluzione.md # Da: docs/03_architettura_multiagente.md (sez. conflitti)
|
||||||
|
│ └── qa_checklist.md # Da: Agente 10 QA & Safety
|
||||||
|
│
|
||||||
|
└── Symlink: ogni skill → ../references (condivisi)
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🔍 Pattern di Trasformazione Distillati
|
||||||
|
|
||||||
|
### 1. **Agente → Skill (Non 1:1)**
|
||||||
|
|
||||||
|
| Pattern | Esempio | Note |
|
||||||
|
|---------|---------|------|
|
||||||
|
| **1 Agente → 1 Skill** | Agente 02 (Agronomo) → orto-agronomo | Caso ideale, quando agente è auto-contenuto |
|
||||||
|
| **1 Agente → 1 Skill + References** | Agente 05 (Irrigazione) → orto-irrigazione + irrigazione_parametri.md | Knowledge pesante estratta in references |
|
||||||
|
| **2+ Agenti → 1 Skill** | Agente 04 (Fitopatologo) + skill PHYTO-DIAG + PHYTO-TREAT-BIO → orto-fitopatologo | Agenti correlati mergiati per coerenza |
|
||||||
|
| **Agente + Workflow → Skill** | Agente 01 (Orchestratore) + Workflow 02/03/04 → orto-orchestratore | Orchestratore coordina workflow multipli |
|
||||||
|
| **Workflow → Skill** | Workflow 00 (Init) + init_new_orto.py → orto-init | Workflow con script diventa skill operativa |
|
||||||
|
| **Agente Eliminato** | Agente 08 (Data Manager), 09 (UI/UX), 12 (Ops) | Non essenziali per MVP, funzionalità assorbite |
|
||||||
|
|
||||||
|
**Regola:** Non mappare 1:1. Raggruppa per **coerenza funzionale** e **minimizza skills** mantenendo separazione of concerns.
|
||||||
|
|
||||||
|
### 2. **Knowledge → References Centralizzate**
|
||||||
|
|
||||||
|
| Input Pattern | Output Pattern |
|
||||||
|
|--------------|----------------|
|
||||||
|
| `docs/knowledge/*.md` | `references/*.md` (1:1 o mergiato) |
|
||||||
|
| `docs/agents/*/` (sezioni knowledge) | Estratte → `references/*.md` |
|
||||||
|
| `docs/skills/01_skill_catalog.md` | Mappato → references da creare |
|
||||||
|
| Tabelle, liste, parametri | Mantenuti in markdown strutturato |
|
||||||
|
|
||||||
|
**Regola:** Tutto il knowledge **pesante** (>500 linee) o **condiviso** (usato da 2+ skills) → references/. Skills leggono references on-demand.
|
||||||
|
|
||||||
|
### 3. **Workflow → Fasi nel Corpo SKILL.md**
|
||||||
|
|
||||||
|
| Input | Output |
|
||||||
|
|-------|--------|
|
||||||
|
| `docs/workflows/01_onboarding.md` | orto-onboarding: Fase 1-5 (blocchi questionario) |
|
||||||
|
| `docs/workflows/02_piano_stagionale.md` | orto-agronomo: Fase 1-4 (filtra, candidate, costruisci piano) |
|
||||||
|
| `docs/workflows/03_esecuzione_settimanale.md` | orto-calendario: Fase 1-3 (genera task, meteo-check, output) |
|
||||||
|
|
||||||
|
**Regola:** Ogni workflow diventa una **sequenza di fasi** nel corpo della skill. Mantenere nomi fasi descrittivi (Fase 1: Filtra Colture per Vincoli).
|
||||||
|
|
||||||
|
### 4. **Scripts → scripts/ nella Skill (Opzionale)**
|
||||||
|
|
||||||
|
| Input | Output | Decisione |
|
||||||
|
|-------|--------|-----------|
|
||||||
|
| `init_new_orto.py` (20 KB) | Integrato in orto-init (logica inline) | Script semplice → inline nel corpo |
|
||||||
|
| `json_to_md_converter.py` | Non incluso | Utility una-tantum, non needed runtime |
|
||||||
|
| `sync_md_from_agents.py` | Non incluso | QA tool, non needed runtime |
|
||||||
|
|
||||||
|
**Regola:** Includere `scripts/` solo se:
|
||||||
|
- Script è **riutilizzabile** (eseguito multiple volte)
|
||||||
|
- Script è **deterministico** (no modifiche ambientali)
|
||||||
|
- Script è **più efficiente** che riscriverlo ogni volta
|
||||||
|
|
||||||
|
### 5. **Storage Architecture → Documentato in SKILL.md**
|
||||||
|
|
||||||
|
| Input | Output |
|
||||||
|
|-------|--------|
|
||||||
|
| `docs/architettura_storage.md` | Sezione "Gestione Progetti & Registry" in orto-orchestratore + orto-init |
|
||||||
|
| Struttura directory orto/ | Documentata in SKILL.md con tree markdown |
|
||||||
|
| Registry JSON | Specificato formato + percorso in SKILL.md |
|
||||||
|
|
||||||
|
**Regola:** La skill deve sapere **dove leggere/scrivere**. Documentare struttura directory e convenzioni naming nel corpo SKILL.md.
|
||||||
|
|
||||||
|
### 6. **Prompts → Integrati o Eliminati**
|
||||||
|
|
||||||
|
| Input | Output |
|
||||||
|
|-------|--------|
|
||||||
|
| `prompts/master_prompt_openclaw.md` | Non incluso (era prompt di generazione, non runtime) |
|
||||||
|
| `prompts/prompt_onboarding.md` | Integrato in orto-onboarding (Fase 1: Raccolta Dati) |
|
||||||
|
| `prompts/prompt_init_orto.md` | Integrato in orto-init (Input section) |
|
||||||
|
|
||||||
|
**Regola:** Prompt che sono **template di input** → integrati come sezioni Input nella skill. Prompt di **generazione framework** → eliminati (non servono runtime).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🏗️ Architettura della Skill `framework-translator`
|
||||||
|
|
||||||
|
### Struttura Proposta
|
||||||
|
|
||||||
|
```
|
||||||
|
framework-translator/
|
||||||
|
├── SKILL.md # Istruzioni traduzione
|
||||||
|
├── scripts/
|
||||||
|
│ ├── analyze_framework.py # Analizza struttura input
|
||||||
|
│ ├── map_entities.py # Mappa agenti/workflow → skills
|
||||||
|
│ ├── extract_knowledge.py # Estrae knowledge → references
|
||||||
|
│ ├── generate_skill.py # Genera SKILL.md da template
|
||||||
|
│ └── validate_output.py # Valida skills generate
|
||||||
|
├── references/
|
||||||
|
│ ├── mapping_patterns.md # Pattern di mappatura (tabella sopra)
|
||||||
|
│ ├── skill_template.md # Template SKILL.md standardizzato
|
||||||
|
│ ├── agent_analysis_checklist.md # Checklist analisi agenti
|
||||||
|
│ └── quality_criteria.md # Criteri QA per skills generate
|
||||||
|
└── assets/
|
||||||
|
└── example_outputs/ # Esempi: orto_v1 → orto-skills
|
||||||
|
```
|
||||||
|
|
||||||
|
### Frontmatter (Bozza)
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
name: framework-translator
|
||||||
|
description: Trasformare framework testuali eterogenei (multi-cartella, multi-agente, workflow) in set di skills AgentSkills-compatibili. Usare quando: (1) convertire framework esistente in skills eseguibili, (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.
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📋 Processo di Traduzione (Workflow della Skill)
|
||||||
|
|
||||||
|
### Fase 1: Analisi Framework Input
|
||||||
|
|
||||||
|
**Obiettivo:** Capire struttura, entità, dipendenze del framework input.
|
||||||
|
|
||||||
|
**Input:** Percorso framework (es. `/path/to/framework/`)
|
||||||
|
|
||||||
|
**Azioni:**
|
||||||
|
|
||||||
|
1. **Scansiona struttura directory**
|
||||||
|
```bash
|
||||||
|
find <framework_path> -type f -name "*.md" | head -50
|
||||||
|
```
|
||||||
|
|
||||||
|
2. **Identifica cartelle chiave**
|
||||||
|
- `agents/` o `agenti/` → Agenti da trasformare
|
||||||
|
- `workflows/` o `flussi/` → Workflow da mappare
|
||||||
|
- `knowledge/` o `docs/` → Knowledge da estrarre
|
||||||
|
- `scripts/` → Script da valutare
|
||||||
|
- `prompts/` → Prompt da integrare
|
||||||
|
|
||||||
|
3. **Leggi file index/overview**
|
||||||
|
- `agents/00_agent_index.md` o simile
|
||||||
|
- `workflows/00_workflow_index.md` o simile
|
||||||
|
- `README.md` del framework
|
||||||
|
|
||||||
|
4. **Estrai metadata agenti**
|
||||||
|
Per ogni file agente:
|
||||||
|
- Nome agente
|
||||||
|
- Missione/responsabilità
|
||||||
|
- Input/output (se specificati)
|
||||||
|
- Skills richieste (se specificate)
|
||||||
|
- Regole decisionali
|
||||||
|
|
||||||
|
5. **Estrai metadata workflow**
|
||||||
|
Per ogni workflow:
|
||||||
|
- Nome workflow
|
||||||
|
- Trigger/condizioni
|
||||||
|
- Fasi/step
|
||||||
|
- Agenti coinvolti
|
||||||
|
|
||||||
|
**Output:** `analysis_report.md` con:
|
||||||
|
- Lista agenti (N totale, nomi, responsabilità)
|
||||||
|
- Lista workflow (N totale, nomi, agenti coinvolti)
|
||||||
|
- Knowledge base identificata (file, dimensioni, argomenti)
|
||||||
|
- Scripts valutati (includere? sì/no + motivo)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Fase 2: Mappatura Entità → Skills
|
||||||
|
|
||||||
|
**Obiettivo:** Decidere come trasformare agenti + workflow in skills.
|
||||||
|
|
||||||
|
**Input:** `analysis_report.md`
|
||||||
|
|
||||||
|
**Azioni:**
|
||||||
|
|
||||||
|
1. **Applica pattern di mappatura** (da references/mapping_patterns.md)
|
||||||
|
- 1 Agente → 1 Skill (se auto-contenuto)
|
||||||
|
- 2+ Agenti → 1 Skill (se correlati funzionalmente)
|
||||||
|
- Workflow → Skill (se operativo, con script)
|
||||||
|
- Agente + Workflow → Skill (se orchestrazione)
|
||||||
|
|
||||||
|
2. **Raggruppa per coerenza funzionale**
|
||||||
|
```
|
||||||
|
Esempio:
|
||||||
|
- Agronomo Colture + Nutrizione & Consumi → orto-agronomo (se overlap forte)
|
||||||
|
- Fitopatologo + Trattamenti → orto-fitopatologo (già uniti)
|
||||||
|
- Irrigazione + Automazione → orto-irrigazione (mantieni unito)
|
||||||
|
```
|
||||||
|
|
||||||
|
3. **Identifica orchestratore**
|
||||||
|
- Quale skill coordina le altre?
|
||||||
|
- Di solito: Agente 01 (Planner/Orchestratore) + QA
|
||||||
|
|
||||||
|
4. **Identifica references necessarie**
|
||||||
|
- Quali knowledge sono condivisi da 2+ skills?
|
||||||
|
- Quali sono troppo pesanti per il corpo SKILL.md?
|
||||||
|
|
||||||
|
**Output:** `mapping_plan.md` con:
|
||||||
|
- Skills da generare (N totale, nomi, agenti/workflow di origine)
|
||||||
|
- References da creare (N totale, nomi, contenuti)
|
||||||
|
- Giustificazione decisioni di mappatura
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Fase 3: Estrazione Knowledge → References
|
||||||
|
|
||||||
|
**Obiettivo:** Centralizzare knowledge in file references condivisi.
|
||||||
|
|
||||||
|
**Input:** `mapping_plan.md` + framework source files
|
||||||
|
|
||||||
|
**Azioni:**
|
||||||
|
|
||||||
|
1. **Per ogni reference pianificata:**
|
||||||
|
- Identifica file sorgente nel framework
|
||||||
|
- Estrai contenuto rilevante (tabelle, liste, parametri)
|
||||||
|
- Riformatta in markdown strutturato (TOC, sezioni, tabelle)
|
||||||
|
- Normalizza naming (lowercase, underscore)
|
||||||
|
|
||||||
|
2. **Applica criterio di inclusion**
|
||||||
|
- Includere: Dati fattuali, parametri, tabelle, regole
|
||||||
|
- Escludere: Narrative, introduzioni lunghe, esempi ridondanti
|
||||||
|
|
||||||
|
3. **Crea symlink plan**
|
||||||
|
- Quali skills useranno quale reference?
|
||||||
|
- Documenta nel file reference (header: "Usato da: skill-X, skill-Y")
|
||||||
|
|
||||||
|
**Output:** Cartella `references/` con N file `.md`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Fase 4: Generazione Skills
|
||||||
|
|
||||||
|
**Obiettivo:** Creare N skills AgentSkills-compatibili.
|
||||||
|
|
||||||
|
**Input:** `mapping_plan.md` + `references/` + framework source
|
||||||
|
|
||||||
|
**Azioni:**
|
||||||
|
|
||||||
|
1. **Per ogni skill pianificata:**
|
||||||
|
|
||||||
|
a. **Genera frontmatter YAML**
|
||||||
|
```yaml
|
||||||
|
name: <skill-name>
|
||||||
|
description: <descrizione concisa con trigger e output>
|
||||||
|
```
|
||||||
|
|
||||||
|
b. **Genera corpo SKILL.md** (usa template da references/skill_template.md)
|
||||||
|
- **Quando Usare:** 3-5 scenari trigger
|
||||||
|
- **Input:** Tabella input richiesti (nome, tipo, obbligatorio, esempio)
|
||||||
|
- **Processo:**
|
||||||
|
- Fase 1: <nome fase> (da workflow o agente)
|
||||||
|
- Fase 2: <nome fase>
|
||||||
|
- ...
|
||||||
|
- **Output:** File/documento generato, formato, struttura
|
||||||
|
- **Gestione Progetti:** (se applicabile) Struttura directory, registry
|
||||||
|
- **References:** Elenco references usate con link
|
||||||
|
|
||||||
|
c. **Integra script** (se deciso in Fase 2)
|
||||||
|
- Copia script in `scripts/` della skill
|
||||||
|
- Documenta uso nel corpo SKILL.md
|
||||||
|
|
||||||
|
d. **Valida struttura**
|
||||||
|
- Frontmatter presente e valido?
|
||||||
|
- Corpo <500 linee (o references usate)?
|
||||||
|
- References linkati esistono?
|
||||||
|
|
||||||
|
2. **Crea struttura skill**
|
||||||
|
```
|
||||||
|
<skill-name>/
|
||||||
|
├── SKILL.md
|
||||||
|
├── scripts/ (opzionale)
|
||||||
|
└── README.md (opzionale, solo se utile per umani)
|
||||||
|
```
|
||||||
|
|
||||||
|
**Output:** Cartella `<framework>-skills/` con N sottocartelle skill
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Fase 5: Packaging e Documentazione
|
||||||
|
|
||||||
|
**Obiettivo:** Rendere le skills pronte per distribuzione.
|
||||||
|
|
||||||
|
**Input:** Cartella `<framework>-skills/`
|
||||||
|
|
||||||
|
**Azioni:**
|
||||||
|
|
||||||
|
1. **Crea references centralizzate**
|
||||||
|
- Sposta `references/` in root di `<framework>-skills/`
|
||||||
|
- Crea symlink in ogni skill → `../references`
|
||||||
|
|
||||||
|
2. **Genera INSTALL.sh**
|
||||||
|
```bash
|
||||||
|
#!/bin/bash
|
||||||
|
# Script installazione framework-skills
|
||||||
|
SOURCE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
||||||
|
TARGET="$HOME/.openclaw/skills/<framework>-skills"
|
||||||
|
|
||||||
|
echo "Installing <framework>-skills..."
|
||||||
|
cp -r "$SOURCE/<framework>-suite" "$TARGET"
|
||||||
|
echo "Installation complete!"
|
||||||
|
```
|
||||||
|
|
||||||
|
3. **Genera README.md root**
|
||||||
|
- Panoramica framework
|
||||||
|
- Lista skills (N totale, nomi, descrizioni brevi)
|
||||||
|
- Istruzioni installazione (3 metodi: script, manuale, chat-only)
|
||||||
|
- Struttura directory
|
||||||
|
|
||||||
|
4. **Validazione finale**
|
||||||
|
- Tutte le skills hanno SKILL.md valido?
|
||||||
|
- Tutti i references linkati esistono?
|
||||||
|
- INSTALL.sh funziona?
|
||||||
|
- README.md chiaro?
|
||||||
|
|
||||||
|
**Output:** Pacchetto pronto per distribuzione
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ✅ Criteri di Qualità (QA Checklist)
|
||||||
|
|
||||||
|
### Per Ogni Skill Generata
|
||||||
|
|
||||||
|
- [ ] **Frontmatter YAML valido** (name + description presenti)
|
||||||
|
- [ ] **Descrizione trigger-specifica** (include "Usare quando:" con 3+ scenari)
|
||||||
|
- [ ] **Corpo <500 linee** (o references usate appropriatamente)
|
||||||
|
- [ ] **Fasi numerate e nominate** (Fase 1: <nome>, Fase 2: <nome>, ...)
|
||||||
|
- [ ] **Output documentato** (file, formato, struttura)
|
||||||
|
- [ ] **References linkati** (se usati, percorsi corretti)
|
||||||
|
- [ ] **Niente JSON per dati** (solo markdown, tranne registry)
|
||||||
|
- [ ] **Niente sezioni ridondanti** (no "When to Use" nel corpo se già in description)
|
||||||
|
|
||||||
|
### Per Ogni Reference
|
||||||
|
|
||||||
|
- [ ] **TOC in header** (se >100 linee)
|
||||||
|
- [ ] **Contenuto strutturato** (tabelle, liste, sezioni)
|
||||||
|
- [ ] **Niente narrative** (solo dati fattuali, parametri, regole)
|
||||||
|
- [ ] **Header con metadata** (Usato da: skill-X, skill-Y)
|
||||||
|
- [ ] **Nome lowercase underscore** (es. `colture_it.md`)
|
||||||
|
|
||||||
|
### Per Pacchetto Complessivo
|
||||||
|
|
||||||
|
- [ ] **Struttura ultra-semplice** (una cartella da copiare)
|
||||||
|
- [ ] **Symlink funzionanti** (tutti risolti)
|
||||||
|
- [ ] **INSTALL.sh testato** (esecuzione verificata)
|
||||||
|
- [ ] **README.md chiaro** (installazione in 3 metodi)
|
||||||
|
- [ ] **Niente file ridondanti** (no build/, no guide duplicate)
|
||||||
|
- [ ] **Git-initialized** (ogni skill ha `.git/` se richiesto)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🧪 Piano di Test
|
||||||
|
|
||||||
|
### Test 1: Framework Semplice (1-2 agenti)
|
||||||
|
|
||||||
|
**Input:** Framework minimale con 2 agenti + 1 workflow
|
||||||
|
|
||||||
|
**Obiettivo:** Verificare mappatura base 1:1
|
||||||
|
|
||||||
|
**Criteri successo:**
|
||||||
|
- 2 skills generate
|
||||||
|
- 1 reference (se knowledge condiviso)
|
||||||
|
- INSTALL.sh funziona
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Test 2: Framework Medio (5-7 agenti)
|
||||||
|
|
||||||
|
**Input:** Framework con 5-7 agenti + 3 workflow + knowledge
|
||||||
|
|
||||||
|
**Obiettivo:** Verificare raggruppamento agenti correlati
|
||||||
|
|
||||||
|
**Criteri successo:**
|
||||||
|
- 4-5 skills generate (alcuni merge)
|
||||||
|
- 3-4 references centralizzate
|
||||||
|
- Orchestratore identificato correttamente
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Test 3: Framework Complesso (10+ agenti)
|
||||||
|
|
||||||
|
**Input:** orto_v1 o simile (12 agenti, 5 workflow, knowledge estesa)
|
||||||
|
|
||||||
|
**Obiettivo:** Verificare scala completa
|
||||||
|
|
||||||
|
**Criteri successo:**
|
||||||
|
- 8-10 skills generate (merge ottimizzati)
|
||||||
|
- 6-10 references
|
||||||
|
- Conflitti gestiti (documentati in reference conflitti)
|
||||||
|
- Pacchetto pronto per produzione
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📅 Roadmap di Sviluppo
|
||||||
|
|
||||||
|
### Sprint 1: Core Infrastructure (2-3 sessioni)
|
||||||
|
|
||||||
|
- [ ] Creare struttura skill `framework-translator`
|
||||||
|
- [ ] Scrivere `references/mapping_patterns.md` (pattern distillati sopra)
|
||||||
|
- [ ] Scrivere `references/skill_template.md` (template standardizzato)
|
||||||
|
- [ ] Implementare `scripts/analyze_framework.py`
|
||||||
|
- [ ] Testare su framework semplice (mock o reale)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Sprint 2: Estrazione e Mappatura (3-4 sessioni)
|
||||||
|
|
||||||
|
- [ ] Implementare `scripts/map_entities.py`
|
||||||
|
- [ ] Implementare `scripts/extract_knowledge.py`
|
||||||
|
- [ ] Scrivere `references/agent_analysis_checklist.md`
|
||||||
|
- [ ] Testare su framework medio (5-7 agenti)
|
||||||
|
- [ ] Raffinare pattern di mappatura basato su test
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Sprint 3: Generazione Skills (4-5 sessioni)
|
||||||
|
|
||||||
|
- [ ] Implementare `scripts/generate_skill.py`
|
||||||
|
- [ ] Scrivere `references/quality_criteria.md`
|
||||||
|
- [ ] Implementare validazione output
|
||||||
|
- [ ] Testare su orto_v1 (framework complesso)
|
||||||
|
- [ ] Confrontare output con orto-skills manuali (gap analysis)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Sprint 4: Packaging e Documentazione (2-3 sessioni)
|
||||||
|
|
||||||
|
- [ ] Implementare `scripts/validate_output.py`
|
||||||
|
- [ ] Automatizzare creazione symlink
|
||||||
|
- [ ] Generare INSTALL.sh dinamico
|
||||||
|
- [ ] Generare README.md dinamico
|
||||||
|
- [ ] Documentare skill (corpo SKILL.md completo)
|
||||||
|
- [ ] Test end-to-end su 2-3 framework diversi
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Sprint 5: Refinement e Production (2-3 sessioni)
|
||||||
|
|
||||||
|
- [ ] Raccogliere feedback da test reali
|
||||||
|
- [ ] Ottimizzare pattern di mappatura
|
||||||
|
- [ ] Migliorare gestione edge cases
|
||||||
|
- [ ] Scrivere esempi in `assets/example_outputs/`
|
||||||
|
- [ ] Pubblicare skill (clawhub o manuale)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🔧 Edge Cases da Gestire
|
||||||
|
|
||||||
|
### 1. Framework Non-Standard
|
||||||
|
|
||||||
|
**Problema:** Framework senza cartelle `agents/` o `workflows/`
|
||||||
|
|
||||||
|
**Soluzione:**
|
||||||
|
- Scansione euristica (cerca file con "agent", "workflow", "skill" nel nome)
|
||||||
|
- Chiedi all'utente di identificare entità principali
|
||||||
|
- Fallback: tratta ogni file `.md` come potenziale skill
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 2. Agenti con Overlap Funzionale Forte
|
||||||
|
|
||||||
|
**Problema:** 2+ agenti con responsabilità quasi identiche
|
||||||
|
|
||||||
|
**Soluzione:**
|
||||||
|
- Rileva overlap (confronta descrizioni missione)
|
||||||
|
- Suggerisci merge in skill unica
|
||||||
|
- Documenta decisione in `mapping_plan.md`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 3. Knowledge Molto Grande (>50 KB)
|
||||||
|
|
||||||
|
**Problema:** Single reference file troppo pesante
|
||||||
|
|
||||||
|
**Soluzione:**
|
||||||
|
- Splitta per argomento (es. `colture_it.md` → `colture_nord.md`, `colture_centro.md`, `colture_sud.md`)
|
||||||
|
- Usa TOC dettagliato per navigazione
|
||||||
|
- Documenta in SKILL.md quando leggere quale parte
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 4. Workflow con Dipendenze Cicliche
|
||||||
|
|
||||||
|
**Problema:** Workflow A richiede output di B, B richiede output di A
|
||||||
|
|
||||||
|
**Soluzione:**
|
||||||
|
- Rileva cicli (grafo dipendenze)
|
||||||
|
- Segnala all'utente (richiede refactoring framework)
|
||||||
|
- Fallback: crea skill orchestratore che gestisce iterazione
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 5. Script con Dipendenze Esterne
|
||||||
|
|
||||||
|
**Problema:** Script richiedono librerie Python non standard
|
||||||
|
|
||||||
|
**Soluzione:**
|
||||||
|
- Documenta dipendenze in `scripts/README.md`
|
||||||
|
- Genera `requirements.txt` per la skill
|
||||||
|
- Valuta se includere script o convertire logica in markdown
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📝 Decisioni di Progetto
|
||||||
|
|
||||||
|
### 1. Naming Convention
|
||||||
|
|
||||||
|
**Decisione:** Skill names in `lowercase-kebab-case` con prefix del framework
|
||||||
|
|
||||||
|
**Esempio:** `orto-init`, `orto-agronomo`, `framework-translator`
|
||||||
|
|
||||||
|
**Motivo:** Coerente con AgentSkills esistenti, leggibile, git-friendly
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 2. References: Copie o Symlink?
|
||||||
|
|
||||||
|
**Decisione:** Symlink centralizzati (una copia, N link)
|
||||||
|
|
||||||
|
**Motivo:**
|
||||||
|
- Aggiornamenti automatici (modifichi reference, tutte skills vedono cambio)
|
||||||
|
- Risparmio spazio (no duplicati)
|
||||||
|
- Coerente con orto-skills
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 3. Script: Includere o Inline?
|
||||||
|
|
||||||
|
**Decisione:** Includere solo se riutilizzabile e deterministico
|
||||||
|
|
||||||
|
**Motivo:**
|
||||||
|
- Script una-tantum → inline nel corpo (meno complessità)
|
||||||
|
- Script riutilizzabile → `scripts/` (efficienza, token savings)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 4. Output: Una Cartella o N Cartelle Separate?
|
||||||
|
|
||||||
|
**Decisione:** Una cartella `<framework>-suite/` con tutte skills + references
|
||||||
|
|
||||||
|
**Motivo:**
|
||||||
|
- Ultra-semplice da installare (cp -r)
|
||||||
|
- References centralizzati
|
||||||
|
- Coerente con orto-skills
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🎓 Lezioni Apprese da orto_v1 → orto-skills
|
||||||
|
|
||||||
|
### Cosa Ha Funzionato Bene
|
||||||
|
|
||||||
|
1. **Raggruppamento agenti correlati** (es. Fitopatologo + Trattamenti → 1 skill)
|
||||||
|
2. **References centralizzate** (8 file, 88 KB, condivisi da 9 skills)
|
||||||
|
3. **Symlink per references** (aggiornamenti automatici, no duplicati)
|
||||||
|
4. **Una cartella da copiare** (installazione ultra-semplice)
|
||||||
|
5. **Documentazione fasi nel corpo** (Fase 1, Fase 2, ... chiaro e azionabile)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Cosa Potrebbe Migliorare
|
||||||
|
|
||||||
|
1. **Automazione analisi iniziale** (fatta manuale, potrebbe essere script)
|
||||||
|
2. **Pattern di mappatura documentati prima** (abbiamo distillato dopo)
|
||||||
|
3. **Validazione QA automatizzata** (fatta manuale, checklist non eseguita automaticamente)
|
||||||
|
4. **Gestione conflitti** (documentata in reference, ma potrebbe essere più esplicita nel processo)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Pattern da Preservare
|
||||||
|
|
||||||
|
1. **Progressive disclosure** (metadata → SKILL.md → references)
|
||||||
|
2. **Concise is key** (SKILL.md <500 linee, references per dettagli)
|
||||||
|
3. **Human-readable output** (markdown, tabelle, liste, no JSON per dati)
|
||||||
|
4. **Audit trail** (documentare decisioni in mapping_plan.md)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🚀 Prossimi Passi Immediati
|
||||||
|
|
||||||
|
1. **Creare cartella `framework-translator/`** nel workspace
|
||||||
|
2. **Scrivere SKILL.md bozza** (frontmatter + processo alto livello)
|
||||||
|
3. **Creare `references/mapping_patterns.md`** (pattern distillati sopra)
|
||||||
|
4. **Creare `references/skill_template.md`** (template standardizzato)
|
||||||
|
5. **Testare analisi su orto_v1** (run manuale di Fase 1)
|
||||||
|
6. **Iterare basato su risultati**
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📌 Note Finali
|
||||||
|
|
||||||
|
**Questa skill è meta:** Trasforma framework in skills, che a loro volta potrebbero essere usate per trasformare altri framework.
|
||||||
|
|
||||||
|
**Valore principale:** Riduce tempo di trasformazione da **giorni/settimane** a **ore**, con consistenza e qualità prevedibili.
|
||||||
|
|
||||||
|
**Rischio principale:** Over-engineering. Mantenere skill semplice e focalizzata su pattern comuni. Edge cases gestiti con escalation all'utente.
|
||||||
|
|
||||||
|
**Successo metrico:** Framework trasformato in ≤4 ore, con QA score ≥0.9 (da qa_checklist.md).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
_Fine del documento di piano. Pronto per revisione e feedback._
|
||||||
455
references/mapping_patterns.md
Normal file
455
references/mapping_patterns.md
Normal file
|
|
@ -0,0 +1,455 @@
|
||||||
|
# Mapping Patterns — Trasformazione Framework → AgentSkills
|
||||||
|
|
||||||
|
_Pattern di mappatura per trasformare entità framework (agenti, workflow, knowledge) in skills AgentSkills-compatibili._
|
||||||
|
|
||||||
|
_Usato da: framework-translator (Fase 2)_
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Panoramica
|
||||||
|
|
||||||
|
Questa reference documenta i pattern di trasformazione usati in **Fase 2: Mappatura Entità → Skills** del processo `framework-translator`.
|
||||||
|
|
||||||
|
Ogni pattern include:
|
||||||
|
- **Descrizione:** Quando applicare il pattern
|
||||||
|
- **Esempio:** Caso concreto da orto_v1 → orto-skills
|
||||||
|
- **Criteri:** Condizioni per applicare il pattern
|
||||||
|
- **Output:** Cosa genera il pattern
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Pattern 1: 1 Agente → 1 Skill
|
||||||
|
|
||||||
|
**Descrizione:** Un agente auto-contenuto con responsabilità chiara diventa una skill singola.
|
||||||
|
|
||||||
|
**Esempio:**
|
||||||
|
```
|
||||||
|
Input: Agente 02 "Agronomo Colture" (piano colture, varietà, rotazioni)
|
||||||
|
Output: orto-agronomo skill
|
||||||
|
```
|
||||||
|
|
||||||
|
**Criteri:**
|
||||||
|
- Agente ha missione ben definita e singola
|
||||||
|
- Non ha overlap significativo con altri agenti (<30%)
|
||||||
|
- Knowledge richiesta è specifica del dominio
|
||||||
|
- Output è chiaramente identificabile
|
||||||
|
|
||||||
|
**Output:**
|
||||||
|
- 1 skill con nome `<prefix>-<agente-name>` (kebab-case)
|
||||||
|
- Corpo SKILL.md con fasi derivate da workflow associati
|
||||||
|
- References: knowledge specifica dell'agente
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Pattern 2: 2+ Agenti → 1 Skill (Merge Funzionale)
|
||||||
|
|
||||||
|
**Descrizione:** Agenti con responsabilità correlate o overlap funzionale sono mergiati in una skill unica.
|
||||||
|
|
||||||
|
**Esempio:**
|
||||||
|
```
|
||||||
|
Input: Agente 04 "Fitopatologo" + Skill PHYTO-DIAG + PHYTO-TREAT-BIO
|
||||||
|
Output: orto-fitopatologo skill (diagnosi + trattamenti unificati)
|
||||||
|
```
|
||||||
|
|
||||||
|
**Criteri:**
|
||||||
|
- Overlap funzionale >50% (confronta descrizioni missione)
|
||||||
|
- Agenti lavorano sullo stesso output/documento
|
||||||
|
- Separazione è artificiale (storica, non funzionale)
|
||||||
|
- Merge semplifica UX senza perdere chiarezza
|
||||||
|
|
||||||
|
**Output:**
|
||||||
|
- 1 skill con nome che copre tutte le responsabilità
|
||||||
|
- Corpo SKILL.md con sezioni distinte per ogni sotto-funzionalità
|
||||||
|
- References: knowledge condivisa tra agenti originali
|
||||||
|
|
||||||
|
**Giustificazione da documentare:**
|
||||||
|
```markdown
|
||||||
|
### Decisione: Merge Agente 04 + PHYTO-DIAG + PHYTO-TREAT-BIO
|
||||||
|
|
||||||
|
**Motivo:** Diagnosi e trattamenti sono strettamente accoppiati nel workflow reale.
|
||||||
|
Separarli richiederebbe all'utente due skill distinte per un singolo task.
|
||||||
|
|
||||||
|
**Vantaggi:**
|
||||||
|
- UX semplificata (una skill per "problema piante")
|
||||||
|
- Meno context switching
|
||||||
|
- Knowledge condivisa (malattie, trattamenti) centralizzata
|
||||||
|
|
||||||
|
**Rischi:**
|
||||||
|
- Skill più grande (gestito con references separate)
|
||||||
|
- Mitigazione: sezioni chiare nel corpo SKILL.md
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Pattern 3: Workflow → Skill Operativa
|
||||||
|
|
||||||
|
**Descrizione:** Un workflow end-to-end con script associato diventa una skill operativa.
|
||||||
|
|
||||||
|
**Esempio:**
|
||||||
|
```
|
||||||
|
Input: Workflow 00 "Inizializzazione Orto" + init_new_orto.py
|
||||||
|
Output: orto-init skill
|
||||||
|
```
|
||||||
|
|
||||||
|
**Criteri:**
|
||||||
|
- Workflow ha trigger chiaro (es. "nuovo progetto")
|
||||||
|
- Workflow produce output tangibile (struttura directory, file)
|
||||||
|
- Script esistente automatizza il workflow
|
||||||
|
- Workflow è eseguible in modo autonomo (no dipendenze da altri workflow)
|
||||||
|
|
||||||
|
**Output:**
|
||||||
|
- 1 skill con nome `<prefix>-<workflow-name>`
|
||||||
|
- Script incluso in `scripts/` della skill (se riutilizzabile)
|
||||||
|
- Corpo SKILL.md descrive fasi del workflow
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Pattern 4: Agente + Workflow → Skill Orchestratore
|
||||||
|
|
||||||
|
**Descrizione:** Agente di coordinamento + workflow multipli diventano skill orchestratore.
|
||||||
|
|
||||||
|
**Esempio:**
|
||||||
|
```
|
||||||
|
Input: Agente 01 "Orchestratore/Planner" + Workflow 02/03/04 + QA Agent
|
||||||
|
Output: orto-orchestratore skill
|
||||||
|
```
|
||||||
|
|
||||||
|
**Criteri:**
|
||||||
|
- Agente ha responsabilità di coordinamento
|
||||||
|
- Workflow multipli coinvolgono questo agente
|
||||||
|
- Skill deve risolvere conflitti tra output di altre skills
|
||||||
|
- QA/validazione è parte del coordinamento
|
||||||
|
|
||||||
|
**Output:**
|
||||||
|
- 1 skill con nome `<prefix>-orchestratore` o `<prefix>-planner`
|
||||||
|
- Corpo SKILL.md con sezione "Risoluzione Conflitti"
|
||||||
|
- Reference: `conflitti_risoluzione.md` (pattern di risoluzione)
|
||||||
|
- Output: PlanBundle unificato o documento master
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Pattern 5: Agente Eliminato (Non Essenziale)
|
||||||
|
|
||||||
|
**Descrizione:** Agente non essenziale per MVP viene eliminato, senza creare skill.
|
||||||
|
|
||||||
|
**Esempio:**
|
||||||
|
```
|
||||||
|
Input: Agente 08 "Data/Knowledge Manager", Agente 09 "UI/UX Agent", Agente 12 "Ops & Integrazioni"
|
||||||
|
Output: Nessuna skill generata (funzionalità assorbite o posticipate)
|
||||||
|
```
|
||||||
|
|
||||||
|
**Criteri:**
|
||||||
|
- Agente gestisce funzionalità non critiche per MVP
|
||||||
|
- Funzionalità può essere posticipata a v2
|
||||||
|
- Altre skills possono assorbire responsabilità minori
|
||||||
|
- Eliminare semplifica senza perdere valore
|
||||||
|
|
||||||
|
**Output:**
|
||||||
|
- Nessuna skill generata
|
||||||
|
- Documenta in `mapping_plan.md` sezione "Eliminati"
|
||||||
|
- Eventuali funzionalità critiche assorbite da altre skills
|
||||||
|
|
||||||
|
**Giustificazione da documentare:**
|
||||||
|
```markdown
|
||||||
|
### Decisione: Eliminare Agente 09 (UI/UX)
|
||||||
|
|
||||||
|
**Motivo:** UI/UX è importante ma non essenziale per MVP testuale.
|
||||||
|
Skill AgentSkills sono per automazione, non per generazione UI.
|
||||||
|
|
||||||
|
**Funzionalità perse:**
|
||||||
|
- Wireframe generation
|
||||||
|
- Componenti UI specs
|
||||||
|
|
||||||
|
**Recupero futuro:**
|
||||||
|
- Skill separata "ui-generator" in v2
|
||||||
|
- Per ora: documentazione UI rimane in docs/ del framework
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Pattern 6: Agente Assorbito (Funzionalità Merge)
|
||||||
|
|
||||||
|
**Descrizione:** Agente con funzionalità micro o ridondante viene assorbito da altra skill.
|
||||||
|
|
||||||
|
**Esempio:**
|
||||||
|
```
|
||||||
|
Input: Agente 10 "QA & Safety Agent"
|
||||||
|
Output: Funzionalità QA assorbite da orto-orchestratore
|
||||||
|
```
|
||||||
|
|
||||||
|
**Criteri:**
|
||||||
|
- Agente ha responsabilità di validazione/check
|
||||||
|
- Validazione può essere integrata in altra skill (es. orchestratore)
|
||||||
|
- Separare richiederebbe skill troppo piccola (<100 linee)
|
||||||
|
- Assorbire migliora coesione
|
||||||
|
|
||||||
|
**Output:**
|
||||||
|
- Nessuna skill separata generata
|
||||||
|
- Funzionalità QA documentate in skill assorbente (es. orchestratore)
|
||||||
|
- Reference: `qa_checklist.md` (condivisa)
|
||||||
|
|
||||||
|
**Giustificazione da documentare:**
|
||||||
|
```markdown
|
||||||
|
### Decisione: Assorbire Agente 10 (QA) in Orchestratore
|
||||||
|
|
||||||
|
**Motivo:** QA è parte naturale del processo di orchestrazione.
|
||||||
|
Separare richiederebbe due step (genera → valida) invece di uno integrato.
|
||||||
|
|
||||||
|
**Vantaggi:**
|
||||||
|
- Workflow più fluido (validazione inline)
|
||||||
|
- Meno skills da gestire
|
||||||
|
- QA context-aware (orchestratore conosce tutto il piano)
|
||||||
|
|
||||||
|
**Implementazione:**
|
||||||
|
- orto-orchestratore include sezione "Validazione QA"
|
||||||
|
- Reference qa_checklist.md consultata durante orchestrazione
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Pattern 7: Knowledge → Reference Centralizzata
|
||||||
|
|
||||||
|
**Descrizione:** Knowledge condivisa da 2+ skills o >500 linee diventa reference centralizzata.
|
||||||
|
|
||||||
|
**Esempio:**
|
||||||
|
```
|
||||||
|
Input: docs/knowledge/colture.md (20 KB, usato da Agronomo + Layout)
|
||||||
|
Output: references/colture_it.md (symlink da entrambe le skills)
|
||||||
|
```
|
||||||
|
|
||||||
|
**Criteri:**
|
||||||
|
- Knowledge usata da 2+ skills diverse
|
||||||
|
- Knowledge >500 linee o >10 KB
|
||||||
|
- Knowledge è dominio-specifica (tabelle, parametri, regole)
|
||||||
|
- Knowledge è relativamente statica (non cambia per progetto)
|
||||||
|
|
||||||
|
**Output:**
|
||||||
|
- File `references/<nome>.md`
|
||||||
|
- Symlink da ogni skill che la usa → `../references/<nome>.md`
|
||||||
|
- Header nel reference: "Usato da: skill-X, skill-Y"
|
||||||
|
|
||||||
|
**Tipologie di knowledge da centralizzare:**
|
||||||
|
- Cataloghi (colture, malattie, varietà)
|
||||||
|
- Parametri (ET₀, Kc, soglie meteo)
|
||||||
|
- Tabelle (consociazioni, rotazioni)
|
||||||
|
- Regole (conflitti, QA checklist)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Pattern 8: Knowledge → Inline nel Corpo
|
||||||
|
|
||||||
|
**Descrizione:** Knowledge piccola (<500 linee) e specifica di una skill rimane nel corpo SKILL.md.
|
||||||
|
|
||||||
|
**Esempio:**
|
||||||
|
```
|
||||||
|
Input: Agente 02 sezione "Varietà consigliate" (50 righe)
|
||||||
|
Output: Integrato in orto-agronomo SKILL.md (Fase 2: Lista Colture)
|
||||||
|
```
|
||||||
|
|
||||||
|
**Criteri:**
|
||||||
|
- Knowledge usata da 1 sola skill
|
||||||
|
- Knowledge <500 linee e <10 KB
|
||||||
|
- Knowledge è specifica del dominio della skill
|
||||||
|
- Separare aggiungerebbe complessità non necessaria
|
||||||
|
|
||||||
|
**Output:**
|
||||||
|
- Knowledge integrata nel corpo SKILL.md (sezione dedicata)
|
||||||
|
- Nessun reference file creato
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Pattern 9: Script → scripts/ nella Skill
|
||||||
|
|
||||||
|
**Descrizione:** Script riutilizzabile e deterministico viene incluso nella skill.
|
||||||
|
|
||||||
|
**Esempio:**
|
||||||
|
```
|
||||||
|
Input: init_new_orto.py (20 KB, crea struttura directory)
|
||||||
|
Output: orto-init/scripts/init_new_orto.py
|
||||||
|
```
|
||||||
|
|
||||||
|
**Criteri:**
|
||||||
|
- Script è riutilizzabile (eseguito multiple volte)
|
||||||
|
- Script è deterministico (stesso input → stesso output)
|
||||||
|
- Script ha dipendenze minime (Python standard lib OK)
|
||||||
|
- Script è più efficiente che riscriverlo inline
|
||||||
|
|
||||||
|
**Output:**
|
||||||
|
- Script copiato in `<skill-name>/scripts/`
|
||||||
|
- Documentato in SKILL.md (sezione "Scripts")
|
||||||
|
- Eventuale `requirements.txt` se dipendenze esterne
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Pattern 10: Script → Inline nel Corpo
|
||||||
|
|
||||||
|
**Descrizione:** Script semplice o una-tantum viene convertito in logica inline nel corpo SKILL.md.
|
||||||
|
|
||||||
|
**Esempio:**
|
||||||
|
```
|
||||||
|
Input: json_to_md_converter.py (3 KB, utility migrazione)
|
||||||
|
Output: Logica descritta in SKILL.md (nessuno script incluso)
|
||||||
|
```
|
||||||
|
|
||||||
|
**Criteri:**
|
||||||
|
- Script è una-tantum (migrazione, setup iniziale)
|
||||||
|
- Script è semplice (<50 righe)
|
||||||
|
- Logica può essere descritta in markdown
|
||||||
|
- Includere script aggiungerebbe complessità non necessaria
|
||||||
|
|
||||||
|
**Output:**
|
||||||
|
- Logica descritta in corpo SKILL.md (pseudocodice o descrizione)
|
||||||
|
- Nessuno script incluso
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Pattern 11: Script → Eliminato
|
||||||
|
|
||||||
|
**Descrizione:** Script non necessario a runtime viene eliminato.
|
||||||
|
|
||||||
|
**Esempio:**
|
||||||
|
```
|
||||||
|
Input: sync_md_from_agents.py (5 KB, validazione post-hoc)
|
||||||
|
Output: Nessuno script incluso (funzionalità assorbita da QA inline)
|
||||||
|
```
|
||||||
|
|
||||||
|
**Criteri:**
|
||||||
|
- Script è tool di sviluppo/test, non runtime
|
||||||
|
- Funzionalità è già coperta da QA inline
|
||||||
|
- Script richiede configurazione complessa
|
||||||
|
- Eliminare semplifica senza perdere valore
|
||||||
|
|
||||||
|
**Output:**
|
||||||
|
- Script non incluso
|
||||||
|
- Eventuale menzione in `mapping_plan.md` (sezione "Eliminati")
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Pattern 12: Prompt → Integrato come Input Section
|
||||||
|
|
||||||
|
**Descrizione:** Prompt che sono template di input diventano sezioni Input nella skill.
|
||||||
|
|
||||||
|
**Esempio:**
|
||||||
|
```
|
||||||
|
Input: prompts/prompt_onboarding.md (template questionario)
|
||||||
|
Output: orto-onboarding SKILL.md, sezione "Input" con tabella campi
|
||||||
|
```
|
||||||
|
|
||||||
|
**Criteri:**
|
||||||
|
- Prompt è template di raccolta dati
|
||||||
|
- Prompt definisce input strutturati
|
||||||
|
- Prompt può essere convertito in tabella markdown
|
||||||
|
|
||||||
|
**Output:**
|
||||||
|
- Tabella Input in SKILL.md (nome, tipo, obbligatorio, esempio)
|
||||||
|
- Eventuale template markdown in `assets/` se complesso
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Pattern 13: Prompt → Eliminato
|
||||||
|
|
||||||
|
**Descrizione:** Prompt di generazione framework (non runtime) vengono eliminati.
|
||||||
|
|
||||||
|
**Esempio:**
|
||||||
|
```
|
||||||
|
Input: prompts/master_prompt_openclaw.md (generazione specifiche)
|
||||||
|
Output: Nessuna inclusione (prompt di generazione, non runtime)
|
||||||
|
```
|
||||||
|
|
||||||
|
**Criteri:**
|
||||||
|
- Prompt serve a generare framework, non a eseguirlo
|
||||||
|
- Prompt non è necessario per le skills runtime
|
||||||
|
- Eliminare non perde funzionalità runtime
|
||||||
|
|
||||||
|
**Output:**
|
||||||
|
- Prompt non incluso
|
||||||
|
- Eventuale menzione storica in README.md
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Decision Tree per Mappatura
|
||||||
|
|
||||||
|
```
|
||||||
|
Start: Entità framework (agente/workflow/knowledge/script)
|
||||||
|
│
|
||||||
|
├─→ È un Agente?
|
||||||
|
│ ├─→ Ha overlap >50% con altro agente?
|
||||||
|
│ │ ├─→ SÌ → Pattern 2 (Merge 2+ Agenti → 1 Skill)
|
||||||
|
│ │ └─→ NO → È essenziale per MVP?
|
||||||
|
│ │ ├─→ SÌ → Pattern 1 (1 Agente → 1 Skill)
|
||||||
|
│ │ └─→ NO → Pattern 5 (Eliminato) o Pattern 6 (Assorbito)
|
||||||
|
│ │
|
||||||
|
│ └─→ È di coordinamento/orchestrazione?
|
||||||
|
│ ├─→ SÌ → Pattern 4 (Agente + Workflow → Orchestratore)
|
||||||
|
│ └─→ NO → (vedi sopra)
|
||||||
|
│
|
||||||
|
├─→ È un Workflow?
|
||||||
|
│ ├─→ Ha script associato?
|
||||||
|
│ │ ├─→ SÌ → Pattern 3 (Workflow → Skill Operativa)
|
||||||
|
│ │ └─→ NO → È orchestrato da altro agente?
|
||||||
|
│ │ ├─→ SÌ → Pattern 4 (Agente + Workflow → Orchestratore)
|
||||||
|
│ │ └─→ NO → Pattern 3 (Workflow → Skill, no script)
|
||||||
|
│ │
|
||||||
|
│ └─→ (vedi sopra)
|
||||||
|
│
|
||||||
|
├─→ È Knowledge?
|
||||||
|
│ ├─→ È condivisa da 2+ skills o >500 linee?
|
||||||
|
│ │ ├─→ SÌ → Pattern 7 (Knowledge → Reference Centralizzata)
|
||||||
|
│ │ └─→ NO → Pattern 8 (Knowledge → Inline nel Corpo)
|
||||||
|
│ │
|
||||||
|
│ └─→ (vedi sopra)
|
||||||
|
│
|
||||||
|
└─→ È uno Script?
|
||||||
|
├─→ È riutilizzabile e deterministico?
|
||||||
|
│ ├─→ SÌ → Pattern 9 (Script → scripts/ nella Skill)
|
||||||
|
│ └─→ NO → È semplice o una-tantum?
|
||||||
|
│ ├─→ SÌ → Pattern 10 (Script → Inline nel Corpo)
|
||||||
|
│ └─→ NO → Pattern 11 (Script → Eliminato)
|
||||||
|
│
|
||||||
|
└─→ (vedi sopra)
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Esempi da orto_v1 → orto-skills
|
||||||
|
|
||||||
|
| Entità Origine | Pattern Applicato | Output | Giustificazione |
|
||||||
|
|----------------|-------------------|--------|-----------------|
|
||||||
|
| Agente 01 (Orchestratore) | Pattern 4 | orto-orchestratore | Coordina workflow multipli + QA |
|
||||||
|
| Agente 02 (Agronomo) | Pattern 1 | orto-agronomo | Auto-contenuto, responsabilità chiara |
|
||||||
|
| Agente 03 (Stagionalità) | Pattern 1 | orto-calendario | Auto-contenuto |
|
||||||
|
| Agente 04 (Fitopatologo) + PHYTO-DIAG + PHYTO-TREAT-BIO | Pattern 2 | orto-fitopatologo | Merge funzionale (diagnosi + trattamenti) |
|
||||||
|
| Agente 05 (Irrigazione) | Pattern 1 | orto-irrigazione | Auto-contenuto |
|
||||||
|
| Agente 06 (Layout) | Pattern 1 | orto-layout | Auto-contenuto |
|
||||||
|
| Agente 07 (Nutrizione) | Pattern 6 | Assorbito in orto-agronomo | Overlap forte con agronomo |
|
||||||
|
| Agente 08 (Data Manager) | Pattern 6 | Assorbito in orchestratore | QA già in orchestratore |
|
||||||
|
| Agente 09 (UI/UX) | Pattern 5 | Eliminato | Non essenziale per MVP testuale |
|
||||||
|
| Agente 10 (QA) | Pattern 6 | Assorbito in orchestratore | Validazione inline |
|
||||||
|
| Agente 11 (Meteo) | Pattern 1 | orto-meteo-decisioni | Auto-contenuto |
|
||||||
|
| Agente 12 (Ops) | Pattern 5 | Eliminato | Integrazioni gestite da singole skills |
|
||||||
|
| Workflow 00 (Init) + init_new_orto.py | Pattern 3 | orto-init | Workflow operativo con script |
|
||||||
|
| Workflow 01 (Onboarding) | Pattern 3 | orto-onboarding | Workflow di raccolta dati |
|
||||||
|
| colture.md (knowledge) | Pattern 7 | references/colture_it.md | Condivisa, 20 KB |
|
||||||
|
| init_new_orto.py | Pattern 9 | orto-init/scripts/ | Riutilizzabile, deterministico |
|
||||||
|
| json_to_md_converter.py | Pattern 11 | Eliminato | Utility migrazione, non runtime |
|
||||||
|
| prompt_onboarding.md | Pattern 12 | orto-onboarding Input section | Template di raccolta dati |
|
||||||
|
| master_prompt_openclaw.md | Pattern 13 | Eliminato | Prompt di generazione, non runtime |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Checklist Applicazione Pattern
|
||||||
|
|
||||||
|
Prima di finalizzare la mappatura, verifica:
|
||||||
|
|
||||||
|
- [ ] Ogni agente ha un pattern applicato (1, 2, 4, 5, o 6)
|
||||||
|
- [ ] Ogni workflow ha un pattern applicato (3 o 4)
|
||||||
|
- [ ] Ogni knowledge ha un pattern applicato (7 o 8)
|
||||||
|
- [ ] Ogni script ha un pattern applicato (9, 10, o 11)
|
||||||
|
- [ ] Ogni prompt ha un pattern applicato (12 o 13)
|
||||||
|
- [ ] Pattern applicati sono coerenti con criteri
|
||||||
|
- [ ] Giustificazioni documentate per Pattern 2, 5, 6
|
||||||
|
- [ ] Decision tree seguito in ordine logico
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
_Aggiornato: 2026-03-07 | Versione: 1.0_
|
||||||
564
references/skill_template.md
Normal file
564
references/skill_template.md
Normal file
|
|
@ -0,0 +1,564 @@
|
||||||
|
# Skill Template — Template Standardizzato per SKILL.md
|
||||||
|
|
||||||
|
_Template per generare SKILL.md coerenti e AgentSkills-compatibili._
|
||||||
|
|
||||||
|
_Usato da: framework-translator (Fase 4)_
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Panoramica
|
||||||
|
|
||||||
|
Questo template definisce la struttura standard per ogni SKILL.md generato da `framework-translator`.
|
||||||
|
|
||||||
|
**Obiettivo:** Coerenza tra tutte le skills, indipendentemente dal framework di origine.
|
||||||
|
|
||||||
|
**Lunghezza target:** <500 linee (esclusi references). Se più lungo, estrai conoscenza in references.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Struttura Template
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
---
|
||||||
|
name: <skill-name>
|
||||||
|
description: <descrizione concisa con trigger e output>
|
||||||
|
---
|
||||||
|
|
||||||
|
# <Skill Name> — <Sottotitolo Descrittivo>
|
||||||
|
|
||||||
|
[Breve introduzione: cosa fa la skill, 2-3 frasi. Contesto e scopo.]
|
||||||
|
|
||||||
|
## Quando Usare Questa Skill
|
||||||
|
|
||||||
|
- **Scenario 1:** [Descrizione trigger specifica, quando l'utente dovrebbe attivare questa skill]
|
||||||
|
- **Scenario 2:** [Descrizione trigger specifica]
|
||||||
|
- **Scenario 3:** [Descrizione trigger specifica]
|
||||||
|
- **Scenario 4:** [Opzionale, se necessario]
|
||||||
|
- **Scenario 5:** [Opzionale, se necessario]
|
||||||
|
|
||||||
|
## Input
|
||||||
|
|
||||||
|
[Tabella input richiesti dalla skill]
|
||||||
|
|
||||||
|
| Input | Tipo | Obbligatorio | Esempio | Note |
|
||||||
|
|-------|------|--------------|---------|------|
|
||||||
|
| `<input_name>` | String/Int/Float/Enum/Bool | Sì/No | `example_value` | [Vincoli, validazione, default] |
|
||||||
|
| ... | ... | ... | ... | ... |
|
||||||
|
|
||||||
|
### Validazione Input
|
||||||
|
|
||||||
|
[Regole di validazione per gli input, se applicabile]
|
||||||
|
|
||||||
|
```
|
||||||
|
<input_name>:
|
||||||
|
- Regola 1 (es. "lowercase, solo underscore, max 64 caratteri")
|
||||||
|
- Regola 2 (es. "range: -90 a 90")
|
||||||
|
- Regola 3 (es. "deve esistere come file/percorso")
|
||||||
|
```
|
||||||
|
|
||||||
|
## Processo
|
||||||
|
|
||||||
|
### Fase 1: <Nome Fase Descrittivo>
|
||||||
|
|
||||||
|
[Descrizione dettagliata della fase]
|
||||||
|
|
||||||
|
**Obiettivo:** [Cosa si ottiene alla fine di questa fase]
|
||||||
|
|
||||||
|
**Azioni:**
|
||||||
|
|
||||||
|
1. [Step operativo 1, azione concreta]
|
||||||
|
2. [Step operativo 2]
|
||||||
|
3. [Step operativo 3]
|
||||||
|
|
||||||
|
**Regole decisionali:**
|
||||||
|
|
||||||
|
```
|
||||||
|
se <condizione>:
|
||||||
|
→ <azione>
|
||||||
|
altrimenti se <condizione>:
|
||||||
|
→ <azione>
|
||||||
|
altrimenti:
|
||||||
|
→ <azione>
|
||||||
|
```
|
||||||
|
|
||||||
|
**Output intermedio:** [Cosa produce questa fase, se applicabile]
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Fase 2: <Nome Fase Descrittivo>
|
||||||
|
|
||||||
|
[Struttura identica a Fase 1]
|
||||||
|
|
||||||
|
**Obiettivo:** ...
|
||||||
|
|
||||||
|
**Azioni:**
|
||||||
|
|
||||||
|
1. ...
|
||||||
|
|
||||||
|
**Regole decisionali:**
|
||||||
|
|
||||||
|
```
|
||||||
|
...
|
||||||
|
```
|
||||||
|
|
||||||
|
**Output intermedio:** ...
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
[Aggiungi fasi secondo necessità: Fase 3, Fase 4, ...]
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Output
|
||||||
|
|
||||||
|
[Descrizione dell'output finale della skill]
|
||||||
|
|
||||||
|
**File generato:** `<percorso/del/file.md>`
|
||||||
|
|
||||||
|
**Formato:** Markdown strutturato (o altro formato se specificato)
|
||||||
|
|
||||||
|
**Struttura:**
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
# <Titolo Output>
|
||||||
|
|
||||||
|
_<metadata: ID, data, agente responsabile>_
|
||||||
|
|
||||||
|
## Sezione 1
|
||||||
|
|
||||||
|
[Contenuto]
|
||||||
|
|
||||||
|
## Sezione 2
|
||||||
|
|
||||||
|
...
|
||||||
|
```
|
||||||
|
|
||||||
|
### Esempio Output
|
||||||
|
|
||||||
|
[Esempio concreto di output, se utile per chiarezza]
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
# Esempio Concreto
|
||||||
|
|
||||||
|
_Orto: Example ID | Generato: 2026-03-07_
|
||||||
|
|
||||||
|
## Dettaglio 1
|
||||||
|
|
||||||
|
- Item 1
|
||||||
|
- Item 2
|
||||||
|
|
||||||
|
## Dettaglio 2
|
||||||
|
|
||||||
|
| Colonna 1 | Colonna 2 |
|
||||||
|
|-----------|-----------|
|
||||||
|
| Valore 1 | Valore 2 |
|
||||||
|
```
|
||||||
|
|
||||||
|
## References
|
||||||
|
|
||||||
|
[Elenco references usate dalla skill, con link e breve descrizione]
|
||||||
|
|
||||||
|
- [`<reference-name>.md`](../references/<reference-name>.md) — [Breve descrizione contenuto]
|
||||||
|
- [`<reference-name-2>.md`](../references/<reference-name-2>.md) — [Breve descrizione contenuto]
|
||||||
|
- ...
|
||||||
|
|
||||||
|
**Nota:** I references sono symlink a `../references/` nella struttura della suite.
|
||||||
|
|
||||||
|
## Scripts
|
||||||
|
|
||||||
|
[Sezione opzionale, solo se la skill include scripts]
|
||||||
|
|
||||||
|
### `<script-name>.py`
|
||||||
|
|
||||||
|
[Descrizione dello script, quando viene eseguito, parametri]
|
||||||
|
|
||||||
|
**Utilizzo:**
|
||||||
|
|
||||||
|
```bash
|
||||||
|
python3 scripts/<script-name>.py --arg1 value1 --arg2 value2
|
||||||
|
```
|
||||||
|
|
||||||
|
**Dipendenze:**
|
||||||
|
|
||||||
|
- Python 3.x
|
||||||
|
- Libreria X (`pip install X`)
|
||||||
|
- ...
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Note
|
||||||
|
|
||||||
|
[Eventuali note aggiuntive, avvertenze, edge cases, limitazioni]
|
||||||
|
|
||||||
|
**Edge cases gestiti:**
|
||||||
|
|
||||||
|
- [Edge case 1]: [Come è gestito]
|
||||||
|
- [Edge case 2]: [Come è gestito]
|
||||||
|
|
||||||
|
**Limitazioni:**
|
||||||
|
|
||||||
|
- [Limitazione 1, se applicabile]
|
||||||
|
- [Limitazione 2, se applicabile]
|
||||||
|
|
||||||
|
**Avvertenze:**
|
||||||
|
|
||||||
|
- ⚠️ [Avvertenza importante, se applicabile]
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
_Aggiornato: YYYY-MM-DD | Versione: 1.0_
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Linee Guida per Compilazione
|
||||||
|
|
||||||
|
### Frontmatter YAML
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
---
|
||||||
|
name: <skill-name>
|
||||||
|
description: <descrizione>
|
||||||
|
---
|
||||||
|
```
|
||||||
|
|
||||||
|
**Regole:**
|
||||||
|
|
||||||
|
- `name`: lowercase kebab-case, max 64 caratteri (es. `orto-agronomo`, `framework-init`)
|
||||||
|
- `description`:
|
||||||
|
- Inizia con verbo all'infinito (Trasformare, Generare, Analizzare, Selezionare, etc.)
|
||||||
|
- Include 3-5 scenari trigger con "(1) ..., (2) ..., (3) ..."
|
||||||
|
- Specifica output finale
|
||||||
|
- Max 300 parole, preferibilmente <200
|
||||||
|
- **Non** includere "When to Use" nel corpo se già in description
|
||||||
|
|
||||||
|
**Esempio description:**
|
||||||
|
|
||||||
|
```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 e bilancio nutrizionale, (2) applicare regole consociazione e rotazione colture, (3) stimare rese e pianificare tempi successioni, (4) considerare clima regionale e finestre stagionali. Output: Piano colture annuale (markdown) con varietà, date semina, spaziature, classe acqua, consociazioni, rese attese.
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Titolo e Sottotitolo
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
# <Skill Name> — <Sottotitolo Descrittivo>
|
||||||
|
```
|
||||||
|
|
||||||
|
**Regole:**
|
||||||
|
|
||||||
|
- `<Skill Name>`: Nome leggibile (maiuscole, spazi) — es. "Orto Agronomo"
|
||||||
|
- `<Sottotitolo>`: Descrizione breve in 3-5 parole — es. "Selezione e Pianificazione Colture"
|
||||||
|
- Usa em-dash (`—`) come separatore, non hyphen (`-`)
|
||||||
|
|
||||||
|
**Esempi:**
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
# Orto Agronomo — Selezione e Pianificazione Colture
|
||||||
|
# Orto Init — Inizializzazione Progetto Orto
|
||||||
|
# Orto Orchestratore — Orchestrazione Workflow Master
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Introduzione
|
||||||
|
|
||||||
|
**Regole:**
|
||||||
|
|
||||||
|
- 2-3 frasi max
|
||||||
|
- Descrivi cosa fa la skill (non quando, già in "Quando Usare")
|
||||||
|
- Includi contesto se utile (es. "Questo è il primo passo nel workflow Orto")
|
||||||
|
|
||||||
|
**Esempio:**
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
Selezionare colture e generare piano colture annuale basato su preferenze comunitarie, clima, spazio e best practice agronomiche. Questo è il secondo passo nel workflow Orto, dopo onboarding.
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Sezione "Quando Usare Questa Skill"
|
||||||
|
|
||||||
|
**Regole:**
|
||||||
|
|
||||||
|
- 3-5 scenari trigger
|
||||||
|
- Ogni scenario inizia con **grassetto** (es. `**Dopo onboarding:**`)
|
||||||
|
- Descrizione specifica, non generica
|
||||||
|
- Evita ripetizioni della description (frontmatter)
|
||||||
|
|
||||||
|
**Esempio:**
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
## Quando Usare Questa Skill
|
||||||
|
|
||||||
|
- **Dopo onboarding:** Profilo utente (GardenConfig + CommunityProfile) è completo
|
||||||
|
- **Selezione colture:** Scegliere verdure corrispondenti a dieta, spazio, livello esperienza
|
||||||
|
- **Pianificazione stagionale:** Mappare colture a finestre di semina (date gelate, requisiti temperatura)
|
||||||
|
- **Pianificazione rotazione:** Assicurare rotazione famiglia negli anni per prevenire accumulo parassiti/malattie
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Sezione "Input"
|
||||||
|
|
||||||
|
**Regole:**
|
||||||
|
|
||||||
|
- Tabella con 5 colonne: Input, Tipo, Obbligatorio, Esempio, Note
|
||||||
|
- `Input`: nome variabile (backtick, snake_case)
|
||||||
|
- `Tipo`: String, Int, Float, Enum, Bool, Array, Object
|
||||||
|
- `Obbligatorio`: Sì/No (se No, specifica default in Note)
|
||||||
|
- `Esempio`: valore concreto (backtick)
|
||||||
|
- `Note`: vincoli, validazione, default
|
||||||
|
|
||||||
|
**Esempio:**
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
| Input | Tipo | Obbligatorio | Esempio | Note |
|
||||||
|
|-------|------|--------------|---------|------|
|
||||||
|
| `orto_id` | String | Sì | `orto_roma_testaccio_001` | lowercase, underscore, max 64 caratteri |
|
||||||
|
| `area_mq` | Float | No | `50` | Default: raccolto in onboarding |
|
||||||
|
| `climate_zone` | Enum | No | `centro` | Inferito da lat/lon se non fornito |
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Sezione "Validazione Input"
|
||||||
|
|
||||||
|
**Regole:**
|
||||||
|
|
||||||
|
- Solo se ci sono regole di validazione non ovvie
|
||||||
|
- Usa pseudocodice o liste puntate
|
||||||
|
- Includi range, formati, vincoli
|
||||||
|
|
||||||
|
**Esempio:**
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
### Validazione Input
|
||||||
|
|
||||||
|
- `orto_id`: lowercase, solo underscore/trattini, max 64 caratteri (es. `orto_NOME_NUMERO`)
|
||||||
|
- `latitude`: -90 a 90, decimale
|
||||||
|
- `longitude`: -180 a 180, decimale
|
||||||
|
- `area_mq`: float positivo se fornito
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Sezione "Processo"
|
||||||
|
|
||||||
|
**Regole:**
|
||||||
|
|
||||||
|
- Fasi numerate (Fase 1, Fase 2, ...)
|
||||||
|
- Ogni fase ha nome descrittivo (es. "Fase 1: Filtra Colture per Vincoli")
|
||||||
|
- Struttura ogni fase con:
|
||||||
|
- **Obiettivo:** Cosa si ottiene
|
||||||
|
- **Azioni:** Step operativi (lista numerata)
|
||||||
|
- **Regole decisionali:** Pseudocodice per logica condizionale
|
||||||
|
- **Output intermedio:** Cosa produce (opzionale)
|
||||||
|
|
||||||
|
**Pseudocodice stile:**
|
||||||
|
|
||||||
|
```
|
||||||
|
se <condizione>:
|
||||||
|
→ <azione>
|
||||||
|
altrimenti se <condizione>:
|
||||||
|
→ <azione>
|
||||||
|
altrimenti:
|
||||||
|
→ <azione>
|
||||||
|
```
|
||||||
|
|
||||||
|
**Esempio:**
|
||||||
|
|
||||||
|
```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 (vedi sotto)
|
||||||
|
|
||||||
|
**Regole decisionali:**
|
||||||
|
|
||||||
|
```
|
||||||
|
se zona == "nord":
|
||||||
|
→ Filtra colture per date gelate nord
|
||||||
|
→ Finestra semina: aprile-maggio
|
||||||
|
altrimenti se zona == "centro":
|
||||||
|
→ Filtra colture per date gelate centro
|
||||||
|
→ Finestra semina: marzo-aprile
|
||||||
|
altrimenti:
|
||||||
|
→ Filtra colture per date gelate sud
|
||||||
|
→ Finestra semina: febbraio-marzo
|
||||||
|
```
|
||||||
|
|
||||||
|
**Output intermedio:** Lista colture pre-filtrate per zona climatica
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Sezione "Output"
|
||||||
|
|
||||||
|
**Regole:**
|
||||||
|
|
||||||
|
- Descrivi file/documento generato
|
||||||
|
- Specifica percorso relativo (es. `dati/colture/piano_colture_annuale.md`)
|
||||||
|
- Descrivi formato (markdown, JSON, etc.)
|
||||||
|
- Includi struttura con esempio di template
|
||||||
|
|
||||||
|
**Esempio:**
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
## Output
|
||||||
|
|
||||||
|
**File generato:** `dati/colture/piano_colture_annuale.md`
|
||||||
|
|
||||||
|
**Formato:** Markdown strutturato
|
||||||
|
|
||||||
|
**Struttura:**
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
# Piano Colture Annuale — [ORTO_ID]
|
||||||
|
|
||||||
|
**Zona Climatica:** [ZONE]
|
||||||
|
**Area disponibile:** [AREA] m²
|
||||||
|
**Comunità:** [DIET] | [N_PERSONE] pp
|
||||||
|
**Esperienza:** [LEVEL]
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Riepilogo Stagionale
|
||||||
|
|
||||||
|
### Primavera (Mar-Mag)
|
||||||
|
- [Coltura 1] ([date])
|
||||||
|
- [Coltura 2] ([date])
|
||||||
|
|
||||||
|
...
|
||||||
|
```
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Sezione "References"
|
||||||
|
|
||||||
|
**Regole:**
|
||||||
|
|
||||||
|
- Elenca tutti i references usati dalla skill
|
||||||
|
- Usa link relativi: `../references/<nome>.md`
|
||||||
|
- Includi breve descrizione (1 frase) per ogni reference
|
||||||
|
|
||||||
|
**Esempio:**
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
## References
|
||||||
|
|
||||||
|
- [`colture_it.md`](../references/colture_it.md) — Catalogo colture italiane, varietà, requisiti
|
||||||
|
- [`calendario_it.md`](../references/calendario_it.md) — Date semina/trapianto/raccolta per zona
|
||||||
|
- [`consociazioni_layout.md`](../references/consociazioni_layout.md) — Matrice consociazioni, spacing aiuole
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Sezione "Scripts" (Opzionale)
|
||||||
|
|
||||||
|
**Regole:**
|
||||||
|
|
||||||
|
- Solo se la skill include scripts in `scripts/`
|
||||||
|
- Descrivi ogni script: scopo, quando eseguito, parametri
|
||||||
|
- Includi esempio di utilizzo
|
||||||
|
- Lista dipendenze esterne
|
||||||
|
|
||||||
|
**Esempio:**
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
## Scripts
|
||||||
|
|
||||||
|
### `init_new_orto.py`
|
||||||
|
|
||||||
|
Script di inizializzazione progetto orto. Eseguito automaticamente quando la skill crea un nuovo orto.
|
||||||
|
|
||||||
|
**Utilizzo:**
|
||||||
|
|
||||||
|
```bash
|
||||||
|
python3 scripts/init_new_orto.py \
|
||||||
|
--id orto_roma_testaccio_001 \
|
||||||
|
--nome "Orto Testaccio Roma" \
|
||||||
|
--provincia Roma \
|
||||||
|
--regione Lazio \
|
||||||
|
--lat 41.8782 \
|
||||||
|
--lon 12.4922
|
||||||
|
```
|
||||||
|
|
||||||
|
**Dipendenze:**
|
||||||
|
|
||||||
|
- Python 3.8+
|
||||||
|
- Nessuna libreria esterna (standard lib)
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Sezione "Note"
|
||||||
|
|
||||||
|
**Regole:**
|
||||||
|
|
||||||
|
- Opzionale, usa solo se necessario
|
||||||
|
- Includi: edge cases gestiti, limitazioni, avvertenze
|
||||||
|
- Usa formattazione chiara (liste, grassetto)
|
||||||
|
|
||||||
|
**Esempio:**
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
## Note
|
||||||
|
|
||||||
|
**Edge cases gestiti:**
|
||||||
|
|
||||||
|
- **Area troppo piccola:** Se area <10m², skill suggerisce colture compatte e successioni rapide
|
||||||
|
- **Acqua limitata:** Se acqua <100mm/mese, skill priorizza colture tolleranti siccità
|
||||||
|
|
||||||
|
**Limitazioni:**
|
||||||
|
|
||||||
|
- Non gestisce orti indoor/idroponici (solo suolo aperto)
|
||||||
|
- Presupposto: utente ha accesso base a strumenti da giardino
|
||||||
|
|
||||||
|
**Avvertenze:**
|
||||||
|
|
||||||
|
- ⚠️ **Date gelate:** Sono stime macro-zona; verifica microclima locale prima di trapianti critici
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Checklist di Qualità
|
||||||
|
|
||||||
|
Prima di finalizzare una skill, verifica:
|
||||||
|
|
||||||
|
- [ ] **Frontmatter YAML valido** (name + description presenti e corretti)
|
||||||
|
- [ ] **Description trigger-specifica** (include "Usare quando:" con 3+ scenari)
|
||||||
|
- [ ] **Corpo <500 linee** (o references usati appropriatamente)
|
||||||
|
- [ ] **Titolo + sottotitolo** presenti e coerenti
|
||||||
|
- [ ] **"Quando Usare"** con 3-5 scenari trigger specifici
|
||||||
|
- [ ] **Input tabella** completa (nome, tipo, obbligatorio, esempio, note)
|
||||||
|
- [ ] **Validazione Input** se applicabile
|
||||||
|
- [ ] **Fasi numerate** con nomi descrittivi
|
||||||
|
- [ ] **Ogni fase ha:** Obiettivo, Azioni, Regole decisionali (se applicabile)
|
||||||
|
- [ ] **Output documentato** (file, formato, struttura, esempio)
|
||||||
|
- [ ] **References linkati** (percorsi corretti, descrizioni)
|
||||||
|
- [ ] **Scripts documentati** (se presenti)
|
||||||
|
- [ ] **Note** per edge cases/limitazioni/avvertenze (se applicabile)
|
||||||
|
- [ ] **Niente JSON per dati** (solo markdown, tranne registry)
|
||||||
|
- [ ] **Niente sezioni ridondanti** (no "When to Use" nel corpo se già in description)
|
||||||
|
- [ ] **Lingua coerente** (stessa lingua del framework input)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Esempi Reali
|
||||||
|
|
||||||
|
Per esempi di SKILL.md compilati correttamente, vedi:
|
||||||
|
|
||||||
|
- `orto-skills/orto-suite/orto-init/SKILL.md`
|
||||||
|
- `orto-skills/orto-suite/orto-agronomo/SKILL.md`
|
||||||
|
- `orto-skills/orto-suite/orto-orchestratore/SKILL.md`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
_Aggiornato: 2026-03-07 | Versione: 1.0_
|
||||||
54
scripts/01_scan_files.sh
Executable file
54
scripts/01_scan_files.sh
Executable file
|
|
@ -0,0 +1,54 @@
|
||||||
|
#!/bin/bash
|
||||||
|
# 01_scan_files.sh — Scansione file framework
|
||||||
|
# Solo meccanico: lista file markdown e struttura directory
|
||||||
|
|
||||||
|
set -e
|
||||||
|
|
||||||
|
FRAMEWORK_PATH="$1"
|
||||||
|
|
||||||
|
if [ -z "$FRAMEWORK_PATH" ]; then
|
||||||
|
echo "❌ Usage: $0 <framework-path>"
|
||||||
|
exit 1
|
||||||
|
fi
|
||||||
|
|
||||||
|
if [ ! -d "$FRAMEWORK_PATH" ]; then
|
||||||
|
echo "❌ Error: Directory not found: $FRAMEWORK_PATH"
|
||||||
|
exit 1
|
||||||
|
fi
|
||||||
|
|
||||||
|
echo "📂 Scansione framework: $FRAMEWORK_PATH"
|
||||||
|
echo "=============================================="
|
||||||
|
|
||||||
|
# Struttura directory
|
||||||
|
echo ""
|
||||||
|
echo "### STRUTTURA DIRECTORY"
|
||||||
|
echo ""
|
||||||
|
find "$FRAMEWORK_PATH" -type d | grep -v "/\." | sort | head -50
|
||||||
|
|
||||||
|
# File markdown
|
||||||
|
echo ""
|
||||||
|
echo "### FILE MARKDOWN ($(find "$FRAMEWORK_PATH" -name "*.md" | wc -l | tr -d ' ') totali)"
|
||||||
|
echo ""
|
||||||
|
find "$FRAMEWORK_PATH" -type f -name "*.md" | grep -v "/\." | sort
|
||||||
|
|
||||||
|
# Script
|
||||||
|
echo ""
|
||||||
|
echo "### SCRIPT ($(find "$FRAMEWORK_PATH" -type f \( -name "*.py" -o -name "*.sh" \) | wc -l | tr -d ' ') totali)"
|
||||||
|
echo ""
|
||||||
|
find "$FRAMEWORK_PATH" -type f \( -name "*.py" -o -name "*.sh" \) | grep -v "/\." | sort
|
||||||
|
|
||||||
|
# Cartelle chiave
|
||||||
|
echo ""
|
||||||
|
echo "### CARTELLE CHIAVE IDENTIFICATE"
|
||||||
|
echo ""
|
||||||
|
|
||||||
|
for pattern in agents agenti actors roles workflows flussi processes knowledge docs scripts tools prompts; do
|
||||||
|
found=$(find "$FRAMEWORK_PATH" -type d -iname "*$pattern*" | grep -v "/\." | head -3)
|
||||||
|
if [ -n "$found" ]; then
|
||||||
|
echo "✓ $pattern: $found"
|
||||||
|
fi
|
||||||
|
done
|
||||||
|
|
||||||
|
echo ""
|
||||||
|
echo "=============================================="
|
||||||
|
echo "✅ Scansione completata"
|
||||||
69
scripts/02_create_structure.sh
Executable file
69
scripts/02_create_structure.sh
Executable file
|
|
@ -0,0 +1,69 @@
|
||||||
|
#!/bin/bash
|
||||||
|
# 02_create_structure.sh — Crea struttura distribuzione
|
||||||
|
# Solo meccanico: mkdir, mv, organizzazione file
|
||||||
|
|
||||||
|
set -e
|
||||||
|
|
||||||
|
FRAMEWORK_NAME="$1"
|
||||||
|
SOURCE_DIR="$2"
|
||||||
|
|
||||||
|
if [ -z "$FRAMEWORK_NAME" ] || [ -z "$SOURCE_DIR" ]; then
|
||||||
|
echo "❌ Usage: $0 <framework-name> <source-dir>"
|
||||||
|
echo " framework-name: nome per la suite (es. orto-skills)"
|
||||||
|
echo " source-dir: directory con skills e references generate"
|
||||||
|
exit 1
|
||||||
|
fi
|
||||||
|
|
||||||
|
if [ ! -d "$SOURCE_DIR" ]; then
|
||||||
|
echo "❌ Error: Directory not found: $SOURCE_DIR"
|
||||||
|
exit 1
|
||||||
|
fi
|
||||||
|
|
||||||
|
DIST_DIR="${FRAMEWORK_NAME}-suite"
|
||||||
|
|
||||||
|
echo "📦 Creazione struttura distribuzione: $DIST_DIR"
|
||||||
|
echo "=============================================="
|
||||||
|
|
||||||
|
# Crea directory distribuzione
|
||||||
|
mkdir -p "$DIST_DIR"
|
||||||
|
|
||||||
|
# Sposta/maintieni skills
|
||||||
|
echo ""
|
||||||
|
echo "### Spostamento skills..."
|
||||||
|
for skill_dir in "$SOURCE_DIR"/*/; do
|
||||||
|
if [ -d "$skill_dir" ]; then
|
||||||
|
skill_name=$(basename "$skill_dir")
|
||||||
|
if [ "$skill_name" != "references" ]; then
|
||||||
|
mv "$skill_dir" "$DIST_DIR/"
|
||||||
|
echo " ✓ Skill: $skill_name"
|
||||||
|
fi
|
||||||
|
fi
|
||||||
|
done
|
||||||
|
|
||||||
|
# Sposta/maintieni references
|
||||||
|
echo ""
|
||||||
|
echo "### Spostamento references..."
|
||||||
|
if [ -d "$SOURCE_DIR/references" ]; then
|
||||||
|
mv "$SOURCE_DIR/references" "$DIST_DIR/"
|
||||||
|
echo " ✓ References directory"
|
||||||
|
fi
|
||||||
|
|
||||||
|
# Crea symlink in ogni skill
|
||||||
|
echo ""
|
||||||
|
echo "### Creazione symlink references..."
|
||||||
|
for skill_dir in "$DIST_DIR"/*/; do
|
||||||
|
if [ -d "$skill_dir" ] && [ "$(basename "$skill_dir")" != "references" ]; then
|
||||||
|
ln -sf ../references "$skill_dir/references" 2>/dev/null || {
|
||||||
|
echo " ⚠️ Symlink fallito per $(basename "$skill_dir")"
|
||||||
|
continue
|
||||||
|
}
|
||||||
|
echo " ✓ Symlink: $(basename "$skill_dir")/references → ../references"
|
||||||
|
fi
|
||||||
|
done
|
||||||
|
|
||||||
|
echo ""
|
||||||
|
echo "=============================================="
|
||||||
|
echo "✅ Struttura creata: $DIST_DIR"
|
||||||
|
echo ""
|
||||||
|
echo "Contenuto:"
|
||||||
|
ls -la "$DIST_DIR"
|
||||||
140
scripts/03_generate_packaging.sh
Executable file
140
scripts/03_generate_packaging.sh
Executable file
|
|
@ -0,0 +1,140 @@
|
||||||
|
#!/bin/bash
|
||||||
|
# 03_generate_packaging.sh — Genera INSTALL.sh e README.md
|
||||||
|
# Solo meccanico: generazione file packaging
|
||||||
|
|
||||||
|
set -e
|
||||||
|
|
||||||
|
DIST_DIR="$1"
|
||||||
|
FRAMEWORK_NAME="$(basename "$DIST_DIR" | sed 's/-suite$//')"
|
||||||
|
|
||||||
|
if [ -z "$DIST_DIR" ] || [ ! -d "$DIST_DIR" ]; then
|
||||||
|
echo "❌ Usage: $0 <dist-dir>"
|
||||||
|
exit 1
|
||||||
|
fi
|
||||||
|
|
||||||
|
echo "📦 Generazione packaging per: $DIST_DIR"
|
||||||
|
echo "=============================================="
|
||||||
|
|
||||||
|
# Conta skills e references
|
||||||
|
SKILLS_COUNT=$(find "$DIST_DIR" -mindepth 1 -maxdepth 1 -type d ! -name "references" 2>/dev/null | wc -l | tr -d ' ')
|
||||||
|
REFS_COUNT=$(find "$DIST_DIR/references" -name "*.md" 2>/dev/null | wc -l | tr -d ' ')
|
||||||
|
|
||||||
|
# Genera INSTALL.sh
|
||||||
|
echo ""
|
||||||
|
echo "### Generazione INSTALL.sh..."
|
||||||
|
|
||||||
|
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..."
|
||||||
|
echo ""
|
||||||
|
|
||||||
|
# Verifica destinazione
|
||||||
|
if [ -d "\$TARGET" ]; then
|
||||||
|
echo "⚠️ Directory esistente: \$TARGET"
|
||||||
|
read -p "Sovrascrivere? (y/N) " confirm
|
||||||
|
if [ "\$confirm" != "y" ]; then
|
||||||
|
echo "❌ Installazione annullata"
|
||||||
|
exit 1
|
||||||
|
fi
|
||||||
|
rm -rf "\$TARGET"
|
||||||
|
fi
|
||||||
|
|
||||||
|
# Crea directory parent
|
||||||
|
mkdir -p "\$(dirname "\$TARGET")"
|
||||||
|
|
||||||
|
# Copia skills
|
||||||
|
cp -r "\$SOURCE" "\$TARGET"
|
||||||
|
|
||||||
|
echo "✅ Installation complete!"
|
||||||
|
echo ""
|
||||||
|
echo "Skills installate in: \$TARGET"
|
||||||
|
echo ""
|
||||||
|
echo "Skills incluse (${SKILLS_COUNT}):"
|
||||||
|
for skill in "\$TARGET"/*/; do
|
||||||
|
if [ -d "\$skill" ] && [ "\$(basename "\$skill")" != "references" ]; then
|
||||||
|
echo " - \$(basename "\$skill")"
|
||||||
|
fi
|
||||||
|
done
|
||||||
|
EOF
|
||||||
|
|
||||||
|
chmod +x "$DIST_DIR/INSTALL.sh"
|
||||||
|
echo " ✓ INSTALL.sh generato"
|
||||||
|
|
||||||
|
# Genera README.md
|
||||||
|
echo ""
|
||||||
|
echo "### Generazione README.md..."
|
||||||
|
|
||||||
|
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" ] && [ "$(basename "$skill_dir")" != "references" ]; then
|
||||||
|
skill_name=$(basename "$skill_dir")
|
||||||
|
echo "- **$skill_name**" >> "$DIST_DIR/README.md"
|
||||||
|
fi
|
||||||
|
done
|
||||||
|
|
||||||
|
cat >> "$DIST_DIR/README.md" << EOF
|
||||||
|
|
||||||
|
## References
|
||||||
|
|
||||||
|
EOF
|
||||||
|
|
||||||
|
# Lista references
|
||||||
|
if [ -d "$DIST_DIR/references" ]; then
|
||||||
|
for ref_file in "$DIST_DIR/references"/*.md; do
|
||||||
|
if [ -f "$ref_file" ]; then
|
||||||
|
ref_name=$(basename "$ref_file")
|
||||||
|
echo "- \`$ref_name\`" >> "$DIST_DIR/README.md"
|
||||||
|
fi
|
||||||
|
done
|
||||||
|
fi
|
||||||
|
|
||||||
|
cat >> "$DIST_DIR/README.md" << EOF
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
_Generato da framework-translator il $(date +%Y-%m-%d)_
|
||||||
|
EOF
|
||||||
|
|
||||||
|
echo " ✓ README.md generato"
|
||||||
|
|
||||||
|
echo ""
|
||||||
|
echo "=============================================="
|
||||||
|
echo "✅ Packaging completato"
|
||||||
|
echo ""
|
||||||
|
echo "File generati:"
|
||||||
|
ls -la "$DIST_DIR"/*.sh "$DIST_DIR"/*.md 2>/dev/null || true
|
||||||
229
scripts/README.md
Normal file
229
scripts/README.md
Normal file
|
|
@ -0,0 +1,229 @@
|
||||||
|
# Scripts — Framework Translator (LLM-Native)
|
||||||
|
|
||||||
|
Script **meccanici** per supporto operativo al processo LLM.
|
||||||
|
|
||||||
|
## Panoramica
|
||||||
|
|
||||||
|
Questi script **NON fanno analisi semantica** — solo operazioni meccaniche:
|
||||||
|
- Listare file
|
||||||
|
- Creare directory
|
||||||
|
- Creare symlink
|
||||||
|
- Generare file template (INSTALL.sh, README.md)
|
||||||
|
|
||||||
|
**Tutta l'analisi e generazione è fatta da LLM** leggendo `SKILL.md`.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Script Disponibili
|
||||||
|
|
||||||
|
### `01_scan_files.sh` — Scansione Framework
|
||||||
|
|
||||||
|
**Scopo:** Lista file markdown e struttura directory del framework.
|
||||||
|
|
||||||
|
**Input:**
|
||||||
|
- Percorso framework
|
||||||
|
|
||||||
|
**Output:**
|
||||||
|
- Lista directory
|
||||||
|
- Lista file markdown
|
||||||
|
- Lista script
|
||||||
|
- Cartelle chiave identificate
|
||||||
|
|
||||||
|
**Utilizzo:**
|
||||||
|
```bash
|
||||||
|
./scripts/01_scan_files.sh /path/to/framework
|
||||||
|
```
|
||||||
|
|
||||||
|
**Output esempio:**
|
||||||
|
```
|
||||||
|
📂 Scansione framework: /path/to/orto_v1
|
||||||
|
==============================================
|
||||||
|
|
||||||
|
### STRUTTURA DIRECTORY
|
||||||
|
|
||||||
|
/path/to/orto_v1
|
||||||
|
/path/to/orto_v1/docs
|
||||||
|
/path/to/orto_v1/docs/agents
|
||||||
|
/path/to/orto_v1/docs/workflows
|
||||||
|
...
|
||||||
|
|
||||||
|
### FILE MARKDOWN (47 totali)
|
||||||
|
|
||||||
|
/path/to/orto_v1/README.md
|
||||||
|
/path/to/orto_v1/docs/agents/00_agent_index.md
|
||||||
|
/path/to/orto_v1/docs/agents/01_orchestratore.md
|
||||||
|
...
|
||||||
|
|
||||||
|
### CARTELLE CHIAVE IDENTIFICATE
|
||||||
|
|
||||||
|
✓ agents: /path/to/orto_v1/docs/agents
|
||||||
|
✓ workflows: /path/to/orto_v1/docs/workflows
|
||||||
|
✓ knowledge: /path/to/orto_v1/docs/knowledge
|
||||||
|
✓ scripts: /path/to/orto_v1/scripts
|
||||||
|
```
|
||||||
|
|
||||||
|
**Per LLM:** Usa questo output come contesto per Fase 1 (analisi framework).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### `02_create_structure.sh` — Crea Struttura Distribuzione
|
||||||
|
|
||||||
|
**Scopo:** Organizza skills e references in struttura finale, crea symlink.
|
||||||
|
|
||||||
|
**Input:**
|
||||||
|
- Nome framework (es. `orto-skills`)
|
||||||
|
- Directory sorgente (con skills e references generate)
|
||||||
|
|
||||||
|
**Output:**
|
||||||
|
- Directory `<framework>-suite/` organizzata
|
||||||
|
- Symlink `references/` in ogni skill
|
||||||
|
|
||||||
|
**Utilizzo:**
|
||||||
|
```bash
|
||||||
|
./scripts/02_create_structure.sh orto-skills ./output/
|
||||||
|
```
|
||||||
|
|
||||||
|
**Output esempio:**
|
||||||
|
```
|
||||||
|
📦 Creazione struttura distribuzione: orto-skills-suite
|
||||||
|
==============================================
|
||||||
|
|
||||||
|
### Spostamento skills...
|
||||||
|
✓ Skill: orto-init
|
||||||
|
✓ Skill: orto-agronomo
|
||||||
|
✓ Skill: orto-calendario
|
||||||
|
|
||||||
|
### Spostamento references...
|
||||||
|
✓ References directory
|
||||||
|
|
||||||
|
### Creazione symlink references...
|
||||||
|
✓ Symlink: orto-init/references → ../references
|
||||||
|
✓ Symlink: orto-agronomo/references → ../references
|
||||||
|
✓ Symlink: orto-calendario/references → ../references
|
||||||
|
|
||||||
|
✅ Struttura creata: orto-skills-suite
|
||||||
|
```
|
||||||
|
|
||||||
|
**Per LLM:** Esegui dopo Fase 4 (generazione skills completata).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### `03_generate_packaging.sh` — Genera Packaging
|
||||||
|
|
||||||
|
**Scopo:** Genera `INSTALL.sh` e `README.md` per distribuzione.
|
||||||
|
|
||||||
|
**Input:**
|
||||||
|
- Directory distribuzione (`<framework>-suite/`)
|
||||||
|
|
||||||
|
**Output:**
|
||||||
|
- `INSTALL.sh` (script installazione automatica)
|
||||||
|
- `README.md` (documentazione con lista skills)
|
||||||
|
|
||||||
|
**Utilizzo:**
|
||||||
|
```bash
|
||||||
|
./scripts/03_generate_packaging.sh ./orto-skills-suite
|
||||||
|
```
|
||||||
|
|
||||||
|
**Output esempio:**
|
||||||
|
```
|
||||||
|
📦 Generazione packaging per: ./orto-skills-suite
|
||||||
|
==============================================
|
||||||
|
|
||||||
|
### Generazione INSTALL.sh...
|
||||||
|
✓ INSTALL.sh generato
|
||||||
|
|
||||||
|
### Generazione README.md...
|
||||||
|
✓ README.md generato
|
||||||
|
|
||||||
|
✅ Packaging completato
|
||||||
|
|
||||||
|
File generati:
|
||||||
|
-rwxr-xr-x INSTALL.sh
|
||||||
|
-rw-r--r-- README.md
|
||||||
|
```
|
||||||
|
|
||||||
|
**Per LLM:** Esegui come ultimo step (Fase 5).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Workflow Completo (LLM + Script)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# FASE 1-4: LLM (leggi SKILL.md, esegui analisi e generazione)
|
||||||
|
# ... LLM lavora su analysis_report.md, mapping_plan.md, references/, skills/ ...
|
||||||
|
|
||||||
|
# FASE 5: Script meccanici
|
||||||
|
|
||||||
|
# 1. Scansione iniziale (opzionale, per contesto)
|
||||||
|
./scripts/01_scan_files.sh /path/to/framework > ./output/scan_results.txt
|
||||||
|
|
||||||
|
# 2. Crea struttura distribuzione (dopo Fase 4)
|
||||||
|
./scripts/02_create_structure.sh orto-skills ./output/
|
||||||
|
|
||||||
|
# 3. Genera packaging (dopo step 2)
|
||||||
|
./scripts/03_generate_packaging.sh ./orto-skills-suite
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Differenze vs. Approccio Python (Archiviato)
|
||||||
|
|
||||||
|
| Aspetto | Script Python (archiviati) | Script Bash (attuali) |
|
||||||
|
|---------|---------------------------|----------------------|
|
||||||
|
| **Analisi semantica** | Sì (regex, euristico) | No (solo meccanico) |
|
||||||
|
| **Generazione contenuto** | Sì (template rigido) | No (fatto da LLM) |
|
||||||
|
| **Linee di codice** | ~2,000 | ~150 |
|
||||||
|
| **Manutenzione** | Complessa (test, debug) | Semplice (solo I/O) |
|
||||||
|
| **Flessibilità** | Bassa (formati fissi) | Alta (LLM si adatta) |
|
||||||
|
| **Token usage** | 0 | ~35-65K per framework |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Script Archiviati (Python)
|
||||||
|
|
||||||
|
Gli script Python originali sono archiviati in:
|
||||||
|
```
|
||||||
|
scripts-archive/
|
||||||
|
├── analyze_framework.py # Fase 1 (parsing automatico)
|
||||||
|
├── map_entities.py # Fase 2 (mappatura euristica)
|
||||||
|
├── extract_knowledge.py # Fase 3 (estrazione keyword)
|
||||||
|
└── generate_skill.py # Fase 4 (template rigido)
|
||||||
|
```
|
||||||
|
|
||||||
|
**Perché archiviati:** Troppo complessi, fragili, output generico. L'approccio LLM-native è più flessibile e produce output di qualità superiore.
|
||||||
|
|
||||||
|
**Quando usarli:** Solo come riferimento o se vuoi sperimentare approccio ibrido.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Note Tecniche
|
||||||
|
|
||||||
|
### Bash vs. Python
|
||||||
|
|
||||||
|
**Bash scelto perché:**
|
||||||
|
- Script <100 linee (semplici)
|
||||||
|
- Solo I/O e operazioni file
|
||||||
|
- Nessuna logica complessa
|
||||||
|
- Ubiquo (tutti i sistemi Unix)
|
||||||
|
|
||||||
|
**Python non necessario perché:**
|
||||||
|
- LLM fa analisi/generazione
|
||||||
|
- Script sono solo "colla" meccanica
|
||||||
|
|
||||||
|
### Compatibilità
|
||||||
|
|
||||||
|
Testato su:
|
||||||
|
- Linux (Ubuntu/Debian)
|
||||||
|
- macOS
|
||||||
|
- Windows (WSL, Git Bash)
|
||||||
|
|
||||||
|
### Permessi
|
||||||
|
|
||||||
|
Assicura che gli script siano eseguibili:
|
||||||
|
```bash
|
||||||
|
chmod +x scripts/*.sh
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
_Aggiornato: 2026-03-07 | Versione: 2.0 (LLM-Native)_
|
||||||
Loading…
Add table
Add a link
Reference in a new issue