Skip to Content
Sviluppo App IoTSkill dell'App

Skill dell’App

Una skill dell’app è un insieme di istruzioni che uno degli agenti AI della tua app carica su richiesta, invece di portarle nel proprio system_prompt a ogni turno.

All’inizio l’agente vede solo il nome e la descrizione di ogni skill. Quando un’attività richiede una skill, l’agente ne carica le istruzioni. Una skill non costa nulla finché l’agente non la carica, quindi puoi dare all’agente procedure lunghe e materiale di riferimento senza appesantire ogni conversazione.

Le skill dell’app sono istruzioni per gli agenti della tua stessa app. Non sono la skill che Sviluppare con Claude Code installa per il tuo agente di programmazione.

Skill o System Prompt?

Il system_prompt viene letto a ogni turno. Una skill viene letta solo quando l’agente decide di caricarla.

Da mettere nel system_promptDa mettere in una skill
Il ruolo dell’agenteConoscenze di cui hanno bisogno solo alcune attività
Regole che valgono sempreProcedure lunghe, come una diagnosi o un controllo di messa in servizio
Regole di sicurezza: ciò che l’agente non deve mai fare o deve prima far confermareRiferimenti del dominio, come i codici di guasto o i parametri di una macchina
Fatti brevi

Un agente che non carica mai una skill deve comunque rispettare ogni regola di sicurezza, quindi queste regole restano sempre nel system_prompt.

Formato della Cartella di una Skill

Le skill si trovano nel repository della tua app, accanto agli altri file in .ironflock/:

.ironflock/ ├── ai-template.yml └── skills/ └── machine-diagnosis/ ├── SKILL.md └── references/ └── codes-press.md
  • .ironflock/skills/<name>/SKILL.md è obbligatorio. Inizia con un frontmatter YAML, seguito dalle istruzioni in Markdown.
  • .ironflock/skills/<name>/references/<file>.md è facoltativo. Usa i file di riferimento per il materiale di cui hanno bisogno solo alcune attività. L’agente carica ciascun file solo quando gli serve, quindi ogni file di riferimento deve essere comprensibile da solo. SKILL.md indica quale file leggere e quando.
  • Nella cartella delle skill non deve esserci nient’altro: niente script, niente immagini, niente link simbolici. Tutti i file sono testo UTF-8.

Il frontmatter ha due campi:

--- name: machine-diagnosis description: >- How to find out why a machine is TOO_HOT or shows NO_READING. Load it before you answer such a question. ---
CampoDescrizione
nameDeve essere uguale al nome della cartella.
descriptionTesto semplice. È tutto ciò che l’agente vede finché non carica la skill.

Elencare una Skill in un Agente

Una skill non fa nulla finché un agente non la elenca. In .ironflock/ai-template.yml, aggiungi la chiave skills all’agente e indica ogni skill con il nome della sua cartella:

machines: main: true skills: [machine-diagnosis]

Scrivi solo il nome della cartella. Non iniziare mai una voce con app/ o project/.

All’agente la skill viene offerta come app/<name>, qui app/machine-diagnosis. Il testo del tuo system_prompt o della tua tool_description che menziona una skill usa questa forma.

Ogni cartella di skill deve essere elencata da almeno un agente, e ogni agente elenca una skill una sola volta.

Skill della Piattaforma

Una voce nella forma platform/<name> è riservata alle skill che la piattaforma mette a disposizione delle app. Al momento non è disponibile nessuna skill della piattaforma, quindi una voce di questo tipo oggi fa fallire la build della release.

Limiti

CosaLimite
Nome della skillLettere minuscole e cifre, unite da singoli trattini; al massimo 64 caratteri
DescrizioneAl massimo 500 caratteri
Istruzioni (SKILL.md)Al massimo 20.000 caratteri
Un file di riferimentoAl massimo 40.000 caratteri
File di riferimento per skillAl massimo 20
Skill per appAl massimo 20
Tutti i file delle skill di un’app insiemeAl massimo 2 MiB
Skill elencate da un agenteAl massimo 20

Cosa Controlla la Build della Release

Quando crei una release, la build controlla le skill insieme a ai-template.yml. Se un controllo fallisce, la release non viene creata e viene mostrato il primo problema trovato. Correggilo e crea di nuovo la release.

La build fallisce quando:

  • un agente elenca una skill che non ha una cartella;
  • una cartella di skill non è elencata da nessun agente;
  • l’app ha una cartella delle skill ma non ha ai-template.yml;
  • una voce di skills inizia con app/ o project/;
  • una voce inizia con platform/ (non è ancora disponibile nessuna skill della piattaforma);
  • un file nella cartella delle skill non è testo UTF-8, è un link simbolico, oppure non è SKILL.md né un file references/<file>.md;
  • viene superato un limite della tabella qui sopra;
  • un agente ha uno strumento chiamato load_skill. Il nome è riservato al caricamento delle skill, in ogni app.

