AI & MCP

Anatomia di una agent skill: nome, descrizione, corpo

Una agent skill è una cartella con istruzioni e risorse: il frontmatter dice quando usarla, il corpo dice come eseguire. Ecco cosa regge nel tempo.

In sintesi

  • Nome in kebab-case e descrizione con i trigger: è la parte sempre in contesto.
  • Il corpo contiene comandi e regole, non un riassunto della documentazione.
  • Una skill non concede permessi: descrive un metodo che il client deve poter fermare.

Una agent skill è una cartella versionata con un file di istruzioni e le risorse che servono a eseguirle; il resto è convenzione. Il minimo reale è un nome e una descrizione che dica quando usarla.

Anatomia minima

  • Nome: kebab-case, stabile, uguale al nome della cartella.
  • Descrizione: cosa fa e quando invocarla, con i termini che l'utente userebbe.
  • Corpo: passi, comandi e regole, nell'ordine in cui vanno eseguiti.
  • Risorse: file di riferimento e script, caricati solo quando servono.

Il frontmatter

---
name: eneui-blog
description: Produce or repair an EneUI blog article (Italian and English pair)
  end to end: JSON shape, measured-data contract, English rewrite rules,
  validation commands, covers and sitemap. Use whenever writing a post
  under data/blog/.
---

# EneUI blog article, end to end

One post = one file: data/blog/.json, holding the Italian source and
the English edition. Never create separate EN files.
## Fast path

Due campi, nessun percorso assoluto. La descrizione è lunga di proposito: contiene i verbi che fanno scattare l'invocazione, come scrivere, riscrivere, tradurre e verificare un post.

La descrizione è il routing

Il client legge solo nome e descrizione finché non decide di aprire la skill. Se la descrizione non nomina il compito, la skill non viene scelta, anche se il corpo è perfetto. Vale la pena sprecare righe qui e risparmiarle altrove.

Il corpo esegue, non racconta

Nella skill eneui-blog il corpo contiene il percorso del file, i comandi di validazione e i divieti, per esempio non scrivere JSON con PowerShell e non inventare un conteggio. Ogni riga o si esegue o si controlla: un riassunto della documentazione invecchia due volte.

Progressive disclosure

Il corpo resta corto e i dettagli vivono in file separati, letti solo quando servono. La skill del blog cita docs/SEO-1000-PLAN.md e docs/EN-REWRITE.md senza copiarli: 82 righe invece di tre documenti interi nel contesto.

Cosa rompe una skill

  • Un comando rinominato che resta nel testo: la skill fallisce senza un errore chiaro.
  • Nessun passo di validazione: l'agente dichiara finito ciò che non ha verificato.
  • Documentazione duplicata: due fonti divergono e il modello sceglie quella sbagliata.

Un agente che costruisce UI può partire da agent dock di dqnamo, oppure sfogliare i 111.985 componenti e i 1.556 blocchi. La skill pubblicata dal server è su /agents e l'endpoint su /mcp.

La limitazione

Una skill è testo: non concede permessi e non impedisce un comando. Se il client non limita la shell, la skill può solo chiedere prudenza. Inoltre la descrizione consuma contesto in ogni sessione, quindi ogni trigger aggiunto toglie spazio ad altri.

Dove continuare

La scrittura del prompt è in prompt per agenti, non per chat; il contesto è in che cos'è un agente AI. Per i rischi leggi sicurezza di un agente di coding, e per la documentazione dei componenti come documentare i componenti.

Domande frequenti

Quali file deve contenere una agent skill?

Un file di istruzioni, di solito SKILL.md, con frontmatter name e description. Gli altri file sono risorse facoltative, lette solo quando la skill viene eseguita.

Quanto deve essere lunga la descrizione?

Abbastanza da contenere i trigger di invocazione, non un riassunto del corpo. Nel repository EneUI la descrizione di eneui-blog nomina scrittura, riscrittura, traduzione e verifica di un post.

Dove vanno i comandi di build e test?

Nel corpo, copiabili così come sono. Un comando raccontato a parole viene ricostruito male; un comando incollato funziona o fallisce con un messaggio leggibile.

Una skill può impedire un'azione pericolosa?

No. La skill è testo e non concede né revoca permessi: la protezione sta nella configurazione del client che limita comandi e file accessibili.

Come si evita che una skill invecchi?

Citando file e comandi invece di copiarli, e chiudendo con un passo di validazione. Se il comando cambia, la skill rimanda alla fonte e non duplica una versione vecchia.