[DOCS] Clarify support for positional arguments ($1, $2, etc.) in Agent Skills
Documentation Type
Missing documentation (feature not documented)
Documentation Location
Section/Topic
The "Available string substitutions" section in the Agent Skills documentation and the "Skill tool" section in the Slash Commands documentation.
Current Documentation
The Agent Skills documentation under "Available string substitutions" lists only:
| Variable | Description | | :--- | :--- | |$ARGUMENTS| All arguments passed when invoking the Skill... | |${CLAUDE_SESSION_ID}| The current session ID... |
Meanwhile, the Slash Commands documentation explicitly details positional arguments:
Individual arguments with $1, $2, etc. Access specific arguments individually using positional parameters (similar to shell scripts)...
The Slash Commands page also notes:
In earlier versions of Claude Code, slash command invocation was provided by a separateSlashCommandtool. This has been merged into theSkilltool.
What's Wrong or Missing?
Since the SlashCommand tool and Agent Skills have been merged into a single Skill tool (as of v2.1.3), there is significant ambiguity regarding argument parsing for SKILL.md files:
- Parity: It is unclear if model-invoked Skills (which are now handled by the same underlying tool as Slash Commands) support the same
$1,$2positional substitutions that Slash Commands do. - Model Behavior: If supported, the documentation doesn't explain how the model is instructed to provide space-separated arguments to a Skill to satisfy positional variables versus the catch-all
$ARGUMENTS. - Usage Guidelines: If positional arguments are not supported for Skills (only for Slash Commands), the documentation should explicitly state this limitation to prevent developers from attempting to use them in
SKILL.mdfiles.
Suggested Improvement
Update the "Available string substitutions" table in docs/en/skills.md to either:
- Include
$1, $2, ... $Nwith an explanation of how the model parses space-separated strings into these variables. - Add a note explicitly stating that positional arguments are currently reserved for manually-invoked Slash Commands and that model-invoked Skills should rely on
$ARGUMENTS.
Additionally, update the Skill tool section in docs/en/slash-commands.md to clarify if the "merger" of these tools implies full feature parity for the Markdown files they reference.
Impact
High - Prevents users from using a feature
Additional Context
- Related Documentation: Slash Commands - Individual arguments
- Context: As developers move from simple Slash Commands to more complex Agent Skills, they often try to bring the same logic (like
$1for a filename and$2for a mode) over. Without documentation, this leads to trial-and-error debugging of model outputs.
4 Comments
Found 3 possible duplicate issues:
This issue will be automatically closed as a duplicate in 3 days.
🤖 Generated with Claude Code
Thank you for the updates regarding the merger of Slash Commands and Agent Skills. After reviewing the current documentation, I have assessed the status of the requested clarifications regarding argument parsing.
What’s FIXED
.claude/commands/and.claude/skills/./commands and that a skill entry (SKILL.md) takes precedence over a legacy command file.$ARGUMENTScatch-all placeholder to handle user input.What’s UNRESOLVED
$ARGUMENTSand${CLAUDE_SESSION_ID}. It remains entirely undocumented whether positional variables ($1,$2, etc.) function withinSKILL.mdfiles as they did in legacy slash commands./fix $1 --mode=$2) into theSKILL.mdformat.Conclusion
While the documentation successfully clarifies the architectural merger of these features, it remains technically incomplete regarding argument parsing parity. The core of my original request—documenting positional variable support and model behavior for those variables—has not been addressed.
I am keeping this issue open. To resolve this, the "Available string substitutions" table at https://code.claude.com/docs/en/skills must be updated to either define the behavior of
$1..$Nfor theSkilltool or explicitly state that these substitutions are deprecated in favor of the$ARGUMENTScatch-all for model-invoked skills.Issue #19355 Verification
Title: [DOCS] Clarify support for positional arguments ($1, $2, etc.) in Agent Skills
Issue Date: 2026-01-19
Verification Date: 2026-01-26
Status: RESOLVED
---
Issue Summary
This issue reported that the Agent Skills documentation was missing information about positional argument support (
$1,$2, etc.), while the Slash Commands documentation included this feature. Since slash commands and skills were merged into a singleSkilltool (as of v2.1.3), the reporter requested clarification on whether positional arguments work inSKILL.mdfiles.---
Verification Results
Claim 1: Skills documentation only lists
$ARGUMENTSand${CLAUDE_SESSION_ID}Status: RESOLVED
The "Available string substitutions" table in the Skills documentation now includes all four variable types:
From [skills.md:184-189](docs/code.claude.com/docs/en/skills.md#L184-L189):
Verdict: The documentation has been updated to include
$ARGUMENTS[N]and$Nshorthand.---
Claim 2: No examples showing positional argument usage in Skills
Status: RESOLVED
The Skills documentation now includes concrete examples demonstrating positional argument usage.
From [skills.md:303-325](docs/code.claude.com/docs/en/skills.md#L303-L325):
And the
$Nshorthand variant:The documentation explains: "Running
/migrate-component SearchBar React Vuereplaces$ARGUMENTS[0]withSearchBar,$ARGUMENTS[1]withReact, and$ARGUMENTS[2]withVue."Verdict: Clear examples with both syntaxes are now documented.
---
Claim 3: Ambiguity about feature parity after slash commands merged into skills
Status: RESOLVED
The documentation now explicitly shows that skills support the same positional argument substitutions. The "Pass arguments to skills" section ([skills.md:277-325](docs/code.claude.com/docs/en/skills.md#L277-L325)) provides comprehensive coverage of argument handling in skills.
Verdict: Feature parity is now documented with examples.
---
Current State
| Claim | Status |
|-------|--------|
|
$ARGUMENTS[N]missing from skills docs | RESOLVED ||
$Nshorthand missing from skills docs | RESOLVED || No examples of positional arguments | RESOLVED |
| Ambiguity about slash command merger | RESOLVED |
---
Suggested Fix
None required. The documentation has been updated to address all concerns raised in this issue.
---
References
$ARGUMENTS[N]and$Nexamples---
Conclusion & Recommendation
Primary Concern: Positional argument support (
$1,$2, etc.) was undocumented for Agent Skills after the slash command merger.Resolution Status: RESOLVED
Recommendation: CLOSE
The Skills documentation now includes complete coverage of positional arguments: the variable table lists
$ARGUMENTS[N]and$Nshorthand, and the "Pass arguments to skills" section provides working examples demonstrating both syntaxes.This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.