Sei nel mezzo di un deploy. Terminale aperto. Tre sessioni SSH. Una code review a metà. Poi arriva il messaggio: “Hai lasciato il riscaldamento acceso a Ragusa?”

Potresti passare al browser. Cercare il bookmark. Aspettare che Home Assistant si carichi. Navigare fino all’entità giusta. Controllare. Tornare al terminale. Perdere il filo del diff.

Oppure potresti semplicemente chiedere.

Gestisco due case. Due istanze Home Assistant. Decine di entità distribuite su due siti connessi via Tailscale. Per mesi, la frizione è stata costante: tab del browser, URL nei preferiti, token diversi, il costo cognitivo del context-switching tra codice e casa.

Poi ho realizzato qualcosa di ovvio. Claude Code vive già nel mio terminale. Esegue già comandi shell. Capisce già il contesto.

Dovevo solo insegnargli dove sono le luci.

Cosa Fa hass-cli (e Cosa No)

hass-cli è il tool CLI ufficiale di Home Assistant. Comunica con le REST API di HA usando token di accesso a lunga durata. Puoi interrogare lo stato delle entità, chiamare servizi, elencare aree e dispositivi, persino renderizzare template Jinja2 lato server.

# Ottenere lo stato di un sensore
hass-cli state get sensor.living_room_temperature

# Accendere una luce
hass-cli service call light.turn_on --arguments entity_id=light.garden

# Elencare tutte le aree
hass-cli area list

Semplice. Potente. Ma c’è un problema.

hass-cli non sa di quale casa stai parlando. Non ricorda i tuoi server URL. Non sceglie il token giusto in base al contesto. È uno strumento. Gli strumenti non pensano.

È qui che entra in gioco la skill.

Cosa Sono le Skill di Claude Code

Una skill è un file Markdown. Tutto qui.

Nessun plugin SDK. Nessuna estensione compilata. Nessuna integrazione API. Solo un file .md con istruzioni chiare che insegnano a Claude Code come fare qualcosa di nuovo. Lo metti in ~/.claude/skills/, e Claude lo riconosce automaticamente.

Le skill possono essere:

  • Auto-attivate da parole chiave (“home assistant”, “luci”, “termostato”)
  • Invocate manualmente via /nomeskill nella CLI
  • Limitate a progetti specifici o rese globali

Una skill è un manuale di istruzioni ben scritto, per un’AI che sa davvero seguire le istruzioni.

Costruire la Skill /ha

La sfida principale: due server HA, due token, e la necessità che Claude scelga quello giusto senza chiederlo ogni volta.

Ecco la tabella di configurazione dei server dalla skill:

| Sito | Server URL | Variabile env token |
|------|-----------|---------------------|
| **MG** (default) | `https://mg-homeassistant.[tailnet]:8123` | `HA_API_TOKEN_MG` |
| **RG** | `https://rg-homeassistant.[tailnet]:8123` | `HA_API_TOKEN_RG` |

Entrambi i server sono accessibili via Tailscale. I token vivono in un file .env, caricati tramite direnv. Lo stesso pattern che uso per i secret di Ansible. Una singola fonte di verità, nessun token nel Markdown.

La Trappola di hass-cli di Cui Nessuno Ti Avverte

Queste cose le impari sulla tua pelle. Nella mia esperienza, il flag --token da CLI non si comporta sempre come previsto quando la variabile d’ambiente HASS_TOKEN è impostata. Passavo il token giusto sulla riga di comando, ma continuava a rispondere la casa sbagliata. Nessun errore. Nessun avviso.

Che sia un bug o una questione di precedenza, l’approccio più sicuro è sovrascrivere sempre tramite variabili d’ambiente, non flag CLI.

HASS_SERVER=https://rg-homeassistant.[tailnet]:8123 \
  HASS_TOKEN="$(grep HA_API_TOKEN_RG ~/Projects/ghost/.env | cut -d= -f2)" \
  hass-cli state get sensor.temperature

Brutto? Sì. Affidabile? Sempre. La skill incapsula questo pattern così non ci devo più pensare.

Regole di Selezione

Questa è la parte che lo fa sembrare intelligente. La skill insegna a Claude cinque regole per scegliere il server giusto:

  1. L’esplicito vince. Se dico “RG”, usa RG.
  2. “Entrambi” significa entrambi. Esegui il comando su entrambi i siti, mostra i risultati combinati.
  3. Nessun sito menzionato? Default su MG (dove passo la maggior parte del tempo).
  4. Telecamere e Frigate? Controlla sempre entrambi. La sicurezza non ha default.
  5. Dimmi sempre quale sito stai interrogando. Nessuna assunzione silenziosa.

Queste regole sono solo punti elenco in Markdown. Ma codificano mesi di “aspetta, quale casa hai appena interrogato?”.

Sicurezza

La skill include una regola ferrea: conferma prima di azioni distruttive. Spegnere il riscaldamento, bloccare le porte, disabilitare le automazioni. Claude chiede prima.

Non è paranoia. È il principio Bourne: fidati dello strumento per l’esecuzione, ma non fidarti mai di lui per decidere cosa è sicuro.

Come Si Presenta in Pratica

Io: “Qual è la temperatura a RG?”

Claude sceglie RG basandosi sulla menzione esplicita, costruisce il comando con il token giusto, lo esegue e restituisce un riepilogo pulito. Nessun entity ID da ricordare. Nessun URL da digitare.

Io: “Accendi le luci del giardino.”

Claude usa MG come default, identifica l’entità e chiede: “Chiamo light.turn_on per light.garden su MG. Confermi?” Una parola da parte mia. Fatto.

Io: “Mostrami tutte le telecamere su entrambi i siti.”

Entrambi i server interrogati. Risultati raggruppati per sito. Stati delle entità riassunti. Niente switch tra due tab del browser.

L’interazione è linguaggio naturale in ingresso, invocazione hass-cli corretta in uscita. La skill gestisce il livello di traduzione: selezione del server, iniezione del token, costruzione del comando, formattazione dell’output.

Perché Conta

Non si tratta di sostituire la dashboard di Home Assistant. Le dashboard sono ottime per quello che fanno: panoramica visiva, grafici storici, accesso mobile.

Si tratta di eliminare i context switch.

Quando sei già nel terminale, già nel flow, già a metà di un ragionamento su un problema di codice, il costo di passare al browser è reale. Non sono i secondi. È lo stato mentale che abbandoni e che potresti non recuperare mai del tutto.

Una skill trasforma Claude Code da assistente di programmazione a interfaccia CLI universale. Il pattern è generalizzabile. Qualsiasi tool CLI con una struttura di comandi chiara può diventare una skill:

  • Tool di infrastruttura (kubectl, terraform, ansible)
  • Monitoring (grafana-cli, query prometheus)
  • Comunicazione (slack-cli, gh)
  • Qualsiasi cosa con un flag --help e un output prevedibile

La skill è solo il ponte tra linguaggio naturale e l’incantesimo corretto.

Il Quadro Generale

Il terminale sta diventando l’interfaccia universale. Non perché è bello. Perché è veloce, componibile e ora, conversazionale.

L’AI è il livello che lo rende accessibile. Non devi memorizzare entity ID, sintassi dei flag o quale server ospita quale dispositivo. Descrivi quello che vuoi. La skill traduce. Il tool esegue.

Due case. Due server. Un solo comando /ha.

Non festeggi. Controlli le letture dei sensori e vai avanti.

Risorse: