Lesson 12Claude Skills

Pass Arguments to Skills

Skills become far more reusable when they accept arguments — text, filenames, flags, or named parameters typed inline after the slash command. Claude reads what the user types and your SKILL.md instructions tell it how to interpret each part.

inline argumentsnamed parametersdefaultsdescription: Usagereal examples

How argument passing works

Claude skills don't have a formal argument parser — Claude itself reads everything the user types after the slash command and interprets it according to your instructions. Your SKILL.md tells Claude what to expect and how to use each piece.

/translate "Hello world" from=en to=fr
Slash command
/translate
Activates the skill
Positional input
"Hello world"
The text to process
Named param
from=en
Source language
Named param
to=fr
Target language
ℹ️ Info: There is no built-in argument parser in Claude skills. Claude reads the full line and your ## Steps tell it which part is which. Naming your arguments clearly (e.g. from=, to=) makes parsing reliable and predictable.

Three ways to pass arguments

Positional — text after the command
> /commit "add login page"
Skill reads: “Read the text after /commit as the subject hint.”
Best for a single main input like text to translate or a subject hint.
Named — key=value pairs
> /translate "Hi" from=en to=es
Skill reads: “Read the from= and to= arguments separately.”
Best when you have two or more distinct inputs.
Flags — keywords that switch behaviour
> /review critical src/auth.py
Skill reads: “If first word is "critical", filter to Critical findings only.”
Best for mode switches: verbose, silent, strict, etc.

Example 1 — /translate with named parameters

The description field is where you document the argument syntax — Claude and auto-detection both read it. The ## Steps section tells Claude how to parse each argument.

~/.claude/skills/translate/SKILL.md
---
name: translate
description: >
  Translate text between languages.
  Usage: /translate <text> from=<lang> to=<lang>
  Example: /translate "Hello world" from=en to=fr
  Outputs a single translated string with a brief note on tone.
---

## Role
You are a professional translator. Preserve tone and meaning precisely.

## Steps
1. Read the text the user provides after the command.
2. Identify the source language (from= argument, or detect automatically).
3. Translate to the target language (to= argument).
4. If tone differs from the original (formal vs casual), note it briefly.

## Output format
Return the translated text on the first line.
If tone differs, add one line: "Note: adjusted from [X] to [Y] register."

## Constraints
- Do not explain the grammar or vocabulary unless asked.
- Keep the output to the translation + optional tone note only.
claude.ai — chat
/translate "Good morning, have a great day!" from=en to=ja
✦
おはようございます、素晴らしい一日を！
Note: adjusted to polite (敬語) register for general use.
✅ from=en parsed✅ to=ja parsed✅ tone note added

Example 2 — /commit with an optional hint

Arguments can be optional. When the user types /commit alone, Claude generates the message from staged changes. When the user adds a hint like"login page", Claude uses it as the subject. Document both forms in the description.

~/.claude/skills/commit/SKILL.md
---
name: commit
description: >
  Write a Conventional Commit message from staged changes.
  Usage: /commit [optional: scope or short description hint]
  Example: /commit  or  /commit "login page"
  Outputs a single commit message line + optional body.
---

## Steps
1. Read the user's hint if provided (text after /commit).
2. Use the hint as the scope or subject when composing the message.
3. Format: type(scope): short description
4. Add a body paragraph only for complex changes.

## Output format
Single line: feat(auth): add login page
Optional body: blank line + one paragraph.
Without argument
> /commit
feat(auth): add email verification flow
Adds a two-step email verification on signup.
Tokens expire after 24 h.
With hint argument
> /commit "login page"
feat(ui): add login page
Introduces the new login screen with email/
password fields and a "remember me" toggle.

Example 3 — /review with a severity flag and filename

Flags change the skill's mode of operation. Here, the first argument selects severity level and the second is the filename. Both are optional — the skill defaults gracefully when they are missing.

~/.claude/skills/review/SKILL.md
---
name: review
description: >
  Review code at a specific severity level.
  Usage: /review [critical|all] [filename]
  Example: /review critical src/auth.py
  Outputs findings filtered to the requested severity.
---

## Steps
1. Read the severity argument (first word after /review): "critical" or "all".
2. Read the filename if provided as the second argument.
3. Review the file or the pasted code.
4. Filter output to the requested severity level.

## Output format
Use the standard severity headings (🔴 Critical / 🟡 Warning / 🔵 Style).
Skip sections that have zero findings.
End with: X findings at [severity] level.

## Constraints
- If severity argument is missing, default to "all".
- If filename is missing, prompt the user to paste code.
# Flag + filename — only shows Critical findings in auth.py
> /review critical src/auth.py
🔴 Critical (2)
└─ Line 42 — SQL query built with f-string. Use parameterised queries.
└─ Line 89 — JWT_SECRET hardcoded. Move to environment variable.
2 findings at critical level.
# No arguments — defaults to all severities
> /review
Please paste the code you'd like me to review.

Always document arguments in the description

The description field is read by Claude during auto-detection and by users who run /help. Use a consistent three-line format: what it does, usage syntax, and an example.

Line in descriptionPurposeExample
What it doesOne sentence — what the skill produces"Translate text between any two languages."
Usage:Argument pattern with <required> and [optional]"Usage: /translate <text> from=<lang> to=<lang>"
Example:A concrete invocation for the user to copy"Example: /translate \"Hi\" from=en to=fr"
Outputs:Shape of the response"Outputs: translated text + optional tone note."

Always define defaults for optional arguments

If an argument is optional, your ## Steps or ## Constraints must say what Claude should do when it is absent. Without a default, Claude will ask the user — or guess — which leads to inconsistent behaviour.

❌ No default
# In ## Steps:
1. Read the severity argument.
2. Filter findings by severity.
If user types just /review, Claude guesses or asks — inconsistent.
✅ With default
# In ## Steps:
1. Read the severity argument if present.
Default to "all" if not provided.
2. Filter findings by severity.
Claude always knows what to do — consistent output every time.
💡 Tip: Keep argument syntax simple. If you find yourself designing more than three arguments, consider splitting the skill into two focused skills instead — skills with fewer arguments are easier to invoke correctly and easier to test.

What's Next

Arguments make skills flexible. The next lesson goes further — using dynamic context to inject live information into your skill at runtime.