Comment ajouter des drapeaux aux commandes slash de Claude Code : 4 patterns qui fonctionnent vraiment

Comment ajouter des drapeaux aux commandes slash de Claude Code : 4 patterns qui fonctionnent vraiment

Claude Code ne parse pas les --flags comme vous l'attendriez pour les commandes slash personnalisées — mais quatre patterns vous donnent exactement la même UX, et trois d'entre eux sont plus propres que le parsing CLI classique. Voici comment ajouter des drapeaux aux commandes slash de Claude Code correctement, avec des fichiers .md opérationnels à copier dès maintenant.

Réponse rapide :

• Claude Code ne parse pas les flags CLI (--json, --verbose) pour les commandes personnalisées — le harness n'a pas de parser de flags.
• Pour une UX à la CLI, écrivez les flags dans $ARGUMENTS et laissez le LLM les interpréter comme du langage naturel.
• Pour des arguments typés, utilisez les positionnels $1/$2 ou des arguments nommés déclarés dans le champ frontmatter arguments:.
• Documentez les flags attendus dans argument-hint: pour que l'autocomplétion / les affiche à l'utilisateur.

Comment fonctionnent vraiment les arguments des commandes slash Claude Code ?

Le harness de Claude Code substitue trois types de tokens avant d'envoyer votre commande au LLM : $ARGUMENTS (la chaîne entière après le nom de la commande), les positionnels $0/$1/$2 (segments entre guillemets à la manière shell), et les nommés $variableName déclarés en frontmatter. Il n'y a pas de parser de flags CLI intégré — --dry-run atterrit dans $ARGUMENTS comme du texte littéral.

Voilà ce qui piège tout le monde. Quand vous tapez /deploy --staging --dry-run, Claude Code n'exécute pas argparse sur --staging --dry-run. Le harness colle cette chaîne entière là où votre fichier .md référence $ARGUMENTS, puis envoie le prompt rendu au modèle. Le LLM voit --staging --dry-run comme de l'anglais ordinaire et décide quoi faire.

Ce n'est pas un bug — c'est le design. Le harness est une couche de substitution, pas un parser. Les commandes intégrées comme /clear et /help (voir la référence CLI officielle) ont bien des flags, mais les commandes personnalisées que vous créez obéissent à des règles différentes.

Le harness de Claude Code substitue des tokens, puis envoie le prompt rendu au LLM. Il n'y a pas de parser de flags.

Dans notre propre travail avec Claude Code, cette confusion est de loin la plus fréquente — les développeurs passent une heure à chercher pourquoi --verbose « n'est pas détecté » avant de réaliser que le LLM est le parser. Depuis Claude Code v2.1.126 (mai 2026), ce comportement est documenté dans la documentation officielle des slash-commands et ne changera pas de sitôt. Les slash commands sont un primitif voisin des hooks Claude Code — les deux étendent le harness, mais les commandes se déclenchent sur la saisie utilisateur tandis que les hooks se déclenchent sur les événements d'outil.

Voici la commande personnalisée la plus minimaliste qui prouve le modèle de substitution :

---
description: Echo whatever the user types after the command
argument-hint: [anything]
---

The user passed these arguments: $ARGUMENTS

Repeat them back verbatim, then describe what the user probably meant.

Sauvegardez cela sous .claude/commands/echo-args.md, tapez /echo-args hello world --foo, et le LLM verra la chaîne littérale hello world --foo substituée dans le prompt. C'est tout le modèle mental. Pour une présentation approfondie de la relation entre les fichiers de commandes et le système de skills au sens large, consultez notre tutoriel sur les Skills Claude.

Créez votre première commande slash paramétrique en 5 minutes

Créez .claude/commands/greet.md avec trois lignes de frontmatter et une ligne de prompt qui référence $ARGUMENTS. Redémarrez Claude Code, tapez /greet World, et regardez World se substituer dans le prompt avant que le LLM le voie. Voilà toute la cérémonie — cinq étapes, sans outil de build.

Voici la recette de bout en bout :

