Come Aggiungere Flag ai Comandi Slash di Claude Code: 4 Schemi che Funzionano Davvero

Come Aggiungere Flag ai Comandi Slash di Claude Code: 4 Schemi che Funzionano Davvero

Claude Code non interpreta i --flag come ti aspetteresti per i comandi slash personalizzati — ma quattro schemi ti danno la stessa UX, e tre di essi sono più puliti di qualsiasi parser CLI. Ecco come aggiungere flag ai comandi slash di Claude Code correttamente, con file .md funzionanti che puoi copiare oggi.

Risposta rapida:

• Claude Code non interpreta i flag CLI (--json, --verbose) per i comandi personalizzati — il sistema non ha un parser di flag.
• Per una UX stile CLI, scrivi i flag in $ARGUMENTS e lascia che il modello li interpreti come linguaggio naturale.
• Per argomenti tipizzati, usa $1/$2 posizionali o argomenti nominati dichiarati nel campo arguments: del frontmatter.
• Documenta i flag attesi in argument-hint: così l'autocompletamento / li mostra all'utente.

Come Funzionano Davvero gli Argomenti dei Comandi Slash di Claude Code?

Il sistema di Claude Code sostituisce tre tipi di token prima di inviare il comando al modello: $ARGUMENTS (l'intera stringa dopo il nome del comando), $0/$1/$2 posizionali (segmenti separati da spazio, come nella shell), e $nomeVariabile nominati dichiarati nel frontmatter. Non esiste un parser di flag CLI integrato — --dry-run arriva in $ARGUMENTS come testo letterale.

Ecco il punto che fa inciampare tutti. Quando scrivi /deploy --staging --dry-run, Claude Code non esegue argparse su --staging --dry-run. Il sistema incolla quella stringa completa ovunque il tuo file .md referenzia $ARGUMENTS, poi invia il prompt renderizzato al modello. Il modello vede --staging --dry-run come testo normale e decide cosa fare.

Non è un bug — è il design. Il sistema è un livello di sostituzione, non un parser. I comandi integrati come /clear e /help (vedi il riferimento CLI ufficiale) hanno flag propri, ma i comandi personalizzati che scrivi seguono regole diverse.

Il sistema di Claude Code sostituisce i token, poi consegna il prompt renderizzato al modello. Non esiste un parser di flag.

Nel nostro lavoro con Claude Code, la confusione più comune è esattamente questa — gli sviluppatori passano un'ora a capire perché --verbose "non viene rilevato" prima di rendersi conto che il modello è il parser. A partire da Claude Code v2.1.126 (maggio 2026), questo comportamento è documentato nella documentazione ufficiale sui comandi slash e non cambierà presto. I comandi slash sono un primitivo parallelo agli hook di Claude Code — entrambi estendono il sistema, ma i comandi si attivano sull'input dell'utente mentre gli hook si attivano sugli eventi degli strumenti.

Ecco il comando personalizzato più piccolo possibile che dimostra il modello di sostituzione:

---
description: Echo di tutto ciò che l'utente scrive dopo il comando
argument-hint: [qualsiasi cosa]
---

L'utente ha passato questi argomenti: $ARGUMENTS

Ripetili verbatim, poi descrivi cosa probabilmente intendeva l'utente.

Salvalo come .claude/commands/echo-args.md, scrivi /echo-args hello world --foo, e il modello vedrà la stringa letterale hello world --foo sostituita nel prompt. È tutto il modello mentale. Per una spiegazione più approfondita di come i file di comando si relazionano al sistema di skill, vedi il nostro tutorial sulle skill.

Crea il Tuo Primo Comando Slash Parametrico in 5 Minuti

Crea .claude/commands/greet.md con tre righe di frontmatter e una riga di prompt che referenzia $ARGUMENTS. Riavvia Claude Code, scrivi /greet Mondo, e guarda Mondo sostituirsi nel prompt prima che il modello lo veda. Questa è tutta la cerimonia — cinque passi, nessuno strumento di build.

Ecco la ricetta dall'inizio alla fine:

1. Crea la directory. Dalla radice del tuo progetto, esegui mkdir -p .claude/commands. La cartella .claude/ vive accanto al tuo codice; i comandi al suo interno vengono scoperti automaticamente all'avvio di Claude Code.
2. Scrivi il file di comando. Salva lo snippet qui sotto come .claude/commands/greet.md.
3. Ricarica la sessione. Esci e rilancia Claude Code (o esegui /reload se la tua versione lo supporta). I comandi vengono letti una volta all'avvio della sessione.
4. Invocalo. Scrivi /greet Mondo nella chat.
5. Verifica la sostituzione. Apri la trascrizione e conferma che il modello ha visto Mondo interpolato nel corpo del prompt, non il token letterale $ARGUMENTS.

Ecco il file completo:

---
description: Saluta qualcuno con entusiasmo
argument-hint: <nome>
---

Sei un assistente amichevole. Saluta la persona di nome "$ARGUMENTS" con una frase breve e calorosa. Poi chiedile su cosa sta lavorando oggi.

E l'interazione nel terminale:

> /greet Mondo
Ciao Mondo, che bello vederti! Su cosa stai lavorando oggi?

Fatto. Hai un comando slash parametrico. Il campo argument-hint è ciò che fa sì che il menu di autocompletamento / mostri <nome> accanto al tuo comando — piccolo dettaglio UX, grande impatto.

Se $ARGUMENTS non si sostituisce, 9 volte su 10 è perché hai scritto $args o $ARGS — il token è letteralmente in maiuscolo.

Il token è case-sensitive ed esatto. $ARGUMENTS funziona. $arguments, $args, $ARGS, ${ARGUMENTS} falliscono silenziosamente — vengono inviati al modello come testo letterale e il modello vede solo spazzatura. Controlla tre volte l'ortografia prima di supporre un bug più profondo.

Quali Campi del Frontmatter Controllano la Gestione degli Argomenti?

Cinque campi del frontmatter determinano come un comando slash gestisce gli argomenti: argument-hint (cosa mostra l'autocompletamento), allowed-tools (cosa può chiamare il comando), arguments (dichiarazione degli argomenti nominati), model (quale variante di Claude lo esegue), e disable-model-invocation (blocca il comando all'invocazione solo da parte dell'utente). Insieme coprono praticamente tutti i pattern parametrici di cui avrai bisogno.

Ecco il riferimento completo al frontmatter per i comandi personalizzati di Claude Code v2.1.x:

Due insidie da tenere a mente. Prima, allowed-tools è separato da spazi, non da virgole. Scrivere Bash(git:*), Read, Edit non aggiunge nulla alla whitelist silenziosamente — il parser tratta l'intera stringa come una singola voce malformata. Usa Bash(git:*) Read Edit. Lo abbiamo imparato a nostre spese; per altri pattern simili, vedi le nostre best practice per CLAUDE.md sulle convenzioni dei file di configurazione.

Secondo, il campo model: sovrascrive qualsiasi modello che l'utente ha selezionato per la sessione. Utile quando un comando è computazionalmente economico e vuoi forzarlo su una variante più piccola — vedi la nostra guida sulla selezione del modello per scegliere tra Opus 4.7 e Sonnet per diversi tipi di comandi.

Il campo disable-model-invocation: true è la tua rete di sicurezza per i comandi distruttivi. Impostalo su /deploy-prod o /drop-database e altri agenti non potranno chiamare quei comandi in modo programmatico — solo un essere umano che digita nella chat può attivarli.

Quali Sono i 4 Schemi di Argomenti che Userai Davvero?

Quattro schemi coprono circa il 95% dei comandi slash reali di Claude Code: (1) flag booleano come /deploy --dry-run interpretato dal modello da $ARGUMENTS, (2) flag con valore come /test --filter auth estratto da $ARGUMENTS, (3) posizionale obbligatorio + flag opzionale come /fix-issue 123 --priority high che mescola $1 e $ARGUMENTS, e (4) posizionale strettamente tipizzato come /migrate-component SearchBar React Vue che usa $0/$1/$2.

Scegli quello che si adatta alla forma del tuo comando. Ecco un file .md funzionante per ciascuno.

Schema 1: Flag Booleano (--dry-run)

Quando vuoi una UX stile flag CLI e il flag è semplicemente on/off, lascia che il modello lo rilevi all'interno di $ARGUMENTS. Nessuna logica di parsing, nessun giocolamento con i posizionali — descrivi semplicemente la regola nel prompt.

---
description: Deploy in staging o produzione
argument-hint: [--dry-run]
allowed-tools: Bash(git:*) Bash(npm:*) Read
---

Esegui il deploy del branch corrente in staging.

Argomenti passati: $ARGUMENTS

Se "$ARGUMENTS" contiene "--dry-run", NON eseguire il deploy. Invece, stampa il piano di deployment: quali file cambierebbero, quali variabili d'ambiente verrebbero impostate, e quali comandi verrebbero eseguiti. Fermati dopo aver stampato il piano.

Altrimenti, procedi con il deployment reale usando `git push staging main` e `npm run deploy:staging`.

Scrivi /deploy --dry-run e il modello vede il flag, stampa il piano e si ferma. Scrivi /deploy e spedisce. Il sistema non ha fatto nessun parsing — il modello ha fatto tutto il lavoro, che è esattamente ciò in cui è bravo.

Schema 2: Flag con Valore (--filter <pattern>)

Stessa idea, ma ora il flag porta un valore. Il modello legge --filter auth da $ARGUMENTS e usa la sottostringa che lo segue.

---
description: Esegui la suite di test, opzionalmente filtrata
argument-hint: [--filter <pattern>]
allowed-tools: Bash(npm:*) Read
---

Esegui la suite di test del progetto.

Argomenti: $ARGUMENTS

Se "$ARGUMENTS" contiene "--filter <pattern>", esegui solo i test che corrispondono a <pattern>. Usa `npm test -- --grep <pattern>` per il comando effettivo.

Se non è presente `--filter`, esegui la suite completa con `npm test`.

Riporta il conteggio dei test superati/falliti alla fine.

/test --filter auth esegue solo i test di autenticazione. /test esegue tutto. Il modello estrae il pattern dopo --filter in modo affidabile perché Claude è genuinamente bravo in questo tipo di estrazione da testo strutturato — molto più affidabile di quanto ci si aspetti.

Schema 3: Posizionale Obbligatorio + Flag Opzionale

Questo è l'ibrido che usiamo di più nella nostra libreria di comandi. $1 porta l'argomento obbligatorio, $ARGUMENTS porta tutto (così il modello può ancora individuare i flag opzionali). È il mix più pulito quando un argomento è irrinunciabile e il resto è contesto libero.

---
description: Risolvi una issue di GitHub
argument-hint: <numero-issue> [--priority high|medium|low] [contesto...]
allowed-tools: Bash(gh:*) Bash(git:*) Read Edit
---

Risolvi la issue GitHub #$1.

Argomenti completi: $ARGUMENTS

Passi:
1. Esegui `gh issue view $1` per caricare il corpo della issue.
2. Leggi il codebase per individuare i file rilevanti.
3. Se "$ARGUMENTS" contiene "--priority high", crea un branch hotfix da main. Altrimenti crea il branch da develop.
4. Applica la correzione, esegui i test e apri una PR collegata alla issue.

Qualsiasi altra cosa in $ARGUMENTS dopo il numero della issue è contesto libero — incorporalo nella tua comprensione del bug.

Invoca come /fix-issue 1234 --priority high il form di login cancella il campo email dopo un tentativo fallito. $1 si risolve in 1234. $ARGUMENTS si risolve nell'intera stringa finale, che il modello interpreta con piacere sia per il flag di priorità che per la descrizione libera.

Usiamo esattamente questo mix $1 + $ARGUMENTS nel nostro comando /fix-issue — $1 per il numero della issue, il resto per il contesto libero che il modello interpreta. È stato lo schema con il miglior ROI in un anno di uso quotidiano di Claude Code.

Schema 4: Posizionale Stretto (Tipizzato)

Quando ogni argomento è obbligatorio e l'ordine conta, elimina $ARGUMENTS. Usa $0/$1/$2 (o argomenti nominati tramite il campo arguments: del frontmatter) per slot tipizzati senza ambiguità.

---
description: Migra un componente tra framework
argument-hint: <componente> <framework-origine> <framework-destinazione>
arguments: [component, fromFramework, toFramework]
allowed-tools: Read Edit Write
---

Migra il componente chiamato "$component" da $fromFramework a $toFramework.

1. Leggi il file del componente esistente (cerca `$component.{jsx,tsx,vue,svelte}`).
2. Traduci gli idiomi del componente da $fromFramework a $toFramework: metodi del ciclo di vita, gestione dello stato, sintassi delle prop, binding degli eventi.
3. Scrivi il nuovo file con l'estensione corretta per $toFramework.
4. Stampa un riepilogo del diff alla fine.

Se $fromFramework o $toFramework non è supportato, interrompi e indica all'utente quali framework SONO supportati (React, Vue, Svelte, Solid).

Invoca come /migrate-component SearchBar React Vue. La dichiarazione degli argomenti nominati rende l'autocompletamento e il corpo del prompt auto-documentanti — chiunque legga migrate-component.md può capire immediatamente quale slot è quale. Questo schema brilla per i comandi con tre o più argomenti obbligatori. Puoi vedere questo stile anche nelle librerie della community come wshobson/commands su GitHub.

I flag booleani e con valore funzionano perché il modello è un parser flessibile. Il posizionale stretto funziona perché non è richiesta nessuna intelligenza del modello. Mescolare i due è il segreto.

Quando Usare $ARGUMENTS vs Posizionale vs Nominato?

Usa $ARGUMENTS quando gli argomenti sono in stile flag CLI e vuoi il parsing flessibile del modello. Usa $1/$2 posizionali quando gli argomenti sono tipizzati, ordinati e vuoi zero ambiguità. Usa arguments: nominati quando ci sono 3+ argomenti e la chiarezza nell'autocompletamento conta più della brevità. Ecco la matrice decisionale:

L'istinto della maggior parte degli sviluppatori è di usare $ARGUMENTS per primo perché si sente più vicino al mondo bash che conoscono. Va bene per i prototipi, ma il posizionale tipizzato è genuinamente migliore quando il contratto è stabile. Il modello non ha bisogno di interpretare $1 — è già una stringa pulita.

Una regola empirica approssimativa: se puoi descrivere la firma del comando in un'unica frase in italiano senza usare le parole "o" e "opzionalmente", vai col posizionale. Se hai bisogno di quelle parole, usa $ARGUMENTS.

I Comandi Slash Sono la Stessa Cosa delle Skill Adesso?

Anthropic ha unito i comandi personalizzati nel sistema di skill più ampio nella primavera del 2026, ma i file .claude/commands/*.md funzionano ancora e usano lo stesso frontmatter. Una skill è una directory (.claude/skills/foo/SKILL.md più file di supporto) con controllo di invocazione aggiuntivo come disable-model-invocation. Un comando è un singolo file .md. Stesse regole di sostituzione, packaging diverso.

Ecco la differenza pratica:

Quindi no, .claude/commands/ non è deprecato. Anthropic ha esplicitamente mantenuto il formato file funzionante quando ha unito i sistemi — troppi progetti hanno librerie di comandi fissate nel controllo versione. Se vuoi file di supporto (come un riferimento CONTRIBUTING.md che la tua skill carica, o un template.json che copia), usa le skill. Altrimenti rimani con i comandi.

L'unione fa parte di una spinta più ampia verso lo standard aperto agentskills.io, ed è uno dei cambiamenti degni di nota della v2.1.x — vedi il nostro riepilogo delle funzionalità di Claude Code v2.1 per il panorama completo e il nostro tutorial sulle skill per una guida più approfondita.

Perché $ARGUMENTS Non Si Sostituisce? Bug Comuni Risolti

Cinque motivi comuni per cui $ARGUMENTS non si sostituisce: (1) token in minuscolo o abbreviato ($args, $ARGS, $arguments — deve essere letteralmente $ARGUMENTS), (2) argomenti multi-parola non quotati (/cmd hello world divide; /cmd "hello world" li tiene insieme), (3) allowed-tools separato da virgole invece di spazi, (4) file di comando non in .claude/commands/ o .claude/skills/, (5) la sessione di Claude Code va riavviata dopo aver modificato il file.

$ARGUMENTS Appare Letteralmente nel Prompt del Modello

Sintomo: Il tuo prompt mostra $ARGUMENTS come testo normale nella risposta del modello, come se il sistema lo avesse ignorato. Causa: Case errato o ortografia sbagliata. Il token è letteralmente $ARGUMENTS — otto caratteri, tutti maiuscoli. Correzione: Apri il .md, cerca $args, $ARGS, $arguments, ${ARGUMENTS}, sostituisci con $ARGUMENTS. Il bug del typo $args ha colpito ogni sviluppatore nel nostro team almeno una volta; è il bug con il volume più alto nella famiglia "comando slash sconosciuto".

L'Argomento Multi-Parola Si Divide Inaspettatamente

Sintomo: Hai eseguito /migrate-component Search Bar React Vue e $1 è Search, $2 è Bar. Causa: Gli spazi dividono gli argomenti posizionali. Correzione: Quota l'argomento multi-parola: /migrate-component "Search Bar" React Vue. Ora $1 è Search Bar. Questo corrisponde al comportamento della shell, che è il modello mentale che il sistema deliberatamente rispecchia.

allowed-tools Non Viene Rispettato

Sintomo: Il comando gira ma Claude si rifiuta di chiamare strumenti che pensavi di aver messo in whitelist, o chiama strumenti che non hai elencato. Causa: Separato da virgole invece di spazi. Correzione: Cambia allowed-tools: Bash, Read, Edit in allowed-tools: Bash Read Edit. Per i sub-pattern degli strumenti, formatta come Bash(git:*) Bash(npm:*) Read.

Il Comando Non Appare nell'Autocompletamento /

Sintomo: Scrivi / e il tuo comando non è nella lista. Causa: Posizione del file, frontmatter mancante, o disable-model-invocation impostato in modo errato. Correzione: Conferma che il file si trova in .claude/commands/tuocmd.md (o .claude/skills/tuocmd/SKILL.md) relativo alla radice del progetto. Conferma che il frontmatter ha almeno un campo description:. Se hai impostato disable-model-invocation: true, il comando non sarà visibile agli altri agenti ma apparirà ancora nel menu / digitato dall'utente.

Hai Modificato il File .md ma Niente è Cambiato

Sintomo: Hai corretto il bug, salvato il file, eseguito di nuovo il comando, stesso comportamento rotto. Causa: Claude Code mette in cache i file di comando all'avvio della sessione. Correzione: Esci e rilancia Claude Code, o esegui /reload se la tua versione lo supporta.

Claude Code legge i file .md all'avvio della sessione. Se modifichi un comando e "non cambia", riavvia la sessione prima di supporre un bug più profondo.

Per i casi limite oltre questi cinque, le issue del repository di Claude Code sono il posto migliore dove cercare. La maggior parte dei bug di sostituzione strani che abbiamo visto sono qualche variante di uno dei casi sopra.

FAQ: Argomenti dei Comandi Slash di Claude Code

Come si passano argomenti a un comando slash di Claude Code?

Scrivi la stringa dell'argomento dopo il nome del comando: /greet Mondo. All'interno del file .md del tuo comando, referenzia il valore come $ARGUMENTS (l'intera stringa), $1 (primo posizionale), o $nomeVariabile (se hai dichiarato arguments: [nomeVariabile] nel frontmatter). Il sistema sostituisce il token prima di inviare il prompt al modello.

Cos'è $ARGUMENTS in Claude Code?

$ARGUMENTS è un token di sostituzione nei file di comando slash personalizzati che il sistema di Claude Code sostituisce con l'intera stringa di argomenti che l'utente ha digitato dopo il nome del comando. Se un utente esegue /deploy --staging --dry-run, allora $ARGUMENTS diventa la stringa letterale --staging --dry-run nel prompt renderizzato, prima che il modello lo veda.

I comandi slash di Claude Code possono accettare flag stile CLI come --json?

Non nativamente — il sistema non ha un parser di flag per i comandi personalizzati. Scrivi --json in $ARGUMENTS, e il tuo prompt istruisce il modello a rilevarlo e comportarsi di conseguenza. Funziona perché Claude è un parser flessibile di testo strutturato. I comandi integrati come /clear e /help hanno flag reali, ma i comandi personalizzati che scrivi seguono regole di sola sostituzione.

Qual è la differenza tra $1, $ARGUMENTS e $nome in Claude Code?

$1 è il primo argomento posizionale separato da spazio ($2 è il secondo, e così via). $ARGUMENTS è l'intera stringa di argomenti verbatim, inclusi tutti i pezzi posizionali e qualsiasi flag. $nome è un argomento nominato dichiarato nel campo arguments: [nome] del frontmatter — utile quando vuoi slot posizionali auto-documentanti senza indicizzazione numerica.

Come funziona argument-hint in Claude Code?

argument-hint è un campo del frontmatter che controlla cosa il menu di autocompletamento / mostra accanto al nome del tuo comando. Impostare argument-hint: <numero-issue> [--priority high] mostra esattamente quel template dopo che l'utente scrive /. È solo UX — non valida né interpreta gli argomenti. Vale comunque la pena impostarlo perché è la documentazione più economica che scriverai mai.

Come si crea un comando slash personalizzato con argomenti multipli?

Due opzioni pulite. Per i posizionali: referenzia $1, $2, $3 nel corpo del prompt. Per i nominati: dichiara arguments: [primo, secondo, terzo] nel frontmatter e referenzia $primo, $secondo, $terzo. Il nominato è più leggibile per tre o più argomenti. Usa $ARGUMENTS solo quando vuoi che il modello interpreti una stringa finale a forma libera dopo gli slot posizionali obbligatori.

.claude/commands/ è deprecato in favore di .claude/skills/?

No. Anthropic ha unito i due sistemi nella primavera del 2026 ma ha esplicitamente mantenuto .claude/commands/*.md funzionante con regole di sostituzione identiche. Usa i comandi per automazioni a file singolo e le skill per bundle multi-file (SKILL.md più template o riferimenti). Stesso frontmatter, stesso comportamento di $ARGUMENTS, packaging diverso. Entrambi sono di prima classe a partire dalla v2.1.126.

Perché $ARGUMENTS non si sostituisce nel mio comando?

Tre cause principali, in ordine di frequenza: errore di case (deve essere maiuscolo $ARGUMENTS, non $args o $arguments), posizione del file sbagliata (deve trovarsi in .claude/commands/ o .claude/skills/), o sessione obsoleta (Claude Code legge i file di comando all'avvio della sessione, quindi riavvia dopo aver modificato). Se tutti e tre sono in ordine, esegui /echo-args foo con l'esempio minimale dall'H2 #1 per isolare il problema.

Posso rendere obbligatori certi argomenti?

Non a livello di sistema — non esiste una validazione nativa degli argomenti obbligatori. Lo schema è istruire il modello nel tuo prompt: "Se $1 è vuoto, fermati e di' all'utente di fornire un numero di issue." Il modello applica il contratto. Non è infallibile, ma in pratica è abbastanza affidabile per l'uso quotidiano, specialmente quando abbinato a un argument-hint chiaro.

model: nel frontmatter sovrascrive i flag CLI?

Sì — il frontmatter ha la precedenza. Se il tuo file di comando dichiara model: claude-haiku-4, quel comando gira su Haiku indipendentemente dal modello che l'utente ha selezionato per la sessione. È utile per comandi economici e invocati frequentemente che vuoi tenere lontano da Opus. Vedi la nostra guida su come cambiare modelli in Claude Code per scegliere la variante giusta per tipo di comando.

In Sintesi

Quattro schemi. Scegli quello che si adatta alla forma del tuo comando:

• Flag booleano (--dry-run) — scrivilo in $ARGUMENTS, lascia che il modello lo rilevi.
• Flag con valore (--filter <pattern>) — stesso approccio, il modello estrae il valore.
• Posizionale obbligatorio + flag opzionale — $1 per l'indispensabile, $ARGUMENTS per il resto.
• Posizionale stretto — $0/$1/$2 (o nominati via arguments:) quando ogni slot è obbligatorio e ordinato.

Ora che i tuoi comandi sono parametrici, il passo successivo è integrarli nei workflow degli agenti — inizia con il nostro tutorial sulle skill di Claude per l'upgrade al packaging multi-file, o esplora gli strumenti alternativi per la codifica con IA se stai confrontando i sistemi. In ogni caso, la tua cartella .claude/commands/ è appena diventata molto più utile.