Esempio

Questa skill spiega all’agente come scoprire perché una macchina segnala un guasto. Qui è abbreviata. Una nuova app parte con tre skill complete in .ironflock/skills/ che puoi leggere, modificare o rimuovere.

.ironflock/skills/machine-diagnosis/SKILL.md:

--- name: machine-diagnosis description: >- How to find out why a machine is TOO_HOT or shows NO_READING, or what is wrong with a machine a user asks about: which rows to read, when to read the machine now with current_reading, and what to tell the user. Load it before you answer such a question. --- # Diagnosing a machine A user asked why a machine is too hot, why it has no reading, or what is wrong with it. Find the cause in the app's tables and at the machine, then answer with the evidence. You only read: you cannot change the limit or a machine. ## 1. Find the device and its state Run with `execute_sql`: ```sql SELECT DISTINCT ON (device_id) device_id, device_name, state, tsp FROM devices ORDER BY device_id, tsp DESC ``` `state` is `OK`, `TOO_HOT` or `NO_READING`. When the user named no machine, take the devices whose state is not `OK`. ## 2. Check the machine now Call `current_reading` for the device and compare its values with the newest rows of `measurements`. When the call fails, the device is offline: say since when. Do not tell anyone that a machine running too hot is safe to keep running.

L’agente che la elenca, in .ironflock/ai-template.yml:

machines: main: true tool_description: | Delegate to this agent when the user asks about the state of a machine. system_prompt: | You answer questions about the machines this app watches. You only read. Never tell anyone that a machine running too hot is safe to keep running. When a user asks why a machine is too hot or has no reading, load the skill app/machine-diagnosis and follow it. data_access: true skills: [machine-diagnosis] tools: current_reading: description: Reads the machine at one device now. topic: current_reading

La frase del system_prompt che inizia con “When a user asks” si riferisce alla skill come app/machine-diagnosis. La regola di sicurezza resta nel system_prompt, perché un agente che non carica la skill deve comunque rispettarla.

Provare le Skill senza una Release

Non ti serve una release per provare un agente o una skill. Il Cloud IDE ha una chat di sviluppo che esegue la tua copia di lavoro.

Nel pannello laterale del Cloud IDE, la sezione Agenti IA ha due azioni:

  • Apri chat di sviluppo applica la tua copia di lavoro e apre una chat che la usa.
  • Aggiorna agenti IA applica le ulteriori modifiche a ai-template.yml e alle skill.

La chat di sviluppo:

  • esegue la tua copia di lavoro dell’app, con il data backend di sviluppo del progetto;
  • è il normale assistente del progetto, con gli agenti, gli strumenti e le skill di questa app presi dalla tua copia di lavoro;
  • è l’unica chat che li riceve. A nessun altro, e a nessun’altra chat, viene offerta la tua copia di lavoro.

Una chat di sviluppo in corso usa le tue modifiche dal messaggio successivo, quindi puoi modificare una skill, fare clic su Aggiorna agenti IA e chiedere di nuovo nella stessa chat.

Se il template o una skill non è valido, viene mostrato lo stesso messaggio della build di una release e continua a essere usata la versione precedente.

La chat di sviluppo richiede il data backend di sviluppo dell’app nel progetto del dispositivo selezionato.

Dove gli Utenti Vedono le Skill

In Studio, la scheda Plugin IA dell’app elenca ogni agente con le sue skill, mostrando il nome e la descrizione di ciascuna skill. Il testo della skill non viene mai mostrato lì.

Installazioni Precedenti

Un Appliance che non è ancora stato aggiornato installa l’app e la esegue. I suoi agenti funzionano senza le skill e lo dicono all’utente quando un’attività ne richiede una. Dopo l’aggiornamento dell’Appliance, le skill arrivano con la sincronizzazione successiva dell’app.

Scrivere Buone Skill

  • La descrizione dice a cosa serve la skill e quando caricarla. Finché l’agente non carica la skill, la descrizione è tutto ciò che vede. Usa le parole che usano i tuoi utenti e i tuoi dati, come valori di stato, sintomi e attività, e concludi indicando quando caricare la skill: “Load it before you answer why a machine is TOO_HOT.” Una descrizione come “Information about machines” non viene mai caricata al momento giusto.
  • Rendi le istruzioni autosufficienti. L’agente le legge nel mezzo di un’attività, con un utente in attesa. Indica con precisione le tabelle, le colonne e gli strumenti della tua app invece di affidarti al system_prompt.
  • Scrivi passi imperativi, nell’ordine in cui vanno seguiti. Indica quando fermarsi e cosa dire all’utente.
  • Indica cosa non fare.

Prossimi Passi

Last updated on