1. Créez le répertoire. Depuis la racine de votre projet, lancez mkdir -p .claude/commands. Le dossier .claude/ vit aux côtés de votre code ; les commandes à l'intérieur sont découvertes automatiquement au démarrage d'une session Claude Code.
2. Écrivez le fichier de commande. Sauvegardez le snippet ci-dessous sous .claude/commands/greet.md.
3. Rechargez votre session. Quittez et relancez Claude Code (ou exécutez /reload si votre version le supporte). Les commandes sont lues une seule fois au démarrage de la session.
4. Invoquez-la. Tapez /greet World dans le chat.
5. Vérifiez la substitution. Ouvrez la transcription et confirmez que le LLM a vu World interpolé dans le corps du prompt, et non le token littéral $ARGUMENTS.

Voici le fichier complet :

---
description: Greet someone enthusiastically
argument-hint: <name>
---

You are a friendly assistant. Greet the person named "$ARGUMENTS" with one short, warm sentence. Then ask them what they're working on today.

Et l'interaction dans le terminal :

> /greet World
Hey World, great to see you! What are you working on today?

C'est tout. Vous avez maintenant une commande slash paramétrique. Le champ argument-hint est ce qui fait que le menu d'autocomplétion / affiche <name> à côté de votre commande — petit détail UX, grand impact.

Si $ARGUMENTS ne se substitue pas, 9 fois sur 10 c'est parce que vous avez tapé $args ou $ARGS — le token est en majuscules strictes.

Le token est sensible à la casse et exact. $ARGUMENTS fonctionne. $arguments, $args, $ARGS, ${ARGUMENTS} échouent silencieusement — ils sont envoyés au LLM comme du texte littéral et le modèle ne voit que du bruit. Vérifiez l'orthographe trois fois avant d'imaginer un bug plus profond.

Quels champs frontmatter contrôlent la gestion des arguments ?

Cinq champs frontmatter définissent le comportement d'une commande slash vis-à-vis des arguments : argument-hint (ce que l'autocomplétion affiche), allowed-tools (ce que la commande peut appeler), arguments (déclaration d'arguments nommés), model (quelle variante Claude exécute la commande), et disable-model-invocation (verrouille la commande à l'invocation manuelle uniquement). Ensemble, ils couvrent pratiquement tous les patterns paramétriques dont vous aurez besoin.

Voici la référence complète du frontmatter pour les commandes personnalisées Claude Code v2.1.x :

Deux pièges à afficher bien en vue. D'abord, allowed-tools est séparé par des espaces, pas des virgules. Écrire Bash(git:*), Read, Edit va silencieusement ne rien mettre en liste blanche — le parser traite toute la chaîne comme une seule entrée malformée. Utilisez Bash(git:*) Read Edit. On l'a appris à nos dépens ; pour d'autres patterns du même acabit, consultez notre guide des meilleures pratiques CLAUDE.md sur les conventions des fichiers de config.

Ensuite, le champ model: surcharge le modèle que l'utilisateur a sélectionné pour la session. Utile quand une commande est peu coûteuse en calcul et que vous voulez la forcer sur une variante plus légère — voir notre guide sur la sélection de modèle pour choisir entre Opus 4.7 et Sonnet selon les types de commandes.

Le champ disable-model-invocation: true est votre filet de sécurité pour les commandes destructrices. Activez-le sur /deploy-prod ou /drop-database et les autres agents ne pourront pas appeler ces commandes par programmation — seul un humain qui tape dans le chat peut les déclencher.

Quels sont les 4 patterns d'arguments que vous utiliserez vraiment ?

Quatre patterns couvrent environ 95 % des commandes slash Claude Code réelles : (1) flag booléen comme /deploy --dry-run parsé par le LLM depuis $ARGUMENTS, (2) flag avec valeur comme /test --filter auth extrait de $ARGUMENTS, (3) positionnel requis + flag optionnel comme /fix-issue 123 --priority high mixant $1 et $ARGUMENTS, et (4) positionnel strictement typé comme /migrate-component SearchBar React Vue utilisant $0/$1/$2.

Choisissez celui qui correspond à la forme de votre commande. Voici un fichier .md opérationnel pour chacun.

Pattern 1 : Flag booléen (--dry-run)

