Agent skills, server MCP o file di regole: quale scegliere

Agent skills, server MCP e file di regole: la risposta breve

Agent skills, server MCP e file di regole mettono tutti le conoscenze a disposizione di un coding agent. La scelta dipende dal tipo di conoscenza. MCP (model context protocol) serve per dati che possono cambiare tra una consultazione e l'altra. Una skill descrive una procedura che si può definire oggi e che resterà valida tra sei settimane. Un file di regole contiene i pochi requisiti che devono essere rispettati in ogni sessione.

Questa scelta ha un costo: il contesto. Ogni token speso per un'istruzione che l'agent non doveva ricevere è un token sottratto al codice che sta leggendo. Inoltre, quel token viene pagato a ogni turno, perché l'intera finestra di contesto viene inviata di nuovo con ogni richiesta. Quindi la domanda utile non è quale meccanismo può svolgere il lavoro. Nella maggior parte dei casi possono farlo tutti e tre. La domanda è quale meccanismo ha il costo più basso mentre resta inutilizzato.

Il costo di ciascun elemento prima dell'utilizzo

I tre elementi vengono caricati in momenti diversi. Questa tempistica determina tutta la differenza.

Un file di regole viene caricato interamente all'avvio, a ogni sessione, indipendentemente dal fatto che sia pertinente. Claude Code legge CLAUDE.md all'inizio di ogni conversazione e lo carica interamente, qualunque sia la sua lunghezza. La destinazione documentata è meno di 200 righe per file, perché un file più lungo consuma più contesto e viene seguito in modo meno affidabile. I due effetti si sommano. Per questo, un file di regole di 900 righe è peggio che inutile.

Una skill viene caricata in due fasi. All'avvio, nel contesto entra solo la riga description del frontmatter SKILL.md di ciascuna skill. Il modello sa così che la skill esiste e quando può essere applicabile, almeno in termini generali. Il corpo viene caricato quando la skill viene invocata. Un documento di riferimento di 400 righe, quindi, ha un costo quasi nullo fino al momento in cui serve.

Un server MCP era l'elemento più costoso. È questo il punto in cui la maggior parte dei confronti che si trovano oggi non è più aggiornata. Nelle versioni correnti di Claude Code, la ricerca degli strumenti è attiva per impostazione predefinita. All'avvio della sessione vengono caricati solo i nomi degli strumenti e il campo instructions del server. Gli schemi JSON completi (JavaScript Object Notation) vengono caricati solo quando Claude li cerca. Aggiungere un server non costa più migliaia di token in anticipo. Un costo rimane, e viene sostenuto interamente in anticipo nelle configurazioni in cui la ricerca degli strumenti è disattivata.

[
  {
    "label": "Rules file, 200 lines",
    "at_startup": "2,500",
    "after_use": "2,500"
  },
  {
    "label": "Skill, 12 KB body",
    "at_startup": 40,
    "after_use": "3,000"
  },
  {
    "label": "MCP server, tool search on",
    "at_startup": 500,
    "after_use": "3,200"
  },
  {
    "label": "MCP server, tool search off",
    "at_startup": "4,500",
    "after_use": "4,500"
  }
]

Sono stime, non misurazioni eseguite sul tuo computer. Derivano dalla dimensione del testo caricato da ciascun meccanismo, considerando circa quattro caratteri per token: un file di regole di 200 righe contiene circa 10 KB di markdown, la descrizione di una skill circa 160 caratteri e un server che espone dodici strumenti include circa 18 KB di schemi e un blocco instructions di 2 KB. Claude Code tronca la descrizione di ogni strumento e il campo instructions di ogni server a 2 KB, quindi questa parte ha un limite massimo. La sezione successiva mostra come leggere i tuoi valori reali.

Leggi insieme le prime due righe. Il file di regole costa 2,500 token in una sessione in cui nessuno ne ha avuto bisogno. Nella stessa sessione, la skill costa 40 token e, nella sessione su dieci in cui viene attivata, 3,000. Le ultime due righe rappresentano due volte lo stesso server, con la ricerca degli strumenti attiva e disattivata: 500 token contro 4,500. Questa differenza spiega perché continuano a circolare i vecchi avvertimenti sull'aumento del contesto causato da MCP.

