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
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_
|
||||
Loading…
Add table
Add a link
Reference in a new issue