framework-translator/references/skill_template.md

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