La ricerca degli strumenti richiede un modello che supporti i blocchi tool_reference. Ad agosto 2026, questo significa Claude Sonnet 4.5, Haiku 4.5, Opus 4.5 e versioni successive. Claude Code la disattiva quando ANTHROPIC_BASE_URL punta a un host non first-party, perché la maggior parte dei proxy non inoltra questi blocchi. Imposta ENABLE_TOOL_SEARCH per controllarla: false carica subito tutti gli schemi, true rimanda il caricamento di tutti gli schemi e auto li carica subito solo quando rientrano nel 10% della finestra di contesto.

# Load schemas up front only if they fit in 5% of the window
ENABLE_TOOL_SEARCH=auto:5 claude

La domanda decisiva è: i dati cambiano tra un'invocazione e l'altra?

Ponila per prima, perché elimina subito una delle opzioni. Se l'agente deve leggere o scrivere qualcosa che può essere diverso la volta successiva in cui lo consulta, serve un server. Un issue tracker, un database, una dashboard di monitoraggio, una propria API interna (application programming interface). Metterlo per iscritto non serve, perché ciò che hai scritto diventa obsoleto non appena qualcun altro modifica il record.

Se la risposta resterebbe corretta tra sei settimane senza che nessuno la aggiorni, serve una skill. Una checklist per il rilascio. Una procedura di migrazione. La struttura delle risposte di errore. Il modo in cui questo repository richiede di scrivere i test. Una skill è un file in git. Non ha una porta, non ha un processo e non ha modalità di errore oltre all'essere errata; un code review può rilevarlo.

Se si tratta di un singolo fatto che deve applicarsi a un lavoro a cui non hai ancora pensato, inseriscilo nel file delle regole. Run make lint before committing. Never push to main. Handlers live in src/api/handlers/. Una riga per ciascun fatto. Nel momento in cui una voce si espande fino a contenere passaggi, non è più un fatto ma una procedura e deve essere spostata in una skill.

Quando è sufficiente un file di regole

I file di regole vengono caricati da più posizioni, dalla più generale alla più specifica: un file di policy gestito, il tuo ~/.claude/CLAUDE.md personale, il ./CLAUDE.md o ./.claude/CLAUDE.md del progetto e un ./CLAUDE.local.md escluso da Git. Tutti i file individuati vengono concatenati invece di sovrascriversi e quelli più vicini alla directory di lavoro vengono letti per ultimi.

Claude Code legge CLAUDE.md, non AGENTS.md. Se il repository contiene già un AGENTS.md per altri strumenti, non mantenerne due copie che finirebbero per divergere.

ln -s AGENTS.md CLAUDE.md

Il link simbolico non stampa nulla se l'operazione riesce. Avvia una sessione, esegui /context e verifica che CLAUDE.md compaia nella sezione Memory files. Se non è elencato, l'agent non lo ha mai visto e nessuna riformulazione sarà utile. Se vuoi aggiungere anche righe specifiche per Claude, usa invece la forma di importazione e inseriscile sotto l'import.

@AGENTS.md

## Claude Code

Use plan mode for changes under `src/billing/`.

Qui esiste una trappola. Gli import @path non riducono il contesto. Il file importato viene espanso e caricato all'avvio insieme al file che lo richiama, fino a quattro livelli di profondità. Suddividere un file di regole di 600 righe in sei import lo organizza per le persone, ma non modifica di nulla il costo in token. Vale la pena leggere le convenzioni alla base di AGENTS.md e del relativo gemello rivolto alle persone prima di scegliere una struttura.

A ridurre il costo è invece .claude/rules/ con un campo paths. Un file di regole che contiene frontmatter paths viene caricato solo quando l'agent accede a un file corrispondente a uno dei pattern.

---
paths:
  - "src/api/**/*.ts"
---

# API rules

- Every endpoint validates its input.
- Use the standard error response shape.

Una regola priva del campo paths viene caricata all'avvio con la stessa priorità di .claude/CLAUDE.md. Il modello operativo è quindi composto da regole brevi e incondizionate, oltre a un elenco paths per tutto ciò che è rilevante soltanto all'interno di una directory.

Quando vuoi una skill

Una skill è una directory che contiene un file SKILL.md. Le skill personali si trovano in ~/.claude/skills/<name>/SKILL.md e si applicano a ogni progetto del computer. Le skill di progetto si trovano in .claude/skills/<name>/SKILL.md, vengono mantenute insieme al repository e possono essere esaminate in una pull request come qualsiasi altro file.

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

