Come addomesticare gli agenti AI con il Skills Toolkit di Matt Pocock

Quando gli sviluppatori iniziano a lavorare a stretto contatto con Claude Code o Codex, si scontrano rapidamente con lo stesso problema. L'agente accetta allegramente il compito, va a scrivere codice per cinque minuti e ritorna con cinquecento righe di spaghetti code. Vi suona familiare? Matt Pocock, l'autore di Total TypeScript, ha deciso di affrontare questo problema con disciplina ingegneristica e ha messo insieme un repository di istruzioni pratiche (skill) per agenti AI. E il progetto vinvcn/mattpocock-skills-zh-CN ha adattato l'intero toolkit per lavorare con modelli linguistici cinesi e contesti misti.

Non si tratta di discussioni astratte sul futuro dello sviluppo. È un insieme di comandi e scenari concreti che fanno sì che il modello linguistico si comporti come uno sviluppatore mid-level o senior ordinato, piuttosto che un generatore casuale di funzioni.

Quattro scenari in cui gli agenti tipicamente falliscono

Matt ha identificato le insidie tipiche in cui gli sviluppatori inciampano quando affidano compiti all'AI, e ha scritto un protocollo di lavoro separato per ogni caso.

L'agente fa qualcosa di completamente diverso da ciò che gli è stato chiesto

L' mal di testa più comune nello sviluppo è chiamato disallineamento delle aspettative. Una persona pensa a un'architettura, il modello riempie i dettagli a proprio gusto. Per colmare questa lacuna, l'autore ha ideato il comando /grill-me (e la sua variante engineering /grill-with-docs).

Prima di toccare qualsiasi codice, l'agente conduce un'interrogazione formale. Pone una serie di domande mirate su casi limite, strutture dati e requisiti dell'interfaccia. Il modello non scriverà una sola riga finché l'albero decisionale non converge. Questo fa risparmiare ore di riscrittura del codice.

Il modello spreca il contesto in chiacchiere inutili

Quando un agente entra in un progetto sconosciuto, inizia a inventare la propria terminologia e a spendere decine di token per spiegare cose ovvie. La soluzione sta nel creare un documento con un vocabolario di dominio unificato (nel progetto si chiama CONTEXT.md).

Il comando /grill-with-docs non vi intervista soltanto, ma registra immediatamente la terminologia del progetto e le decisioni architetturali (ADR). Una volta che voi e l'agente condividete un linguaggio comune, il dialogo si riduce drasticamente, e le variabili nel codice iniziano a essere nominate allo stesso modo in tutti i moduli.

Il codice generato non viene eseguito

Quando un modello scrive codice senza feedback, lavora alla cieca. Ha bisogno di test. La skill /tdd costringe l'agente a seguire rigorosamente il ciclo red-green-refactor. Prima il modello scrive un test unitario che fallisce, poi implementa esattamente quanto codice necessario per far passare il test, e solo dopo pulisce.

Per bug complessi c'è uno scenario separato /diagnosing-bugs. Guida il modello attraverso un protocollo rigoroso: riprodurre l'errore con un test, restringere l'area di ricerca, formulare un'ipotesi, aggiungere logging, correggere il codice ed eseguire un test di regressione.

L'architettura si trasforma in un caos

La velocità di generazione del codice alimenta la crescita dell'entropia. Per impedire che il progetto diventi una grande matassa di spaghetti code, viene utilizzato il comando /improve-codebase-architecture.

Scansiona il progetto, cerca candidati per moduli profondi (con interfacce pubbliche semplici e logica complessa nascosta) e genera un report. In sostanza, è un audit regolare della qualità del codice direttamente nel terminale.

Perché localizzare in cinese

Il repository originale è scritto in inglese, ma la localizzazione di vinvcn ha uno scopo tecnico interessante. Non si tratta solo di convenienza per gli sviluppatori cinesi.

Quando si lavora con LLM asiatici come Qwen o DeepSeek, i prompt di sistema e le istruzioni in cinese riducono la perdita di contesto. Il modello si confonde meno per le sfumature delle formulazioni. Nel frattempo, tutti gli identificatori, i nomi dei comandi, i percorsi dei file e le chiavi di configurazione rimangono in inglese. Niente si rompe quando si eseguono gli script.

Come funziona l'architettura delle skill

Tutte le skill nel repository rientrano in due categorie:

1. Comandi invocati dall'utente. Solo gli esseri umani li attivano manualmente tramite slash. Ad esempio, /ask-matt aiuta a selezionare la skill giusta per il compito corrente, /to-spec compila la discussione in un ticket e /wayfinder pianifica una funzionalità importante diverse sessioni avanti.
2. Skill invocate dal modello. Sia l'utente che l'agente possono attivarle di propria iniziativa quando vedono un sottocompito adatto. Queste includono il ciclo TDD, la risoluzione dei conflitti git senza aborti bruschi, la code review e la stesura di documenti.

Le skill sono scritte come semplici file Markdown con istruzioni. Sono facili da leggere e possono essere modificate per adattarle alle regole del vostro team.

Configurazione in un paio di minuti

Potete aggiungere le skill al vostro progetto usando l'installer skills.sh:

npx skills@latest add vinvcn/mattpocock-skills-zh-CN

L'utility vi chiederà quali skill volete copiare e quali directory degli agenti registrare. Assicuratevi di selezionare /setup-matt-pocock-skills.

Dopo l'installazione, eseguite la configurazione iniziale direttamente nel dialogo con l'agente:

/setup-matt-pocock-skills

L'agente chiarirà dove tracciate i task (GitHub Issues, Linear o file locali), quali etichette usate per il triage e quale cartella utilizzare per archiviare la documentazione architetturale.

Se state lavorando in Claude Code e non volete memorizzare copie dei file in ogni repository, potete collegare le skill come plugin:

claude plugin marketplace add vinvcn/mattpocock-skills-zh-CN
claude plugin install mattpocock-skills@mattpocock

In questa modalità, le skill si aggiorneranno centralmente quando verranno rilasciate nuove versioni.

A chi è destinato

Due categorie di ingegneri dovrebbero dare un'occhiata a questo repository.

Innanzitutto, chi usa attivamente Claude Code, Codex o OpenCodeInterpreter ed è stanco di combattere con le allucinazioni del modello. L'approccio di Matt Pocock riporta la prevedibilità nello sviluppo attraverso vincoli rigorosi e cicli di feedback brevi.

In secondo luogo, è un ottimo esempio di come scrivere istruzioni di sistema per assistenti AI. Anche se non avete bisogno della traduzione cinese, la struttura dei file in questo repository offre una lezione chiara sulla progettazione di skill per agenti. Provate a incorporare un paio di comandi come /grill-me nel vostro workflow quotidiano, e noterete la differenza già alla sera.