Як додати прапорці до слеш-команд Claude Code: 4 патерни, які справді працюють

Як додавати прапорці до слеш-команд Claude Code: 4 патерни, які справді працюють

Claude Code насправді не розбирає --flags так, як ви очікували б для власних слеш-команд, але чотири патерни дають той самий UX, і три з них чистіші, ніж будь-коли був розбір у CLI. Ось як правильно додавати прапорці до слеш-команд Claude Code — із робочими файлами .md, які ви можете скопіювати вже сьогодні.

Коротка відповідь:

• Claude Code не розбирає прапорці CLI (--json, --verbose) для власних команд — парсера прапорців там немає.
• Для UX у стилі CLI записуйте прапорці в $ARGUMENTS і дозвольте LLM інтерпретувати їх як природну мову.
• Для типізованих аргументів використовуйте позиційні $1/$2 або іменовані аргументи, оголошені у полі frontmatter arguments:.
• Документуйте очікувані прапорці в argument-hint:, щоб автодоповнення / показувало їх користувачу.

Як насправді працюють аргументи слеш-команд у Claude Code?

Перед тим як надіслати вашу команду LLM, Claude Code підставляє три типи токенів: $ARGUMENTS (увесь рядок після назви команди), позиційні $0/$1/$2 (сегменти в лапках у стилі оболонки) та іменовані $variableName, оголошені у frontmatter. Вбудованого парсера CLI-прапорців немає, тож --dry-run потрапляє в $ARGUMENTS як буквальний текст.

Ось момент, на якому спотикаються всі. Коли ви вводите /deploy --staging --dry-run, Claude Code не запускає argparse для --staging --dry-run. Система вставляє весь цей рядок туди, де ваш .md файл посилається на $ARGUMENTS, а потім надсилає зрендерений промпт моделі. LLM сприймає --staging --dry-run як звичайну англійську і вирішує, що робити.

Це не баг, а задум. Це шар підстановки, а не парсер. Вбудовані команди, як-от /clear і /help (див. офіційний довідник CLI), мають прапорці, але кастомні команди, які ви створюєте, живуть за іншими правилами.

Claude Code підставляє токени, а потім передає зрендерений промпт LLM. Парсера прапорців немає.

У нашій власній роботі з Claude Code найпоширеніша плутанина — саме ця: розробники витрачають годину, намагаючись зрозуміти, чому --verbose «не виявляється», перш ніж усвідомити, що парсером є LLM. Станом на Claude Code v2.1.126 (травень 2026) ця поведінка задокументована в офіційній документації зі слеш-команд і найближчим часом не зміниться. Слеш-команди — це споріднений примітив поруч із хуками Claude Code: обидва розширюють систему, але команди спрацьовують у відповідь на введення користувача, тоді як хуки — у відповідь на події інструментів.

Ось найменша можлива кастомна команда, яка доводить модель підстановки:

---
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.

Збережіть це як .claude/commands/echo-args.md, введіть /echo-args hello world --foo, і LLM побачить буквальний рядок hello world --foo, підставлений у промпт. Це й уся ментальна модель. Щоб детальніше розібратися, як файли команд пов'язані із ширшою системою навичок, перегляньте наш вступ до Skills.

Створіть свою першу параметричну слеш-команду за 5 хвилин

Створіть .claude/commands/greet.md з трьома рядками фронтматеру та одним рядком промпту, який посилається на $ARGUMENTS. Перезапустіть Claude Code, введіть /greet World і побачте, як World підставляється у промпт ще до того, як його побачить LLM. Ось і вся церемонія — п'ять кроків, жодних інструментів збірки.

Ось повний рецепт від початку до кінця:

1. Створіть каталог. У корені проєкту виконайте mkdir -p .claude/commands. Папка .claude/ лежить поруч із вашим кодом; команди всередині неї автоматично виявляються, коли Claude Code починає сесію.
2. Напишіть файл команди. Збережіть наведений нижче сніпет як .claude/commands/greet.md.
3. Перезавантажте сесію. Вийдіть і заново запустіть Claude Code (або виконайте /reload, якщо ваша версія це підтримує). Команди зчитуються один раз на початку сесії.
4. Викличте її. Введіть /greet World у чаті.
5. Перевірте підстановку. Відкрийте транскрипт і переконайтеся, що LLM отримала World, інтерпольований у тіло промпту, а не буквальний токен $ARGUMENTS.