Quand vous voulez une UX à la CLI et que le flag est juste on/off, appuyez-vous sur le LLM pour le détecter dans $ARGUMENTS. Pas de logique de parsing, pas de jonglage positionnel — décrivez simplement la règle dans le prompt.

---
description: Deploy to staging or production
argument-hint: [--dry-run]
allowed-tools: Bash(git:*) Bash(npm:*) Read
---

Deploy the current branch to staging.

Arguments passed: $ARGUMENTS

If "$ARGUMENTS" contains "--dry-run", DO NOT actually deploy. Instead, print the deployment plan: which files would change, which env vars would be set, and which commands would run. Stop after printing the plan.

Otherwise, proceed with the real deployment using `git push staging main` and `npm run deploy:staging`.

Tapez /deploy --dry-run et le LLM voit le flag, imprime le plan et s'arrête. Tapez /deploy et il déploie. Le harness n'a rien parsé — c'est le LLM qui a tout fait, ce qui est exactement ce pour quoi il est fait.

Pattern 2 : Flag avec valeur (--filter <pattern>)

Même idée, mais le flag porte une valeur. Le LLM lit --filter auth depuis $ARGUMENTS et utilise la sous-chaîne qui suit.

---
description: Run the test suite, optionally filtered
argument-hint: [--filter <pattern>]
allowed-tools: Bash(npm:*) Read
---

Run the project's test suite.

Arguments: $ARGUMENTS

If "$ARGUMENTS" contains "--filter <pattern>", run only tests matching <pattern>. Use `npm test -- --grep <pattern>` for the actual command.

If no `--filter` is present, run the full suite with `npm test`.

Report pass/fail counts at the end.

/test --filter auth n'exécute que les tests d'authentification. /test exécute tout. Le LLM extrait le pattern après --filter de façon fiable — Claude est vraiment bon pour ce type d'extraction de texte structuré, bien plus que les gens ne l'imaginent.

Pattern 3 : Positionnel requis + flag optionnel

C'est le hybride que nous utilisons le plus dans notre propre bibliothèque de commandes. $1 porte l'argument requis, $ARGUMENTS porte tout (pour que le LLM puisse encore repérer les flags optionnels). C'est le mélange le plus propre quand un argument est non négociable et que le reste est du contexte libre.

---
description: Fix a GitHub issue
argument-hint: <issue-number> [--priority high|medium|low] [context...]
allowed-tools: Bash(gh:*) Bash(git:*) Read Edit
---

Fix GitHub issue #$1.

Full arguments: $ARGUMENTS

Steps:
1. Run `gh issue view $1` to load the issue body.
2. Read the codebase to locate the relevant file(s).
3. If "$ARGUMENTS" contains "--priority high", create a hotfix branch off main. Otherwise branch off develop.
4. Apply the fix, run tests, and open a PR linked to the issue.

Anything else in $ARGUMENTS after the issue number is freeform context — fold it into your understanding of the bug.

Invoquez avec /fix-issue 1234 --priority high le formulaire de login efface l'email après un échec. $1 se résout en 1234. $ARGUMENTS se résout en toute la chaîne qui suit, que le LLM parse allègrement pour extraire à la fois le flag de priorité et la description en texte libre.

On utilise exactement ce mélange $1 + $ARGUMENTS dans notre commande /fix-issue — $1 pour le numéro d'issue, le reste pour le contexte libre que le LLM interprète. C'est le pattern au meilleur ROI après un an d'usage quotidien de Claude Code.

Pattern 4 : Positionnel strict (typé)

Quand tous les arguments sont obligatoires et que l'ordre compte, abandonnez $ARGUMENTS entièrement. Utilisez $0/$1/$2 (ou des arguments nommés via le champ frontmatter arguments:) pour des slots typés sans ambiguïté.

---
description: Migrate a component between frameworks
argument-hint: <component> <from-framework> <to-framework>
arguments: [component, fromFramework, toFramework]
allowed-tools: Read Edit Write
---

Migrate the component named "$component" from $fromFramework to $toFramework.

1. Read the existing component file (search for `$component.{jsx,tsx,vue,svelte}`).
2. Translate the component idioms from $fromFramework to $toFramework: lifecycle methods, state handling, prop syntax, event binding.
3. Write the new file in the matching extension for $toFramework.
4. Print a diff summary at the end.