---
name: summarize-changes
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.
---

Run `git status` and `git diff` against the merge base.
Group the changes by intent, not by file.
Call out anything touching auth, migrations or deletions.

description è l'unica parte di quel file presente nel contesto prima dell'esecuzione della skill, quindi svolge due funzioni. Indica cosa fa la skill e quando utilizzarla. Una descrizione come "Aiuta con i deploy" non fornisce al modello elementi sufficienti per associare una richiesta, quindi la skill non viene attivata e si può concludere erroneamente che le skill non funzionino.

Il nome della directory diventa il comando, quindi l'esempio precedente produce /summarize-changes. In una skill personale o di progetto, il campo di frontmatter name imposta soltanto l'etichetta visualizzata negli elenchi.

Quando una skill viene invocata, il relativo contenuto renderizzato entra nella conversazione come un singolo messaggio e resta disponibile per il resto della sessione. Claude Code non rilegge il file nei turni successivi. Scrivi istruzioni permanenti anziché passaggi da eseguire una sola volta e mantieni il corpo conciso, perché da quel momento ogni riga rappresenta un costo ricorrente per ogni richiesta. Dopo la compattazione automatica, Claude Code riaggancia l'invocazione più recente di ogni skill, mantenendo i primi 5.000 token di ciascuna entro un budget complessivo di 25.000 token. Se invochi diverse skill di grandi dimensioni nella stessa sessione, quelle meno recenti vengono eliminate completamente. Per questo una skill può sembrare perdere effetto dopo una conversazione lunga. Invocala di nuovo per renderla nuovamente disponibile. Quando la stessa procedura si applica a più codebase, condividi una skill tra più repository anziché copiare il file.

Quando serve un server MCP

Aggiungerne uno richiede un solo comando e il transport ne determina la forma.

# Remote HTTP server
claude mcp add --transport http notion https://mcp.notion.com/mcp

# Remote HTTP server behind a bearer token
claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"

# Local stdio server: everything after -- is passed through untouched
claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
  -- npx -y airtable-mcp-server

Il valore -- è importante. Per un server stdio separa le opzioni di Claude Code dalla riga di comando che avvia il server. Se lo ometti, un --port 8080 destinato al server viene interpretato come un'opzione di claude mcp add, che quindi lo rifiuta.

claude mcp list
claude mcp get notion

claude mcp add conferma con una riga Added ..., che indica soltanto che la configurazione è stata scritta su disco. claude mcp list è il comando che mostra la situazione reale, perché visualizza lo stato di integrità accanto a ogni server: ✔ Connected, ! Needs authentication oppure ✘ Failed to connect. Uno stato di errore indica che Claude Code non ha potuto raggiungere il server, non che il comando per elencare i server non ha funzionato. All'interno di una sessione, /mcp mostra la stessa situazione per ogni server e anche il numero di strumenti.

Ogni chiamata a un server MCP è autonoma e contiene tutto ciò che serve, ed è il motivo per cui un server MCP non ricorda la richiesta precedente. Questa scelta progettuale comporta una conseguenza di cui devi occuparti: qualsiasi stato che debba essere conservato deve risiedere dietro il server, in un database o in un file, e ora devi gestire anche questa risorsa.

Un server MCP è un processo che devi eseguire

Ecco il costo che i confronti tra fornitori omettono. Una skill è un file. Un server MCP è un software che viene eseguito da qualche parte e, quando quel posto è il tuo VPS (virtual private server), sei tu a doverne garantire la disponibilità.

Un server stdio è il caso meno oneroso. Claude Code lo avvia come processo figlio quando inizia la sessione e il processo termina quando termina la sessione. Non c'è nulla da monitorare né da applicare patch secondo una pianificazione propria. Un server HTTP remoto è un servizio a esecuzione prolungata e richiede tutto ciò che serve a un servizio di questo tipo.

[Unit]
Description=Notes MCP server
After=network-online.target
Wants=network-online.target

[Service]
User=mcp
WorkingDirectory=/srv/notes-mcp
ExecStart=/usr/bin/node /srv/notes-mcp/dist/server.js
Environment=PORT=8931
Restart=on-failure
RestartSec=5
NoNewPrivileges=true
PrivateTmp=true

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now notes-mcp
systemctl is-active notes-mcp
journalctl -u notes-mcp -n 50 --no-pager