Ось повний файл:

---
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.

І взаємодія в терміналі:

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

Ось і все. Тепер у вас є параметрична слеш-команда. Саме поле argument-hint змушує меню автодоповнення / показувати <name> поруч із вашою командою — дрібна UX-деталь, а віддача велика.

Якщо $ARGUMENTS не підставляється, у 9 випадках із 10 це тому, що ви ввели $args або $ARGS — токен пишеться буквально великими літерами.

Токен чутливий до регістру й має бути точним. $ARGUMENTS працює. $arguments, $args, $ARGS, ${ARGUMENTS} — усі вони тихо не спрацьовують: потрапляють до LLM як буквальний текст, і модель бачить просто нісенітницю. Тричі перевірте написання, перш ніж припускати глибший баг.

Які поля frontmatter керують обробкою аргументів?

П'ять полів frontmatter визначають, як слеш-команда обробляє аргументи: argument-hint (що показує автодоповнення), allowed-tools (що команда може викликати), arguments (оголошення іменованих аргументів), model (який варіант Claude її виконує) та disable-model-invocation (закріплює команду виключно за викликом користувачем). Разом вони покривають практично будь-який шаблон параметризації, який вам знадобиться.

Ось повний довідник frontmatter для користувацьких команд Claude Code v2.1.x:

Дві пастки, про які варто пам'ятати. По-перше, allowed-tools розділяється пробілами, а не комами. Якщо написати Bash(git:*), Read, Edit, білий список мовчки не спрацює — парсер розглядатиме весь рядок як один неправильний запис. Використовуйте Bash(git:*) Read Edit. Ми дізналися про це на гіркому досвіді; щоб побачити більше подібних прикладів, ознайомтеся з нашими найкращими практиками CLAUDE.md щодо конвенцій файлів конфігурації.

По-друге, поле model: перевизначає модель, яку користувач наразі обрав для сесії. Це корисно, коли команда є обчислювально простою і ви хочете примусово запустити її на меншому варіанті — дивіться наш посібник із вибору моделі, щоб визначитися між Opus 4.7 та Sonnet для різних типів команд.

Поле disable-model-invocation: true — це ваша страховка для деструктивних команд. Встановіть його для /deploy-prod або /drop-database, і інші агенти не зможуть викликати ці команди програмно — лише людина, яка вводить текст у чат, зможе їх запустити.

Які 4 патерни аргументів ви насправді використовуватимете?

Чотири патерни покривають приблизно 95% реальних слеш-команд Claude Code: (1) булевий прапорець, як-от /deploy --dry-run, який LLM розбирає з $ARGUMENTS; (2) прапорець зі значенням, як-от /test --filter auth, що витягується з $ARGUMENTS; (3) обов'язковий позиційний + необов'язковий прапорець, як-от /fix-issue 123 --priority high, де поєднуються $1 і $ARGUMENTS; та (4) строго типізований позиційний, як-от /migrate-component SearchBar React Vue, що використовує $0/$1/$2.

Обирайте той, що відповідає формі вашої команди. Ось робочий файл .md для кожного з них.

Патерн 1: Булевий прапорець (--dry-run)

Якщо вам потрібна поведінка CLI-прапорця, а сам прапорець — лише увімк/вимк, покладіться на LLM, щоб вона розпізнала його всередині $ARGUMENTS. Жодної логіки парсингу, жодної жонглювання позиціями — просто опишіть правило в промпті.