If $fromFramework or $toFramework is unsupported, abort and tell the user which frameworks ARE supported (React, Vue, Svelte, Solid).

Invoquez avec /migrate-component SearchBar React Vue. La déclaration d'arguments nommés rend l'autocomplétion et le corps du prompt auto-documentés — quiconque lit migrate-component.md sait d'un coup d'œil quel slot est lequel. Ce pattern brille pour les commandes à trois arguments ou plus. Vous retrouverez ce style dans des bibliothèques communautaires comme wshobson/commands sur GitHub.

Les flags booléens et avec valeur fonctionnent parce que le LLM est un parser flexible. Le positionnel strict fonctionne parce qu'aucune intelligence du LLM n'est requise. Mélanger les deux, c'est le secret.

Quand utiliser $ARGUMENTS vs positionnel vs nommé ?

Utilisez $ARGUMENTS quand les arguments sont au style flags CLI et que vous voulez un parsing flexible par le LLM. Utilisez les positionnels $1/$2 quand les arguments sont typés, ordonnés, et que vous voulez zéro ambiguïté LLM. Utilisez les nommés arguments: quand il y a 3+ arguments et que la clarté dans l'autocomplétion importe plus que la concision. Voici la matrice de décision :

Le réflexe de la plupart des développeurs est de d'abord atteindre $ARGUMENTS parce que c'est le plus proche du monde bash qu'ils connaissent. C'est bien pour les prototypes, mais le positionnel typé est vraiment meilleur quand le contrat est stable. Le LLM n'a pas besoin d'interpréter $1 — c'est déjà une chaîne propre.

Une règle empirique : si vous pouvez décrire la signature de la commande en une phrase anglaise sans utiliser les mots « or » et « optionally », allez au positionnel. Si vous avez besoin de ces mots, allez à $ARGUMENTS.

Les slash commands sont-elles les mêmes que les Skills maintenant ?

