Come trasformare un'attività ripetitiva in una skill riutilizzabile per il tuo agente IA di coding

Se continui a incollare la stessa checklist nel tuo agente IA di coding — "scrivi un conventional commit, poi esegui i test, poi aggiorna il changelog" — stai facendo un lavoro che l'agente potrebbe ricordare al posto tuo. La maggior parte degli agenti moderni ti permette di racchiudere una procedura ricorrente in un file piccolo e riutilizzabile. In Claude Code questi si chiamano skill; lo stesso file alimenta anche slash command come /deploy. Questa guida ti accompagna nella creazione di una skill da zero, poi spiega i principi che valgono anche per altri strumenti.

Cos'è una skill

Una skill è una cartella con un unico file SKILL.md al suo interno. Quel file ha due parti: il frontmatter YAML che indica all'agente quando usare la skill, e un corpo in markdown con le istruzioni che segue quando la skill viene eseguita. Il vantaggio chiave rispetto allo stipare tutto in un file CLAUDE.md (o AGENTS.md) è la divulgazione progressiva: il corpo si carica solo quando la skill viene effettivamente invocata, perciò un lungo materiale di riferimento costa quasi nulla finché non ti serve.

Invochi una skill in due modi: direttamente, digitando /skill-name, oppure automaticamente — l'agente legge la tua richiesta, la confronta con la description della skill e la carica se è pertinente.

Dove risiedono le skill

Dove metti la cartella decide chi può usarla. In Claude Code, secondo la documentazione ufficiale:

• ~/.claude/skills/<name>/SKILL.md — personale, disponibile in tutti i tuoi progetti.
• .claude/skills/<name>/SKILL.md — di progetto, committata nel repository in modo che tutti nel team ottengano lo stesso comando.

Il nome della cartella diventa il comando. Una cartella chiamata summarize-changes ti dà /summarize-changes.

Un esempio concreto

Costruiamo una skill che riassume le tue modifiche non committate e segnala qualunque cosa rischiosa prima che tu faccia il commit. Crea la directory:

mkdir -p ~/.claude/skills/summarize-changes

Poi salva questo come ~/.claude/skills/summarize-changes/SKILL.md:

---
description: Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed, wants a commit message, or asks to review their diff.
---

## Current changes

!`git diff HEAD`

## Instructions

Summarize the changes above in two or three bullet points, then list any
risks you notice such as missing error handling, hardcoded values, or tests
that need updating. If the diff is empty, say there are no uncommitted changes.

Due elementi fanno funzionare tutto questo. Primo, la description è scritta per l'agente, non per te — nomina i trigger ("what changed", "wants a commit message", "review their diff") così che l'agente sappia quando ricorrervi. Secondo, la riga !`git diff HEAD` è un'iniezione dinamica di contesto: Claude Code esegue quel comando e incolla il suo output nel prompt prima che l'agente legga la skill. Le istruzioni arrivano con il tuo diff reale già inserito, perciò la risposta è ancorata al tuo vero working tree invece che a delle ipotesi.

Fai una piccola modifica a un file qualsiasi, avvia il tuo agente e provala in entrambi i modi — chiedi "cosa ho modificato?" per attivarla automaticamente, oppure digita /summarize-changes per eseguirla direttamente.

Passare argomenti

Le skill possono ricevere input. Un segnaposto $ARGUMENTS nel corpo viene sostituito da qualunque cosa digiti dopo il comando, e le varianti indicizzate ($0, $1) catturano parole specifiche. Una skill invocata come /fix-issue 4821 può fare riferimento direttamente al numero dell'issue, così un solo file gestisce ogni issue invece di averne uno per ticket.

Cinque principi per skill che reggono nel tempo

Questi valgono che tu stia scrivendo una skill di Claude Code, un comando di Cursor o — a partire dalla funzionalità Record & Replay di OpenAI del giugno 2026 — modificando un'automazione che l'agente ha registrato per te:

1. Scrivi la description per il modello. Anteponi frasi di trigger concrete. Una description vaga significa che l'agente non carica mai automaticamente la skill, e ti ritrovi a digitare / e a dover ricordare i nomi.
2. Limita ogni skill a un solo compito. Una skill che fa il deploy e esegue le migrazioni e pubblica su Slack è difficile da fidarsi e ancora più difficile da debuggare. Skill piccole e a scopo unico si compongono meglio.
3. Inietta contesto in tempo reale invece di descriverlo. Inserire un diff reale, il risultato di un test o l'elenco di un file è meglio che dire all'agente "controlla lo stato attuale" — elimina un passaggio in cui l'agente può sbagliare l'ipotesi.
4. Metti un controllo su tutto ciò che ha effetti collaterali. Per le skill che fanno deploy, migrazioni o cancellazioni, richiedi un'invocazione esplicita invece di lasciare che l'agente le esegua automaticamente. Vuoi una persona nel processo prima di azioni irreversibili.
5. Committa le skill di team nel repository. Mettere le skill di progetto in .claude/skills/ e committarle significa che ogni sviluppatore — e ogni esecuzione dell'agente in CI — segue la stessa procedura. Le tue convenzioni smettono di vivere nella testa di una sola persona.

Quando ricorrere a una skill

La regola pratica: nel momento in cui incolli le stesse istruzioni a più passaggi per la terza volta, oppure una sezione del tuo CLAUDE.md si trasforma da fatto in procedura, spostala in una skill. Ottieni un comando riutilizzabile, il tuo file di contesto resta snello e le istruzioni si caricano solo quando servono davvero — il che mantiene sia te sia l'agente concentrati sul compito che avete davanti.