---
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`.

Введіть /deploy --dry-run — і LLM побачить прапорець, виведе план та зупиниться. Введіть /deploy — і вона задеплоїть. Користувач не виконав жодного парсингу, LLM зробила всю роботу, а це саме те, що вона вміє найкраще.

Патерн 2: Прапорець зі значенням (--filter <pattern>)

Та сама ідея, але тепер прапорець має значення. LLM зчитує --filter auth із $ARGUMENTS і використовує підрядок після нього.

---
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 запускає лише тести автентифікації. /test запускає все. LLM надійно витягує патерн після --filter, тому що Claude справді добре справляється з таким виділенням структурованого тексту — набагато надійніше, ніж зазвичай очікують.

Патерн 3: Обов'язковий позиційний + необов'язковий прапорець

Це гібрид, який ми найчастіше використовуємо у власній бібліотеці команд. $1 передає обов'язковий аргумент, $ARGUMENTS містить усе підряд (тож LLM досі може розпізнавати необов'язкові прапорці). Це найчистіша комбінація, коли один аргумент є обов'язковим, а решта — довільний контекст.

---
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.

Виклик виглядає як /fix-issue 1234 --priority high the login form blanks the email field after a failed attempt. $1 розгортається у 1234. $ARGUMENTS розгортається в увесь хвостовий рядок, який LLM охоче розбирає, виокремлюючи і прапорець пріоритету, і довільний опис.

Ми використовуємо саме цю комбінацію $1 + $ARGUMENTS у нашій команді /fix-issue: $1 — для номера задачі, решта — для довільного контексту, який LLM розбирає. Це патерн із найвищою віддачею за рік щоденного використання Claude Code.

Патерн 4: Строгий позиційний (типізований)

Коли всі аргументи обов'язкові й порядок має значення, повністю приберіть $ARGUMENTS. Використовуйте $0/$1/$2 (або іменовані аргументи через поле arguments: у frontmatter) для однозначних типізованих слотів.

---
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).

Виклик має вигляд /migrate-component SearchBar React Vue. Оголошення іменованих аргументів робить автодоповнення та тіло промпта самодокументованими — кожен, хто читає migrate-component.md, може з першого погляду зрозуміти, який слот за що відповідає. Цей патерн особливо добре працює для команд із трьома або більше обов'язковими аргументами. Такий стиль також можна побачити в бібліотеках спільноти, як-от wshobson/commands на GitHub.

Булеві прапорці та прапорці зі значенням працюють, тому що LLM — гнучкий парсер. Строгий позиційний підхід працює, тому що інтелект LLM не потрібен. Поєднання цих двох підходів — і є секрет.

Коли варто використовувати $ARGUMENTS проти позиційних та іменованих?

Використовуйте $ARGUMENTS, коли аргументи мають стиль CLI-прапорців і вам потрібен гнучкий парсинг з боку LLM. Використовуйте позиційні $1/$2, коли аргументи типізовані, впорядковані й вам потрібна нульова неоднозначність з боку LLM. Використовуйте іменовані arguments:, коли аргументів 3+ і зрозумілість в автодоповненні важливіша за лаконічність. Ось матриця рішень:

Інстинкт більшості розробників — спершу потягнутися до $ARGUMENTS, бо це найближче до знайомого їм світу bash. Це нормально для прототипів, але типізовані позиційні аргументи справді кращі, коли контракт стабільний. LLM не потрібно парсити $1 — це вже чистий рядок.

Приблизне емпіричне правило: якщо ви можете описати сигнатуру команди одним реченням англійською, не вживаючи слів «або» та «за бажанням», обирайте позиційні. Якщо ці слова потрібні — обирайте $ARGUMENTS.

Чи слеш-команди тепер те саме, що й навички?

Навесні 2026 року Anthropic об'єднала користувацькі команди в ширшу систему навичок, але файли .claude/commands/*.md досі працюють і використовують той самий фронтматер. Навичка — це каталог (.claude/skills/foo/SKILL.md плюс допоміжні файли) з додатковим керуванням викликом, як-от disable-model-invocation. Команда — це один файл .md. Ті самі правила підстановки, інше пакування.

Ось практична різниця:

Тож ні, .claude/commands/ не є застарілим. Anthropic свідомо зберегла працездатність файлової форми, коли об'єднала системи, — надто багато проєктів мають бібліотеки команд, зафіксовані в системі контролю версій. Якщо вам потрібні допоміжні файли (як-от довідка CONTRIBUTING.md, яку завантажує ваша навичка, або template.json, який вона копіює), обирайте навички. Інакше залишайтеся на командах.

Це об'єднання є частиною ширшого руху до відкритого стандарту agentskills.io, і це одна з кількох змін у v2.1.x, про які варто знати, — перегляньте наш огляд функцій Claude Code v2.1, щоб дізнатися про повний ландшафт функцій, і наш посібник з навичок для глибшого розбору навичок.

Чому мій $ARGUMENTS не підставляється? Виправлення типових помилок

П'ять типових причин, чому $ARGUMENTS не підставляється: (1) токен у нижньому регістрі або скорочений ($args, $ARGS, $arguments — має бути буквально $ARGUMENTS), (2) багатослівні аргументи не взято в лапки (/cmd hello world розбивається; /cmd "hello world" зберігає цілісність), (3) allowed-tools розділено комами замість пробілами, (4) файл команди не в .claude/commands/ або .claude/skills/, (5) сеанс Claude Code потрібно перезавантажити після редагування файлу.

$ARGUMENTS буквально з'являється у промпті LLM

Симптом: У відповіді моделі ваш промпт відображає $ARGUMENTS як звичайний текст, наче його проігнорували. Причина: Неправильний регістр або неправильне написання. Токен — це буквально $ARGUMENTS, вісім символів, усі великі літери. Виправлення: Відкрийте .md, виконайте grep для $args, $ARGS, $arguments, ${ARGUMENTS}, замініть на $ARGUMENTS. Помилка одруку $args хоча б раз траплялася з кожним розробником у нашій команді; це найпоширеніша помилка у сімействі «невідома слеш-команда».

Багатослівний аргумент несподівано розділяється

Симптом: Ви виконали /migrate-component Search Bar React Vue, і $1 — це Search, $2 — це Bar. Причина: Пробіли розділяють позиційні аргументи. Виправлення: Візьміть багатослівний аргумент у лапки: /migrate-component "Search Bar" React Vue. Тепер $1 — це Search Bar. Це відповідає поведінці оболонки, яка є ментальною моделлю, яку використання свідомо відтворює.

allowed-tools не застосовується

Симптом: Команда виконується, але Claude відмовляється викликати інструменти, які, на вашу думку, ви додали до списку дозволених, або викликає інструменти, яких немає у списку. Причина: Елементи розділені комами замість пробілів. Виправлення: Замініть allowed-tools: Bash, Read, Edit на allowed-tools: Bash Read Edit. Для підшаблонів інструментів використовуйте формат Bash(git:*) Bash(npm:*) Read.

Команда не з'являється в автодоповненні /

Симптом: Ви вводите /, але вашої команди немає в списку. Причина: Неправильне розташування файлу, відсутній фронтматер або некоректно встановлено disable-model-invocation. Виправлення: Переконайтеся, що файл розташований за шляхом .claude/commands/yourcmd.md (або .claude/skills/yourcmd/SKILL.md) відносно кореня вашого проєкту. Переконайтеся, що фронтматер містить принаймні поле description:. Якщо ви встановили disable-model-invocation: true, команда не буде доступна іншим агентам, але все одно з'являтиметься в меню /, що відкривається при ручному введенні користувачем.

Ви відредагували файл .md, але нічого не змінилося

Симптом: Ви виправили баг, зберегли файл, знову запустили команду — а поведінка лишилася тією ж, хибною. Причина: Claude Code кешує файли команд на початку сесії. Рішення: Вийдіть із Claude Code і запустіть його знову або виконайте /reload, якщо ваша версія це підтримує.

Claude Code зчитує файли .md на початку сесії. Якщо ви відредагували команду, а вона «не змінюється», перезапустіть сесію, перш ніж припускати серйозніший баг.

Для крайніх випадків, що виходять за межі цих п'яти, найкращим місцем для пошуку є розділ issues репозиторію Claude Code. Більшість дивних багів підстановки, які ми бачили, є тим чи іншим різновидом одного з описаних вище.

Часті запитання: Аргументи слеш-команд у Claude Code

Як передати аргументи слеш-команді Claude Code?

Введіть рядок аргументів після назви команди: /greet World. У файлі .md вашої команди посилайтеся на значення як $ARGUMENTS (увесь рядок), $1 (перший позиційний аргумент) або $variableName (якщо ви оголосили arguments: [variableName] у фронтматері). Користувач підставляє токен перед надсиланням запиту до LLM.

Що таке $ARGUMENTS у Claude Code?

$ARGUMENTS — це токен підстановки у файлах користувацьких слеш-команд, який Claude Code замінює на весь рядок аргументів, введений користувачем після назви команди. Якщо користувач виконує /deploy --staging --dry-run, то $ARGUMENTS перетворюється на буквальний рядок --staging --dry-run усередині сформованого промпту ще до того, як його побачить LLM.

Чи можуть слеш-команди Claude Code приймати прапорці у стилі CLI, як-от --json?

Нативно — ні, use не має парсера прапорців для користувацьких команд. Ви записуєте --json у $ARGUMENTS, а ваш промпт інструктує LLM розпізнавати його та діяти відповідно. Це працює, тому що Claude гнучко інтерпретує структурований текст. Вбудовані команди, як-от /clear і /help, мають справжні прапорці, але користувацькі команди, які ви створюєте, підпорядковуються правилам лише підстановки.

Яка різниця між $1, $ARGUMENTS та $name у Claude Code?

$1 — це перший позиційний аргумент, розділений пробілами ($2 — другий, і так далі). $ARGUMENTS — це весь рядок аргументів дослівно, включно з усіма позиційними частинами та будь-якими прапорцями. $name — це іменований аргумент, оголошений у полі arguments: [name] фронтматеру, корисний, коли потрібні самодокументовані позиційні слоти без числової індексації.

Як працює argument-hint у Claude Code?

argument-hint — це поле frontmatter, яке визначає, що відображає меню автодоповнення / поруч із назвою вашої команди. Якщо вказати argument-hint: <issue-number> [--priority high], саме такий шаблон з'явиться після того, як користувач введе /. Це впливає лише на UX — поле не перевіряє й не розбирає аргументи. Його все одно варто задавати, адже це найдешевша документація, яку ви будь-коли напишете.

Як створити власну слеш-команду з кількома аргументами?

Є два лаконічні варіанти. Для позиційних: посилайтеся на $1, $2, $3 у тілі промпту. Для іменованих: оголосіть arguments: [first, second, third] у фронтматері та посилайтеся на $first, $second, $third. Іменовані краще читаються, коли аргументів три або більше. Використовуйте $ARGUMENTS лише тоді, коли хочете, щоб LLM розбирала довільний завершальний рядок після обов'язкових позиційних слотів.

Чи застаріло .claude/commands/ на користь .claude/skills/?

Ні. Anthropic об'єднала ці дві системи навесні 2026 року, але явно зберегла роботу .claude/commands/*.md з ідентичними правилами підстановки. Використовуйте команди для однофайлових автоматизацій, а навички — для багатофайлових наборів (SKILL.md плюс шаблони або посилання). Той самий frontmatter, та сама поведінка $ARGUMENTS, лише інше пакування. Обидва варіанти є повноцінними, починаючи з версії v2.1.126.

Чому $ARGUMENTS не підставляється в моїй команді?

Три найпоширеніші причини за частотою: помилка регістру (має бути великими літерами $ARGUMENTS, а не $args чи $arguments), неправильне розташування файлу (має зберігатися в .claude/commands/ або .claude/skills/) або застаріла сесія (Claude Code зчитує файли команд на початку сесії, тож перезапустіть після редагування). Якщо всі три пункти в порядку, виконайте /echo-args foo з мінімальним прикладом із H2 #1, щоб локалізувати проблему.

Чи можу я вимагати певні аргументи?

На рівні використання — ні, нативної валідації обов'язкових аргументів не існує. Патерн полягає в тому, щоб дати LLM інструкцію у вашому промпті: «Якщо $1 порожній, зупинись і скажи користувачеві надати номер проблеми.» Модель забезпечує дотримання контракту. Це не ідеальний захист, але на практиці достатньо надійно для щоденного використання, особливо в поєднанні з чітким argument-hint.

Чи перевизначає model: у frontmatter прапорці CLI?

Так, frontmatter має пріоритет. Якщо у файлі команди оголошено model: claude-haiku-4, ця команда виконується на Haiku незалежно від того, яку модель користувач обрав для сесії. Це корисно для дешевих команд, які часто викликаються і які ви хочете тримати подалі від Opus. Дивіться наш посібник із перемикання моделей Claude, щоб обрати правильний варіант для кожного типу команд.

Підсумки

Чотири патерни. Виберіть той, що відповідає формі вашої команди:

• Булевий прапорець (--dry-run) — запишіть його в $ARGUMENTS і дозвольте LLM виявити його.
• Прапорець зі значенням (--filter <pattern>) — той самий підхід: LLM витягує значення.
• Обов'язковий позиційний + необов'язковий прапорець — $1 для обов'язкового, $ARGUMENTS для решти.
• Строго позиційний — $0/$1/$2 (або іменовані через arguments:), коли кожен слот є обов'язковим і впорядкованим.

Тепер, коли ваші команди стали параметричними, наступний крок — інтегрувати їх у робочі процеси агента. Почніть з нашого посібника з Claude Skills про пакування у багатофайлові структури, або перегляньте альтернативні інструменти для програмування з ШІ, якщо порівнюєте різні оболонки. У будь-якому разі ваша папка .claude/commands/ щойно стала набагато кориснішою.