Feature Request: Formalize Custom Slash Commands with Structured Definitions and Model-Led Argument Parsing

Title: Feature Request: Formalize Custom Slash Commands with Structured Definitions and Model-Led Argument Parsing

Labels: feature-request, enhancement, slash-commands, developer-experience

Summary

This proposal outlines a significant enhancement to the custom slash command system. By migrating from the current Markdown-based definitions to a structured format (e.g., TOML or YAML) and implementing a more powerful, dual-mode argument handling system, we can dramatically improve the feature's usability, discoverability, and power. This would elevate custom commands from simple shortcuts to a cornerstone of personal and team-based workflow automation.

1. Problem Statement: Current Limitations

The current custom slash command system, as detailed in the official documentation, is effective for simple use cases but has key limitations that hinder its potential.

• Source Documentation:
• Slash Commands (en/docs/claude-code/slash-commands): Describes the file-based discovery (.claude/commands/, ~/.claude/commands/) and basic command creation.
• Common Workflows (en/docs/claude-code/common-workflows): Provides a practical example of creating a custom command (fix-issue.md) using the single $ARGUMENTS placeholder.

• Identified Limitations:

1. Lack of Formal Metadata: Defining commands in .md files without a formal structure prevents the inclusion of machine-readable metadata. There is no standard way to specify a description, argument-hint, or allowed-tools. This makes it impossible for the /help menu to display useful information, harming discoverability and making commands harder to use, especially in shared team repositories.
2. Inflexible Argument Handling: The single $ARGUMENTS placeholder performs a direct string replacement. While simple, this is not flexible enough for commands that could benefit from multiple arguments, flags, or more sophisticated, model-led parsing of natural language input.

2. Proposed Solution: A Two-Part Enhancement

This proposal, inspired by the robust implementation in tools like Google's Gemini CLI, suggests a comprehensive upgrade.

Part A: Structured Command Definitions

We propose moving command definitions from .md files to a structured format like TOML. This allows for explicit, machine-readable metadata and a cleaner, more maintainable structure.

• Discovery: The file-based discovery mechanism can remain the same (.claude/commands/, ~/.claude/commands/), with subdirectories creating namespaces (e.g., .claude/commands/git/commit.toml becomes /git:commit).

• Example TOML Command File (fix-issue.toml):

```toml
# A short description that will appear in the /help menu.
description = "Finds and fixes a GitHub issue by its number."

# A hint for users shown during autocompletion.
argument-hint = "<issue-number>"

# A list of tools the command can use without prompting (if already approved).
allowed-tools = ["Read", "Edit", "Bash(npm run test:*)"]

# The prompt to be sent to Claude. The {{args}} placeholder is used for direct injection.
prompt = """
Find and fix issue #{{args}}. Please follow these steps:

1. Understand the issue described in the ticket.
2. Locate the relevant code in our codebase.
3. Implement a solution that addresses the root cause.
4. Add appropriate tests.
5. Prepare a concise PR description for the changes.

"""
```

Part B: Flexible, Dual-Mode Argument Processing

The core of this proposal is to allow two distinct modes for handling arguments, determined by the content of the prompt field.

Mode 1: Shorthand Injection (Simple, Templated Commands)

• Trigger: The prompt string contains a specific placeholder, such as {{args}}.
• Behavior: The CLI performs a direct, literal replacement of {{args}} with all text following the user's command. This preserves the simplicity of the current system for straightforward commands.
• Example Usage:
• User types: /fix-issue 123
• In the prompt, {{args}} is replaced with 123.

Mode 2: Model-Led Parsing (Advanced, Multi-Argument Commands)

• Trigger: The prompt string does not contain the {{args}} placeholder.
• Behavior: The CLI appends the user's entire raw command line to the end of the prompt. This empowers the model to perform its own sophisticated parsing of multiple arguments, flags, or natural language.
• Example Command File (changelog.toml):

``toml
description = "Generates a changelog entry from structured input."
prompt = """
# Task: Update Changelog
You are an expert maintainer. A user has invoked a command to add a new entry to the project changelog.
Your task is to parse the <version>, <type>, and <message> from the user's raw command line, which is appended below.
Use the Write tool to update the CHANGELOG.md file, adhering to the "Keep a Changelog" format.
"""
``

• Example Usage:
• User types: /changelog 1.2.0 added "New feature for model-led parsing"
• Final Prompt Sent to Claude:

``
# Task: Update Changelog
You are an expert maintainer. A user has invoked a command to add a new entry to the project changelog.
Your task is to parse the <version>, <type>, and <message> from the user's raw command line, which is appended below.
Use the Write tool to update the CHANGELOG.md` file, adhering to the "Keep a Changelog" format.

/changelog 1.2.0 added "New feature for model-led parsing"
```

3. Rationale & Benefits

• Improved Discoverability & Usability: Structured definitions allow the /help command to become a rich, informative discovery tool for all custom commands, displaying descriptions and argument hints.
• Enhanced Power and Flexibility: The dual-mode argument system supports everything from simple text-replacement shortcuts to complex, multi-argument automated workflows, leveraging the model's natural language understanding.
• Superior Maintainability: A structured format like TOML is cleaner, more self-documenting, and easier to manage for a growing library of commands, especially for teams sharing a .claude/commands directory.
• Extensibility: The TOML format can be easily extended with new metadata in the future (e.g., timeout, author) without breaking changes.
• Backward Compatibility: The logic is designed to be fully backward-compatible. Existing .md files can continue to work as they do today, with the system prioritizing the new .toml format if both exist for the same command name.

4. Implementation Reference

A successful implementation of this pattern can be seen in Google's Gemini CLI. Reviewing their FileCommandLoader.ts may provide a useful architectural reference.
Reference: google-gemini/gemini-cli/blob/main/packages/cli/src/services/FileCommandLoader.ts