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

---
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 : → altrimenti se : → altrimenti: →

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

# 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 — [Breve descrizione contenuto]
• <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:

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:

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

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

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

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:

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

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

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

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

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

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