Anthropic a fusionné les commandes personnalisées dans le système de skills au sens large au printemps 2026, mais les fichiers .claude/commands/*.md fonctionnent toujours avec le même frontmatter. Un skill est un répertoire (.claude/skills/foo/SKILL.md plus des fichiers complémentaires) avec un contrôle d'invocation étendu comme disable-model-invocation. Une commande est un seul fichier .md. Mêmes règles de substitution, emballage différent.

Voici la différence pratique :

Donc non, .claude/commands/ n'est pas déprécié. Anthropic a explicitement maintenu le fonctionnement de la forme fichier lors de la fusion des systèmes — trop de projets ont des bibliothèques de commandes épinglées en version control. Si vous voulez des fichiers complémentaires (comme une référence CONTRIBUTING.md que votre skill charge, ou un template.json qu'il copie), optez pour les skills. Sinon, restez avec les commandes.

La fusion s'inscrit dans une dynamique plus large vers le standard ouvert agentskills.io, et c'est l'un des changements v2.1.x qui méritent d'être connus — consultez notre tour d'horizon des fonctionnalités Claude Code v2.1 pour le panorama complet et notre tutoriel sur les Skills pour une présentation approfondie.

Pourquoi $ARGUMENTS ne se substitue pas ? Les bugs courants résolus

Cinq raisons courantes pour lesquelles $ARGUMENTS échoue à se substituer : (1) token en minuscules ou abrégé ($args, $ARGS, $arguments — doit être le littéral $ARGUMENTS), (2) arguments multi-mots non entre guillemets (/cmd hello world se divise ; /cmd "hello world" les garde ensemble), (3) allowed-tools séparé par des virgules au lieu d'espaces, (4) fichier de commande absent de .claude/commands/ ou .claude/skills/, (5) session Claude Code à recharger après modification du fichier.

$ARGUMENTS apparaît littéralement dans le prompt LLM

Symptôme : Votre prompt affiche $ARGUMENTS en texte brut dans la réponse du modèle, comme si le harness l'avait ignoré. Cause : Mauvaise casse ou mauvaise orthographe. Le token est littéralement $ARGUMENTS — huit caractères, tout en majuscules. Fix : Ouvrez le .md, cherchez $args, $ARGS, $arguments, ${ARGUMENTS}, remplacez par $ARGUMENTS. Le bug de la faute de frappe $args a touché chaque développeur de notre équipe au moins une fois ; c'est le bug le plus fréquent dans la famille « commande slash inconnue ».

Un argument multi-mots se divise de façon inattendue

Symptôme : Vous avez lancé /migrate-component Search Bar React Vue et $1 vaut Search, $2 vaut Bar. Cause : Les espaces divisent les arguments positionnels. Fix : Mettez l'argument multi-mots entre guillemets : /migrate-component "Search Bar" React Vue. Maintenant $1 vaut Search Bar. Cela correspond au comportement shell, qui est le modèle mental que le harness imite délibérément.

allowed-tools n'est pas respecté

Symptôme : La commande s'exécute mais Claude refuse d'appeler des outils que vous pensiez avoir mis en liste blanche, ou appelle des outils que vous n'aviez pas listés. Cause : Séparation par virgules au lieu d'espaces. Fix : Changez allowed-tools: Bash, Read, Edit en allowed-tools: Bash Read Edit. Pour les sous-patterns d'outils, formatez ainsi : Bash(git:*) Bash(npm:*) Read.

La commande n'apparaît pas dans l'autocomplétion /

Symptôme : Vous tapez / et votre commande n'est pas dans la liste. Cause : Emplacement du fichier, frontmatter manquant, ou disable-model-invocation mal configuré. Fix : Confirmez que le fichier est à .claude/commands/yourcmd.md (ou .claude/skills/yourcmd/SKILL.md) relativement à la racine de votre projet. Confirmez que le frontmatter a au moins un champ description:. Si vous avez défini disable-model-invocation: true, la commande ne sera pas visible des autres agents mais apparaîtra quand même dans le menu / humain.

Vous avez modifié le fichier .md mais rien n'a changé

Symptôme : Vous avez corrigé le bug, sauvegardé le fichier, relancé la commande, même comportement cassé. Cause : Claude Code met en cache les fichiers de commandes au démarrage de la session. Fix : Quittez et relancez Claude Code, ou exécutez /reload si votre version le supporte.

Claude Code lit les fichiers .md au démarrage de la session. Si vous modifiez une commande et qu'elle « ne change pas », redémarrez votre session avant d'imaginer un bug plus profond.

Pour les cas aux limites au-delà de ces cinq, les issues du dépôt Claude Code sont le meilleur endroit pour chercher. La plupart des bugs de substitution étranges que nous avons vus sont une variation de l'un des cas ci-dessus.

FAQ : Arguments des commandes slash Claude Code

Comment passer des arguments à une commande slash Claude Code ?

Tapez la chaîne d'arguments après le nom de la commande : /greet World. Dans le fichier .md de votre commande, référencez la valeur comme $ARGUMENTS (toute la chaîne), $1 (premier positionnel), ou $variableName (si vous avez déclaré arguments: [variableName] en frontmatter). Le harness substitue le token avant d'envoyer le prompt au LLM.

Qu'est-ce que $ARGUMENTS dans Claude Code ?

$ARGUMENTS est un token de substitution dans les fichiers de commandes slash personnalisées que le harness de Claude Code remplace par la chaîne d'arguments complète que l'utilisateur a tapée après le nom de la commande. Si un utilisateur exécute /deploy --staging --dry-run, alors $ARGUMENTS devient la chaîne littérale --staging --dry-run dans le prompt rendu, avant même que le LLM le voie.

Les commandes slash Claude Code peuvent-elles prendre des flags CLI comme --json ?

Pas nativement — le harness n'a pas de parser de flags pour les commandes personnalisées. Vous écrivez --json dans $ARGUMENTS, et votre prompt instruit le LLM de le détecter et de se comporter en conséquence. Cela fonctionne parce que Claude est un parser flexible du texte structuré. Les commandes intégrées comme /clear et /help ont de vrais flags, mais les commandes personnalisées que vous créez obéissent aux règles de substitution seules.

Quelle est la différence entre $1, $ARGUMENTS, et $name dans Claude Code ?

$1 est le premier argument positionnel séparé par des espaces ($2 est le deuxième, et ainsi de suite). $ARGUMENTS est toute la chaîne d'arguments verbatim, y compris toutes les parties positionnelles et tous les flags. $name est un argument nommé déclaré dans le champ frontmatter arguments: [name] — utile quand vous voulez des slots positionnels auto-documentés sans indexation numérique.

Comment fonctionne argument-hint dans Claude Code ?

argument-hint est un champ frontmatter qui contrôle ce que le menu d'autocomplétion / affiche à côté du nom de votre commande. Définir argument-hint: <issue-number> [--priority high] affiche exactement ce template après que l'utilisateur tape /. C'est uniquement UX — cela ne valide ni ne parse les arguments. Ça vaut quand même la peine de le définir car c'est la documentation la moins chère que vous écrirez jamais.

Comment créer une commande slash personnalisée avec plusieurs arguments ?

Deux options propres. Pour le positionnel : référencez $1, $2, $3 dans le corps du prompt. Pour le nommé : déclarez arguments: [first, second, third] en frontmatter et référencez $first, $second, $third. Le nommé est plus lisible pour trois arguments et plus. Utilisez $ARGUMENTS seulement quand vous voulez que le LLM parse une chaîne libre après les slots positionnels requis.

.claude/commands/ est-il déprécié au profit de .claude/skills/ ?

Non. Anthropic a fusionné les deux systèmes au printemps 2026 mais a explicitement maintenu le fonctionnement de .claude/commands/*.md avec des règles de substitution identiques. Utilisez les commandes pour les automatisations sur un seul fichier et les skills pour les bundles multi-fichiers (SKILL.md plus templates ou références). Même frontmatter, même comportement $ARGUMENTS, emballage différent. Les deux sont de première classe depuis v2.1.126.

Pourquoi $ARGUMENTS ne se substitue pas dans ma commande ?

Trois causes principales, par ordre de fréquence : erreur de casse (doit être $ARGUMENTS en majuscules, pas $args ni $arguments), mauvais emplacement du fichier (doit vivre dans .claude/commands/ ou .claude/skills/), ou session obsolète (Claude Code lit les fichiers de commandes au démarrage, donc redémarrez après modification). Si les trois sont vérifiés, lancez /echo-args foo avec l'exemple minimal du premier H2 pour isoler le problème.

Peut-on rendre certains arguments obligatoires ?

Pas au niveau du harness — il n'y a pas de validation d'arguments requis native. Le pattern consiste à instruire le LLM dans votre prompt : « Si $1 est vide, arrêtez et dites à l'utilisateur de fournir un numéro d'issue. » Le modèle fait respecter le contrat. Ce n'est pas infaillible, mais en pratique c'est suffisamment fiable pour un usage quotidien, surtout combiné à un argument-hint clair.

Le model: en frontmatter surcharge-t-il les flags CLI ?

Oui — le frontmatter gagne. Si votre fichier de commande déclare model: claude-haiku-4, cette commande s'exécute sur Haiku quel que soit le modèle que l'utilisateur a sélectionné pour la session. Utile pour les commandes fréquentes peu coûteuses que vous voulez garder hors d'Opus. Voir notre guide sur le changement de modèles Claude pour choisir la bonne variante par type de commande.

Conclusion

Quatre patterns. Choisissez celui qui correspond à la forme de votre commande :

• Flag booléen (--dry-run) — écrivez-le dans $ARGUMENTS, laissez le LLM le détecter.
• Flag avec valeur (--filter <pattern>) — même approche, le LLM extrait la valeur.
• Positionnel requis + flag optionnel — $1 pour le non-négociable, $ARGUMENTS pour le reste.
• Positionnel strict — $0/$1/$2 (ou nommé via arguments:) quand chaque slot est requis et ordonné.

Maintenant que vos commandes sont paramétriques, la prochaine étape est de les intégrer dans des workflows d'agents — commencez par notre tutoriel Claude Skills pour passer à l'emballage multi-fichiers, ou parcourez les outils de coding alternatifs si vous comparez des harnesses. Dans tous les cas, votre dossier .claude/commands/ vient de devenir beaucoup plus utile.