[DOCS] Clarify support for positional arguments ($1, $2, etc.) in Agent Skills

Documentation Type

Missing documentation (feature not documented)

Documentation Location

• https://code.claude.com/docs/en/skills - https://code.claude.com/docs/en/slash-commands

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 separate SlashCommand tool. This has been merged into the Skill tool.

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:

1. Parity: It is unclear if model-invoked Skills (which are now handled by the same underlying tool as Slash Commands) support the same $1, $2 positional substitutions that Slash Commands do.
2. 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.
3. 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.md files.

Suggested Improvement

Update the "Available string substitutions" table in docs/en/skills.md to either:

• Include $1, $2, ... $N with 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 $1 for a filename and $2 for a mode) over. Without documentation, this leads to trial-and-error debugging of model outputs.