# Plugin e Skill

## Plugin

### Cosa Sono i Plugin?

I plugin sono moduli TypeScript che estendono le funzionalità di Neotask a runtime. Possono aggiungere nuovi canali di messaggistica, strumenti per gli agenti, metodi RPC, comandi CLI, servizi in background e skill.

### Plugin Ufficiali

**Canali di Messaggistica:**
- Microsoft Teams, Matrix, Nostr, Zalo, Feishu/Lark, LINE, Nextcloud Talk, Mattermost, Tlon, Twitch

**Funzionalità:**
- **Voice Call**, Supporto telefonia SIP per chiamate vocali in entrata/uscita
- **Memory (LanceDB)**, Memoria a lungo termine con ricerca per somiglianza vettoriale
- **MCP Native**, Integrazione del server Model Context Protocol per il collegamento di strumenti esterni

**Provider di Autenticazione:**
- Google Antigravity OAuth, Gemini CLI OAuth, Qwen OAuth, Minimax OAuth, VS Code Copilot Proxy

### Capacità dei Plugin

I plugin possono registrare:
- **Metodi RPC**, Metodi WebSocket personalizzati che i client possono chiamare
- **HTTP Handler**, Endpoint HTTP personalizzati sul Gateway
- **Strumenti per Agenti**, Nuovi strumenti con schemi tipizzati che gli agenti possono invocare
- **Comandi CLI**, Comandi aggiuntivi da riga di comando
- **Servizi in Background**, Processi a lunga esecuzione gestiti dal Gateway
- **Skill**, Directory di skill incluse nel plugin
- **Comandi Auto-Reply**, Comandi che si eseguono senza il coinvolgimento dell'agente AI

### Sicurezza dei Plugin

Neotask controlla i plugin a più livelli prima che vengano eseguiti:

- **Firmati e verificati.** I pacchetti del catalogo pubblico Construct sono pubblicati da Neotask, ispezionati automaticamente prima del rilascio e firmati con la chiave di rilascio di Neotask. Prima di installarne uno, Neotask verifica la firma con chiavi integrate in Neotask e controlla l'hash SHA-256 del download.
- **Nessuno script di installazione.** I pacchetti Construct includono le proprie dipendenze, quindi l'installazione non esegue mai un gestore di pacchetti né uno script di installazione. Quando un'altra installazione di plugin usa npm, gli script di installazione sono disattivati.
- **Scansione all'installazione.** I plugin installati al di fuori di Construct vengono analizzati alla ricerca di codice pericoloso, e i problemi critici bloccano l'installazione.
- **Licenza per versione.** Un plugin Construct viene caricato solo finché il tuo account ha un'autorizzazione valida per quella versione. Le versioni revocate non vengono caricate.
- **Approvazioni per le azioni degli agenti.** Le chiamate agli strumenti degli agenti, compresi quelli aggiunti dai plugin, vengono verificate rispetto alla tua politica di approvazione, e le azioni che richiedono il tuo consenso lo attendono. Il software che un agente vuole installare al di fuori delle ricette di installazione incluse in Neotask ti mostra sempre il comando esatto e attende la tua approvazione.
- **Sandbox facoltativa.** Puoi eseguire gli strumenti di un agente in un container Docker isolato invece che direttamente sul tuo computer. La sandbox è disattivata per impostazione predefinita; consulta [Sicurezza](security.md) per attivarla.

I plugin nativi vengono eseguiti all'interno del processo del Gateway, quindi un plugin installato al di fuori di Construct è codice che scegli di eseguire. Usa `plugins.allow` per elencare i plugin che possono essere caricati.

---

## Skill

### Cosa Sono le Skill?

Le skill sono capacità modulari che insegnano nuovi flussi di lavoro agli agenti. Ogni skill è un file markdown (`SKILL.md`) con istruzioni che vengono iniettate nel contesto dell'agente quando pertinenti.

### Posizioni delle Skill (Ordine di Priorità)

1. **Skill del workspace**, `<workspace>/skills/` (priorità più alta)
2. **Skill gestite**, `~/.neotask/skills/`
3. **Skill incluse**, Fornite con Neotask
4. **Skill dei plugin**, Skill incluse con i plugin installati
5. **Directory extra**, Percorsi configurati aggiuntivi (priorità più bassa)

Quando più skill condividono lo stesso nome, vince la posizione con priorità più alta.

### Funzionalità delle Skill

- **Invocabili dall'utente**, Attiva le skill direttamente con comandi slash (es. `/docker-build`)
- **Invocabili dal modello**, Skill che l'agente può invocare autonomamente quando pertinente
- **Command dispatch**, Skill che mappano a strumenti specifici
- **Gating dei requisiti**, Le skill si caricano solo quando i loro requisiti sono soddisfatti (binari richiesti, chiavi di configurazione, variabili d'ambiente, plugin)

### Creare Skill

Crea un file `SKILL.md` con frontmatter YAML che definisce i metadati e le istruzioni della skill:

**Campi del frontmatter:**
- `name`, Identificatore della skill
- `description`, Cosa fa la skill
- `homepage`, Link alla documentazione
- `user-invocable`, Se gli utenti possono attivarla direttamente
- `disable-model-invocation`, Impedisce all'agente di invocarla autonomamente
- `command-dispatch`, Strumento a cui fare dispatch
- `metadata.neotask.requires`, Prerequisiti (bin, config, env, plugin)

**Corpo:** Istruzioni markdown che insegnano all'agente come usare la skill, inclusi esempi e linee guida.

### Catalogo delle Skill

Sfoglia le skill disponibili nel [catalogo delle skill](/skills).

### Categorie delle Skill

Le skill coprono un'ampia gamma di capacità:

| Categoria | Esempi |
|----------|---------|
| **Produttività** | Gestione email, calendario, generazione documenti |
| **Sviluppo** | Operazioni Git, CI/CD, Docker, revisione del codice |
| **Comunicazione** | Messaggistica, notifiche, annunci |
| **Media** | Elaborazione immagini, editing video, trascrizione audio |
| **AI e Modelli** | Cambio modello, gestione prompt, RAG |
| **Smart Home** | Controllo dispositivi IoT, trigger di automazione |
| **Utility** | Conversione file, trasformazione dati, web scraping |