systemctl is-active dovrebbe restituire active. Se restituisce failed, il journal contiene il motivo. Alla prima esecuzione, la causa è quasi sempre una variabile d'ambiente mancante o una porta già occupata da un altro processo. Qui Restart=on-failure non è facoltativo, perché un server MCP arrestato in modo anomalo non segnala il problema. Te ne accorgi quando l'agente ti comunica che non riesce a leggere il tuo issue tracker.

Associa il processo a 127.0.0.1 e configura davanti a esso un reverse proxy con TLS (transport layer security). Un server MCP che accede al tuo database e risponde su una porta pubblica senza autenticazione equivale a un database che hai pubblicato su Internet. Eseguire un server MCP su un VPS descrive correttamente la configurazione del proxy, del certificato e del firewall.

Poi valuta con obiettività il lavoro ricorrente. Il servizio riceve gli aggiornamenti di sicurezza secondo una pianificazione propria, indipendente dall'agente che lo utilizza. Il suo token OAuth scade e claude mcp list inizia a stampare ! Needs authentication nel momento meno opportuno. Le sue credenziali si trovano in un file di configurazione o in un'intestazione Authorization, quindi richiedono la stessa attenzione di qualsiasi altro secret. È un argomento complesso, trattato separatamente in tenere i secret fuori dalla portata di un agente AI. Una skill non richiede nessuna di queste attività.

Valuta l'alternativa prima di procedere. Se i dati alla base del server proposto cambiano circa una volta a trimestre, una skill che indica all'agente dove cercare e il significato dei campi costa meno di un servizio che devi mantenere continuamente attivo.

Come misurare il costo del proprio contesto

Smettete di fare stime ed eseguite /context all'interno di una sessione. Il comando stampa il dettaglio iniziale: prompt di sistema, file di memoria, strumenti e server MCP, con il peso in token di ciascun elemento.

Controllate due aspetti. In Memory files, verificate che siano elencati tutti i file delle regole previsti. Un file mancante è invisibile all'agente. Per questo è il primo elemento da verificare quando le istruzioni vengono ignorate. Controllate quindi il costo dei server. Se un server che usate due volte al mese è una delle voci più pesanti dell'elenco, disattivatelo in /mcp e riattivatelo nelle sessioni che ne hanno bisogno. La configurazione viene mantenuta in ogni caso.

Un server remoto può anche restituire uno stato come cached 2h ago · connects on first use · 5 tools. Significa che Claude Code ha letto l'elenco degli strumenti da una sessione precedente invece di connettersi all'avvio. La connessione verrà stabilita alla prima chiamata a uno strumento. Gli strumenti sono disponibili dal primo messaggio, quindi non è necessario intervenire. Impostate MCP_DISCOVERY_CACHE=0 se preferite che ogni server si connetta all'avvio. Per una visione più ampia, gestire la finestra di contesto di Claude Code spiega quali elementi rimangono dopo la compattazione, mentre quanto vi costano realmente questi token converte i numeri in denaro.

Perché la mia skill non viene mai attivata?

La causa più comune è il description. È l'unico testo presente nel contesto prima dell'esecuzione della skill. Se non descrive la situazione, non viene trovata alcuna corrispondenza. Inserisci il trigger nella frase: "Use when the user asks what changed, wants a commit message, or asks to review their diff." Le descrizioni vaghe falliscono senza messaggi, quindi il problema può essere difficile da individuare.

La seconda causa è un errore di battitura nel frontmatter, che invece produce un errore evidente. Una chiave sconosciuta viene rifiutata direttamente:

Unexpected key(s) in SKILL.md frontmatter: argument-hint. Allowed properties are: allowed-tools, compatibility, description, license, metadata, name

La terza causa è la posizione. Le skill del progetto vengono caricate da .claude/skills/ nella directory di lavoro e in ogni directory padre fino alla radice del repository. Le skill nelle directory annidate al di sotto della directory da cui hai avviato l'operazione non vengono caricate all'avvio. Diventano disponibili la prima volta che l'agente legge o modifica un file in quella sottodirectory. Fino a quel momento non vengono proposte dal completamento automatico e non possono essere richiamate per nome.

L'equivalente MCP di questo errore silenzioso è una voce .mcp.json con un url e senza type. Claude Code considera qualsiasi voce priva di type un server stdio, quindi ignora la voce e segnala:

