400 lines
9 KiB
Markdown
400 lines
9 KiB
Markdown
# 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_
|