Slash command custom in Claude Code: /commit, /review-pr, /deploy e altri

Claude Code arriva con una manciata di slash command pronti: /help, /clear, /compact, /model. Utili, ma il valore vero sta nel fatto che puoi definire i tuoi. Un file markdown in una cartella, e hai uno shortcut riusabile per i flussi che ripeti ogni giorno: creare un commit, aprire una PR, rivedere codice, fare deploy, generare changelog.

Non e’ magia, e’ un prompt template con un po’ di frontmatter YAML. Ma proprio perche’ e’ semplice vale la pena capirlo bene, specie se lavori in team.

Cosa sono, in pratica

Uno slash command custom e’ un file .md che Claude Code legge al volo quando digiti /nome-comando. Il contenuto del file viene iniettato come prompt, con eventuali placeholder sostituiti. Nessun eseguibile, nessun plugin da installare: solo markdown.

Le due location che contano:

• Personali: ~/.claude/commands/ — visibili solo a te, su qualsiasi progetto
• Di progetto: .claude/commands/ nella root del repo — committati in git, condivisi col team

Il nome del file e’ il nome del comando. commit.md diventa /commit. Le sottocartelle creano namespace: .claude/commands/git/commit.md diventa /git:commit.

Anatomia di un comando

La struttura minima e’ frontmatter YAML opzionale + corpo markdown con le istruzioni. Campi riconosciuti dal frontmatter:

• description: una riga, appare nell’autocomplete quando digiti /
• argument-hint: suggerimento sugli argomenti attesi (es. [message] | [ticket-id])
• allowed-tools: whitelist dei tool che Claude puo’ usare dentro il comando
• model: forza un modello specifico per quel comando

Il corpo e’ il prompt vero e proprio. Puoi usare placeholder dinamici: $ARGUMENTS prende tutto quello che segue il comando come una stringa unica, $1, $2, $3 prendono i singoli argomenti posizionali. In aggiunta, se prefissi una riga con ! Claude Code esegue quel comando shell prima di inviare il prompt e ne include l’output nel contesto.

Un /commit che funziona

Esempio concreto: un comando che analizza il diff corrente, decide se serve uno o piu’ commit, e li crea seguendo conventional commits.

---
description: Crea commit conventional partendo dal diff staged o unstaged
argument-hint: [nota opzionale da aggiungere al corpo]
allowed-tools: Bash(git:*), Read, Grep
---

Contesto corrente del repo:

- Status: !`git status --short`
- Diff staged: !`git diff --cached --stat`
- Diff unstaged: !`git diff --stat`
- Ultimi 5 commit: !`git log --oneline -5`

Istruzioni:

1. Se non c'e' nulla di staged, esegui `git add -A` solo dopo avermelo detto
2. Analizza il diff e raggruppa i cambi per intento logico
3. Se ci sono cambi non correlati, proponi piu' commit separati
4. Usa formato conventional: `type(scope): subject` in minuscolo, imperativo, max 72 char
5. Se l'utente ha passato una nota ($ARGUMENTS), aggiungila al body del commit
6. Non pushare mai automaticamente
7. Mostra il messaggio finale prima di eseguire `git commit`

Salvato come .claude/commands/commit.md, diventa /commit. Lanciato con /commit ref #1234, la stringa ref #1234 finisce in $ARGUMENTS.

Placeholder: $ARGUMENTS vs posizionali

La differenza conta quando il comando prende input strutturato. Un /review-pr 1234 main dove il primo argomento e’ il numero PR e il secondo il branch base, si scrive cosi’:

---
description: Review di una PR GitHub
argument-hint: [pr-number] [base-branch]
allowed-tools: Bash(gh:*), Bash(git:*), Read, Grep
---

Recupera la PR #$1 e confrontala con $2.

1. !`gh pr view $1 --json title,body,files,additions,deletions`
2. !`gh pr diff $1`
3. Analizza i cambi contro la base $2
4. Produci review strutturata: bug, security, performance, leggibilita'
5. Non postare il commento automaticamente, mostramelo prima

Se invece usi $ARGUMENTS prendi tutto come un blob unico — comodo quando il comando e’ free-form (es. /brainstorm idea per onboarding).

allowed-tools: la gabbia che ti salva

Il campo allowed-tools limita cosa il comando puo’ invocare. Un /deploy che fa partire script in produzione non dovrebbe avere accesso a tool generici: va scoped stretto. La sintassi supporta pattern per i Bash:

• Bash(git:*): solo comandi git
• Bash(npm run test:*): solo test runner
• Read, Grep, Glob: sola lettura, zero scrittura
• WebFetch(domain:docs.claude.com): fetch solo su domini whitelisted

Se non specifichi nulla, il comando eredita i permessi della sessione. Meglio essere espliciti: ti risparmia brutte sorprese e rende il comando riproducibile fra utenti con profili diversi.

Personali vs di progetto

Regola pratica: nei ~/.claude/commands/ ci vanno le abitudini tue (stile commit, template email, scorciatoie per il tuo stack preferito). Nei .claude/commands/ del repo ci va tutto quello che serve anche ai colleghi: /deploy, /run-migration, /release, /check-env.

Committare .claude/commands/ nel repo ha un effetto collaterale positivo: nuovo sviluppatore clona, apre Claude Code, scrive / e vede i comandi standard del progetto. E’ documentazione eseguibile. Ed e’ un formato leggibile da umani, quindi non hai dipendenza vincolante dall’IDE.

Anti-pattern da evitare

• Comandi chilometrici: se il prompt supera 150-200 righe, spezzalo o spostalo in una skill. Gli slash command eccellono per task focalizzati
• Side effect non dichiarati: un /fix che pusha su main senza avvisare e’ un bug in attesa. Dichiara sempre cosa tocca il filesystem o la rete
• Troppa specificita’: /commit-for-payment-module-v2 non serve. Parametrizza con $ARGUMENTS
• Hardcode di path assoluti: rendi il comando portabile, usa path relativi alla root del repo
• Duplicati fra personale e progetto: la versione di progetto vince, ma crea confusione. Tieni i nomi distinti

Dove si incastrano con il resto

Gli slash command sono uno dei tre meccanismi di estensione di Claude Code. Gli altri due sono https://www.smartworkers.cloud/?p=3421 per reagire automaticamente a eventi (pre/post tool use), e https://www.smartworkers.cloud/?p=3423 per impacchettare conoscenza di dominio riusabile. Regola grossolana: slash command per azioni esplicite che lanci tu, hook per automazione passiva, skill per expertise che Claude carica on-demand.

Dopo tre o quattro comandi salvati ti accorgi che il terminale inizia a comportarsi come un IDE custom cucito sul tuo workflow. La domanda interessante non e’ “quali comandi esistono”, e’ “quale parte del tuo lavoro e’ abbastanza ripetitiva da meritare un file markdown di 30 righe?”