Estendere l'agente: skills, hooks e MCP 🔌

Ogni agente di coding ha una capacità base: leggere file, eseguire comandi, cercare nel codice. Ma i progetti reali richiedono di più: collegarsi a un issue tracker, interrogare un database, eseguire verifiche di sicurezza automatiche. Skills, hooks e MCP sono i tre modi per estendere l’agente. Il rischio è gonfiare il contesto con troppe estensioni, trasformando uno strumento snello in un litter che consuma token senza aggiungere valore.

Più estensioni attivi, più contesto consumi. Più contesto consumi, meno il modello capisce.

I tre meccanismi di estensione 🔧

Skills 🧩

Uno skill è un file SKILL.md con istruzioni specializzate che l’agente carica quando rileva un task pertinente. È il meccanismo più leggero: nessun overhead di rete, nessun server da avviare.

Struttura tipica:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

---
name: security-audit
description: Esegui audit di sicurezza sul codice
globs: ["*.go", "*.ts"]
alwaysApply: false
---
## Istruzioni
1. Scansiona per hardcoded secrets
2. Verifica pattern OWASP
3. Genera report tabellare

Quando usarli:

• Regole di progetto specifiche (stile, pattern, convenzioni)
• Workflow ricorrenti (audit, generazione, deployment)
• Knowledge base che l’agente deve consultare

Quando evitarli:

• Istruzioni generiche che appartengono ad AGENTS.md
• Skill che richiedono accesso a risorse esterne (usa MCP)
• Più di 5-6 skill attivi contemporaneamente

Hooks deterministici ⚙️

Gli hook sono callback che si eseguono prima o dopo le azioni dell’agente. Sono deterministici: non dipendono dal modello, ma da logica codificata. Sono il meccanismo di sicurezza più affidabile.

Esempio: hook PreToolUse che blocca git push

1
2
3
4
5

{
  "hook": "PreToolUse",
  "matcher": "bash",
  "command": "echo \"$INPUT\" | grep -q 'git push' && echo 'BLOCKED: git push requires manual approval' && exit 1"
}

Ciclo di vita degli hook:

Quando usarli:

• Bloccare operazioni che non devono mai essere automatizzate (git push, deploy, delete)
• Iniettare regole di minimal diff
• Loggare tutte le azioni dell’agente per audit trail

Quando evitarli:

• Logica che dipende dal contesto del modello (usa skill)
• Hook che richiedono accesso a reti esterne (usa MCP)

MCP (Model Context Protocol) 🌐

MCP è lo standard aperto per connettere l’agente a sorgenti dati ed ecosistemi esterni. È il meccanismo più potente e più pesante: ogni server MCP aggiunge overhead al contesto (500-1000 token per tool esposto).

Cosa può fare MCP:

• Interrogare database SQL/NoSQL
• Leggere/scrivere issue su Jira, GitHub Issues
• Accedere a documentazione interna (Confluence, Notion)
• Esecutare test end-to-end su browser headless
• Integrare servizi cloud (AWS, GCP, Azure)

Esempio di configurazione:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "..." }
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": { "DATABASE_URL": "..." }
    }
  }
}

Regola d’oro: 3-5 server attivi. Ogni server aggiunge tool alla disponibilità dell’agente, ma ogni tool consuma token nel contesto. Con 10 server MCP attivi, l’agente ha così tanti tool disponibili che il modello fatica a scegliere quello giusto.

Tabella comparativa 📊

Come scegliere il meccanismo giusto 🧠

    flowchart TD
    A[Hai bisogno di estendere l'agente] --> B{Servono risorse esterne?}
    B --> Sì --> C[MCP]
    B --> No --> D{Deve essere deterministico?}
    D --> Sì --> E[Hook]
    D --> No --> F[Hai istruzioni specializzate?}
    F --> Sì --> G[Skill]
    F --> No --> H[Usa AGENTS.md]
  

Anti-pattern 🚫

• Troppi MCP server — 10+ server attivi = contesto saturo, scelte confuse, token sprecati. Mantieni 3-5 server.
• Skill duplicati — non creare uno skill per cosa che già fa AGENTS.md. Unificare.
• Hook hardcoded — non mettere logica condizionale negli hook. Se dipende dal contesto, è uno skill.
• MCP per tutto — non usare MCP per operazioni locali. Se il file è nel repository, leggilo direttamente.
• Sicurezza trascurata — ogni server MCP è una superficie di attacco. Valida, pinner le versioni, limita i permessi.

Sicurezza delle estensioni 🔒

Ogni estensione che aggiungi all’agente è una potenziale superficie di attacco. OWASP LLM05 e LLM06 classificano le vulnerabilità della supply chain e l’agenzia eccessiva come rischi critici.

Checklist sicurezza:

• Server MCP da fonti verificate (npm ufficiale, GitHub ufficiale)
• Versioni pinnate (niente latest in produzione)
• Permessi minimi (sola lettura dove possibile)
• Nessun secret nel codice sorgente degli hook
• Audit periodico delle estensioni installate
• .ignore che esclude file sensibili dalla sessione

Verifica periodica 🔄

Gli standard evolvono rapidamente. AGENTS.md, skills e MCP cambiano frequentemente. Programma una verifica semestrale di:

• Aggiornamenti alle specifiche MCP
• Nuove funzionalità di hook nel tuo tool
• Skill obsoleti da rimuovere
• Server MCP compromessi o deprecati

Riferimenti della serie 📚

• Configuring the repository — AGENTS.md, .ignore, configurazione base
• Sicurezza e audit del codice — sicurezza delle integrazioni MCP
• Surviving sessions — gestione del contesto e compattazione