# AGENTS.md — Orto Skills Installation & Setup Agent Instructions

**Per agenti OpenClaw che ricevono pacchetto orto-skills e devono installare le skill**

---

## 🎯 Scopo

Quando un utente carica il pacchetto `orto-skills-v*.tar.gz` in chat e chiede di installare le skill, un agente deve:

1. **Estrarre** il pacchetto `.tar.gz`
2. **Eseguire** `INSTALL.sh` per copiare le skill in `~/.openclaw/skills/orto-suite/`
3. **Verificare** che i 9 SKILL.md + 8 reference file siano presenti
4. **Guida utente** verso il prossimo step (creazione orto)

---

## 📋 Step-by-Step Per l'Agente

### Fase 1: Ricevere il Pacchetto

**Trigger:** Utente carica file `.tar.gz` e chiede "installa", "estrai", "setup"

**Azioni agente:**
```
✅ Detect file upload
✅ Verify filename ends with .tar.gz
✅ Verify size ~77 KB (orto-skills-v1.0-dist.tar.gz)
```

**Messaggio all'utente:**
```
📦 Ho ricevuto il pacchetto!
   - Filename: orto-skills-v1.0-dist.tar.gz
   - Size: 77 KB ✓
   
Procedo con estrazione e installazione...
(30-45 secondi)
```

---

### Fase 2: Estrarre il Pacchetto

**Dove:** Cartella temporanea (es: `/tmp/orto-install-<timestamp>/`)

**Comandi eseguiti dall'agente:**
```bash
# 1. Crea cartella temporanea
WORK_DIR=$(mktemp -d)
cd $WORK_DIR

# 2. Estrai tar.gz
tar -xzf /tmp/uploads/orto-skills-v1.0-dist.tar.gz

# 3. Verifica struttura
ls -la orto-skills/
  └─ orto-suite/
  └─ INSTALL.sh
  └─ README.md
  └─ ...
```

**Verifiche:**
```
✅ orto-skills/ estratto
✅ orto-suite/ presente
✅ INSTALL.sh presente e executable
```

---

### Fase 3: Eseguire INSTALL.sh

**Azioni agente:**
```bash
# Navigare in cartella estratta
cd $WORK_DIR/orto-skills

# Eseguire script di installazione
./INSTALL.sh
```

**Output atteso:**
```
✅ Source directory found
✅ Copying orto-suite to ~/.openclaw/skills/orto-suite/
✅ Copied successfully
✅ Verifying installation...
✅ Found 9 SKILL.md files
✅ Found 8 reference files
✅ Installation verified

║ ✅ INSTALLATION COMPLETED SUCCESSFULLY
```

**Se utente risponde "n" al prompt di overwrite:**
```
⚠️ Installazione non eseguita (utente ha rifiutato)
Vuoi procedere con overwrite? Scrivi "sì" per continuare
```

---

### Fase 4: Verificare Installazione

**Azioni agente:**
```bash
# Verifica file installati
ls -la ~/.openclaw/skills/orto-suite/

# Conta SKILL.md
find ~/.openclaw/skills/orto-suite -name "SKILL.md" | wc -l

# Conta reference files
ls ~/.openclaw/skills/orto-suite/references/*.md | wc -l

# Test symlink resolution
ls ~/.openclaw/skills/orto-suite/orto-init/references/*.md | wc -l
```

**Criterio successo:**
```
✅ 9 SKILL.md trovati
✅ 8 reference files trovati
✅ Symlink risolti: tutti 8 reference file accessibili
✅ Directory structure coerente
```

---

### Fase 5: Guida Utente al Prossimo Step

**Messaggio di successo:**
```
🎉 INSTALLAZIONE COMPLETATA!

✅ 9 skill installate in ~/.openclaw/skills/orto-suite/
✅ 8 reference files centralizzati
✅ Symlink verif ied ✓

Adesso puoi:

1️⃣ Creare il tuo primo orto:
   "Voglio creare un orto a Roma, Lazio"
   
2️⃣ Oppure se hai domande:
   "Dove si trova il mio orto? Come funziona il sistema?"

Pronto? 🌱
```

**Se fallisce:**
```
❌ INSTALLAZIONE FALLITA

Errore: [descrizione errore dal log]

Possibili soluzioni:
1. Verifica che il pacchetto sia integro
2. Controlla che ~/.openclaw/skills/ sia scrivibile
3. Riprova con: "Installa di nuovo"

Se persiste, contatta support.
```

---

## 🔧 Dettagli Tecnici Per Agenti

### Percorsi Chiave

```
Pacchetto uploaddato:  /tmp/uploads/orto-skills-v1.0-dist.tar.gz
Lavoro temporaneo:     /tmp/orto-install-<timestamp>/
Estratto pacchetto:    /tmp/orto-install-<timestamp>/orto-skills/
Script INSTALL.sh:     /tmp/orto-install-<timestamp>/orto-skills/INSTALL.sh
Destinazione finale:   ~/.openclaw/skills/orto-suite/
```

### Cartella Installata (Struttura)