MCP server "notes" has a "url" but no "type"; add "type": "http" (or "sse" / "ws") to this entry

Uso combinato dei tre meccanismi

Questi meccanismi non competono per lo stesso spazio. Una configurazione efficace usa ciascuno di essi dove il relativo costo è più basso. Il file delle regole contiene poche righe valide in ogni contesto. Le skill contengono le procedure e vengono caricate solo quando sono applicabili. Un server MCP, occasionalmente due, collega i sistemi i cui contenuti non possono essere previsti in anticipo. Se stai ancora costruendo un modello mentale del primo meccanismo, che cosa sia realmente una agent skill descrive il formato in dettaglio.

Un test consente di risolvere la maggior parte dei dubbi sulla collocazione di un elemento. Eliminalo, avvia una nuova sessione e assegna il compito all'agente. Se l'agente è soltanto più lento, l'elemento apparteneva a una skill. Se l'agente produce con sicurezza una risposta errata, l'elemento apparteneva al file delle regole. Se l'agente non riesce in alcun modo a recuperare le informazioni, era necessario il server; ora serve anche un piano per mantenerlo operativo.

FAQ

Devo scrivere una skill o configurare un server MCP?

Decidilo in base al fatto che le informazioni cambino tra un'invocazione e l'altra. Se l'agente deve leggere uno stato aggiornato che qualcun altro può modificare, ad esempio un issue tracker, un database o una dashboard, serve un server MCP, perché qualsiasi informazione scritta diventa obsoleta non appena cambia il record. Se potessi scrivere la risposta una volta e questa restasse corretta anche tra sei settimane, scrivi una skill. La skill è un file in git: non richiede un processo da eseguire, una porta da esporre o una pianificazione delle patch. Per questo è l'opzione meno costosa, quando è applicabile.

I server MCP continuano a riempire la finestra di contesto?

Molto meno di prima. Nelle versioni attuali di Claude Code, la ricerca degli strumenti è abilitata per impostazione predefinita. All'avvio della sessione vengono caricati solo i nomi degli strumenti e il campo delle istruzioni del server; gli schemi completi vengono recuperati quando Claude li cerca. Il caricamento iniziale avviene ancora quando la ricerca degli strumenti è disabilitata: con ENABLE_TOOL_SEARCH=false, con ANTHROPIC_BASE_URL configurato per usare un proxy che non è first-party oppure con un modello precedente alla generazione Claude 4.5. Esegui /context per verificare in quale situazione ti trovi, perché i numeri riportati nei vecchi articoli comparativi presuppongono il caricamento iniziale.

Claude Code legge AGENTS.md?

No. Claude Code legge CLAUDE.md. Se il repository contiene già un AGENTS.md per altri agenti, indirizza l'uno all'altro invece di mantenere due copie. Esegui ln -s AGENTS.md CLAUDE.md per creare un symlink semplice, oppure inserisci @AGENTS.md nella prima riga di un CLAUDE.md e aggiungi sotto le istruzioni specifiche per Claude. Avvia quindi una sessione ed esegui /context per verificare che CLAUDE.md compaia nella sezione Memory files.

Perché la mia skill ha smesso di avere effetto a metà sessione?

Di solito la causa è l'auto-compattazione. Quando la conversazione viene riepilogata, Claude Code ricollega l'invocazione più recente di ogni skill. Mantiene i primi 5.000 token di ciascuna, entro un budget complessivo di 25.000 token per tutte le skill. Il budget viene utilizzato a partire dalla skill invocata più di recente. Di conseguenza, se hai invocato diverse skill di grandi dimensioni, quelle meno recenti vengono eliminate completamente. Invoca di nuovo la skill per ripristinarne il contenuto completo.

Come posso impedire il caricamento di un file di regole lungo in ogni sessione?

Sposta le parti che servono solo in alcuni casi in file .claude/rules/ con un campo paths nel frontmatter, in modo che ciascun file venga caricato solo quando l'agente accede a un file corrispondente. Suddividere il file in import @path non risolve il problema, perché i file importati vengono espansi e caricati all'avvio insieme al file che li richiama. Tutto ciò che costituisce una procedura a più passaggi, anziché un'informazione permanente, dovrebbe diventare una skill, perché il contenuto di una skill non ha alcun costo finché non viene invocato.