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.
2026-03-07 10:14:37 +01:00 · 2026-03-07 10:14:37 +01:00 · c40ddf4b59
commit c40ddf4b59
9 changed files with 3344 additions and 0 deletions
--- a/references/mapping_patterns.md
+++ b/references/mapping_patterns.md
@ -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_
--- a/references/skill_template.md
+++ b/references/skill_template.md
@ -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_