```
~/.openclaw/skills/orto-suite/
├── orto-init/
│   ├── SKILL.md
│   ├── references → ../references (symlink)
│   ├── assets/
│   └── scripts/
├── orto-agronomo/
├── orto-calendario/
├── orto-fitopatologo/
├── orto-irrigazione/
├── orto-layout/
├── orto-meteo-decisioni/
├── orto-onboarding/
├── orto-orchestratore/
└── references/ (8 file)
    ├── colture_it.md
    ├── calendario_it.md
    ├── malattie_trattamenti.md
    ├── irrigazione_parametri.md
    ├── consociazioni_layout.md
    ├── meteo_soglie.md
    ├── conflitti_risoluzione.md
    └── qa_checklist.md
```

### Comandi di Verifica

```bash
# Totale file SKILL.md
find ~/.openclaw/skills/orto-suite -name "SKILL.md" | wc -l
# Atteso: 9

# Totale reference files
ls ~/.openclaw/skills/orto-suite/references/*.md | wc -l
# Atteso: 8

# Verifica symlink
readlink ~/.openclaw/skills/orto-suite/orto-init/references
# Atteso: ../references (output testuale)

# Test accesso via symlink
ls ~/.openclaw/skills/orto-suite/orto-agronomo/references/*.md | wc -l
# Atteso: 8
```

---

## 📊 Flusso di Installazione Completo

```
┌─ UTENTE AZIONI ──────────────┐    ┌─ AGENTE AZIONI ──────────┐
│                              │    │                          │
│ 1. Carica .tar.gz            │──→ │ 1. Detect + verify file  │
│                              │    │                          │
│ 2. "Installa le skill"       │──→ │ 2. Extract tar.gz        │
│                              │    │                          │
│ 3. [Aspetta]                 │    │ 3. Run INSTALL.sh        │
│    (30-45 secondi)           │    │                          │
│                              │    │ 4. Verify installation   │
│ 4. Riceve conferma           │←── │                          │
│    ✅ Installazione ok       │    │ 5. Report to user        │
│                              │    │                          │
│ 5. "Crea orto a Roma"        │──→ │ 6. Invoke orto-init      │
│                              │    │                          │
└──────────────────────────────┘    └──────────────────────────┘
```

---

## 🚨 Gestione Errori

### Errore: File Corrotto

**Scenario:** Decompressione fallisce

```bash
# Agente:
tar -tzf /tmp/uploads/orto-skills-v1.0-dist.tar.gz > /dev/null 2>&1
if [ $? -ne 0 ]; then
  echo "❌ File corrupted or invalid tar.gz"
  exit 1
fi
```

**Messaggio utente:**
```
❌ ERRORE: Pacchetto corrotto

Il file non è un tar.gz valido.
Controlla di aver scaricato il file corretto da:
  https://github.com/...

Scarica di nuovo e riprova.
```

---

### Errore: INSTALL.sh Non Eseguibile

**Scenario:** Permission denied

```bash
# Agente:
chmod +x orto-skills/INSTALL.sh
./orto-skills/INSTALL.sh
```

**Messaggio utente:**
```
⚠️ ATTENZIONE: Script non eseguibile

Ho corretto i permessi e riprovo...
```

---

### Errore: ~/.openclaw/skills/ Non Scrivibile

**Scenario:** Permission denied su destinazione

```bash
# Agente:
if [ ! -w ~/.openclaw/skills ]; then
  echo "❌ Directory not writable"
  exit 1
fi
```

**Messaggio utente:**
```
❌ ERRORE: Permessi insufficienti

La cartella ~/.openclaw/skills/ non è scrivibile.
Questo può accadere se:
1. Il sistema file è read-only
2. Hai cambiato permessi manualmente

Contatta il tuo amministratore di sistema.
```

---

## ✅ Checklist Per Agenti

Quando ricevi richiesta di installazione:

- [ ] Detect file upload (.tar.gz)
- [ ] Verify file size and name
- [ ] Extract in temporary directory
- [ ] Verify orto-skills/ structure
- [ ] Verify orto-suite/ present
- [ ] Verify INSTALL.sh executable
- [ ] Run INSTALL.sh
- [ ] Parse output (success vs failure)
- [ ] If failed, handle error
- [ ] If success, verify installation
- [ ] Count SKILL.md (9 expected)
- [ ] Count reference files (8 expected)
- [ ] Test symlink resolution
- [ ] Report success/failure to user
- [ ] Suggest next step (orto-init)
- [ ] Cleanup temporary directory

---

## 🎯 Next Steps Per Utente

Dopo installazione, guidare utente verso:

### Opzione A: Setup Interattivo
```
"Mi guidi a creare il mio primo orto?"

Agente guiderà attraverso:
1. Localizzazione (provincia, regione)
2. Profilo orto (spazio, dieta, tempo disponibile)
3. Generazione piano completo
```

### Opzione B: Solo Info
```
"Voglio saperne di più sulle skill"

Agente presenterà:
- Elenco 9 skill disponibili
- Workflow tipico: init → onboarding → agronomo → orchestratore
- Esempi di output
```

### Opzione C: Manuale
```
"Come uso le skill?"

Agente guiderà all'README.md e INSTALL_INTERACTIVE.md
```

---

## 📞 Supporto

Se agente riceve errore non documentato:

```
❓ ERRORE NON RICONOSCIUTO

Dettagli:
[descrizione errore completa]

Questo potrebbe essere un problema di sistema.
Per supporto: contatta il tuo amministratore OpenClaw

Log salvato in: ~/.openclaw/logs/orto-install-<timestamp>.log
```

---

_Last Updated: 2026-03-07 02:17 GMT+1_