9 KiB
9 KiB
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:
- Estrarre il pacchetto
.tar.gz - Eseguire
INSTALL.shper copiare le skill in~/.openclaw/skills/orto-suite/ - Verificare che i 9 SKILL.md + 8 reference file siano presenti
- 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:
# 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:
# 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:
# 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
# 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
# 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
# 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
# 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