# Anatomy of an agent skill: name, description, body

An agent skill is a folder of instructions and resources: the frontmatter says when to use it, the body says how to run it. Here is what survives time.

> Page: https://ui.eneawork.it/blog/agent-skill-struttura
> Markdown: https://ui.eneawork.it/blog/agent-skill-struttura.md

*2026-11-01*

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.

Il repository EneUI contiene 3 skill in .agents/skills per 11.996 byte totali, con eneui-blog/SKILL.md lungo 82 righe: verificate il 1 novembre 2026. Il server in backend/mcp.js genera /agent-skill.md dalla lista viva TOOLS di 9 strumenti, cosicché il documento non può citare un tool inesistente. Il catalogo servito conta 111.985 componenti, 1.556 blocchi e 12.808 icone, letti da /api/stats il 1 novembre 2026. Nel dataset docs/keyword-data.json la riga Stack Overflow più vicina al tema agenti riguarda Figma Agent, 45 voti, campionata il 31 ottobre 2026.

## Anatomia minima

## 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

## Il catalogo

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.

## FAQ

### 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.