chore: Archive update-slash-commands-session change
- Move change to archive/2025-12-24-update-slash-commands-session - Create specs/slash-commands/spec.md with 10 requirements
This commit is contained in:
Luong NGUYEN
@@ -0,0 +1,33 @@
|
||||
# Change: Update Slash Commands Documentation
|
||||
|
||||
## Why
|
||||
|
||||
The current slash commands documentation in `01-slash-commands/README.md` is outdated compared to the official Claude Code documentation at https://code.claude.com/docs/en/slash-commands. Several new features, built-in commands, and capabilities have been added that users should know about.
|
||||
|
||||
## What Changes
|
||||
|
||||
### Documentation Updates
|
||||
|
||||
- **Add comprehensive built-in commands table** - Document all 40+ built-in slash commands with their purposes
|
||||
- **Update custom command features** - Document new argument handling (`$ARGUMENTS`, `$1`, `$2`, etc.)
|
||||
- **Add bash execution syntax** - Document the `!` prefix for executing bash commands within slash commands
|
||||
- **Update frontmatter fields** - Document `allowed-tools`, `argument-hint`, `description`, `model`, `disable-model-invocation`
|
||||
- **Add file reference syntax** - Document the `@` prefix for including file contents
|
||||
- **Add Plugin commands section** - Document `/plugin-name:command-name` pattern
|
||||
- **Add MCP slash commands section** - Document `/mcp__<server-name>__<prompt-name>` pattern
|
||||
- **Add SlashCommand Tool section** - Document programmatic invocation from Claude
|
||||
- **Add Skills vs Slash Commands comparison** - Help users choose the right tool
|
||||
|
||||
### Example Updates
|
||||
|
||||
- Add example command with bash execution (`!git status`)
|
||||
- Add example with file references (`@src/utils/helpers.js`)
|
||||
- Add example with complete frontmatter
|
||||
- Update existing examples to use official syntax
|
||||
|
||||
## Impact
|
||||
|
||||
- Affected specs: `slash-commands` (new capability spec to be created)
|
||||
- Affected code: `01-slash-commands/README.md`, potentially new example files
|
||||
- No breaking changes - additive documentation improvements
|
||||
- Benefits all users learning about Claude Code slash commands
|
||||
@@ -0,0 +1,147 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Slash Command Types Documentation
|
||||
|
||||
The documentation SHALL describe the four types of slash commands:
|
||||
1. Built-in commands provided by Claude Code
|
||||
2. Custom user-defined commands (project and personal)
|
||||
3. Plugin commands
|
||||
4. MCP (Model Context Protocol) slash commands
|
||||
|
||||
#### Scenario: User learns about command types
|
||||
- **WHEN** a user reads the slash commands documentation
|
||||
- **THEN** they understand the different types of slash commands available
|
||||
- **AND** they know when to use each type
|
||||
|
||||
---
|
||||
|
||||
### Requirement: Built-in Commands Reference
|
||||
|
||||
The documentation SHALL include a comprehensive reference table of all built-in slash commands with their purposes, including but not limited to:
|
||||
- `/add-dir` - Add additional working directories
|
||||
- `/agents` - Manage custom AI subagents
|
||||
- `/clear` - Clear conversation history
|
||||
- `/compact` - Compact conversation with optional focus instructions
|
||||
- `/config` - Open Settings interface
|
||||
- `/context` - Visualize current context usage
|
||||
- `/cost` - Show token usage statistics
|
||||
- `/doctor` - Check installation health
|
||||
- `/export` - Export conversation to file or clipboard
|
||||
- `/help` - Get usage help
|
||||
- `/hooks` - Manage hook configurations
|
||||
- `/init` - Initialize project with CLAUDE.md
|
||||
- `/mcp` - Manage MCP server connections
|
||||
- `/memory` - Edit CLAUDE.md memory files
|
||||
- `/model` - Select or change AI model
|
||||
- `/permissions` - View or update permissions
|
||||
- `/resume` - Resume conversation by ID or name
|
||||
- `/review` - Request code review
|
||||
- `/sandbox` - Enable sandboxed bash tool
|
||||
- `/vim` - Enter vim mode
|
||||
|
||||
#### Scenario: User finds built-in command
|
||||
- **WHEN** a user needs to perform a common operation
|
||||
- **THEN** they can find the appropriate built-in command in the reference table
|
||||
- **AND** they understand what the command does
|
||||
|
||||
---
|
||||
|
||||
### Requirement: Argument Handling
|
||||
|
||||
The documentation SHALL explain both argument handling methods:
|
||||
1. `$ARGUMENTS` - Receives all arguments as a single string
|
||||
2. `$1`, `$2`, `$3`, etc. - Individual positional arguments
|
||||
|
||||
#### Scenario: User uses $ARGUMENTS placeholder
|
||||
- **WHEN** a user creates a command with `$ARGUMENTS` placeholder
|
||||
- **AND** invokes it with `/fix-issue 123 high-priority`
|
||||
- **THEN** `$ARGUMENTS` contains "123 high-priority"
|
||||
|
||||
#### Scenario: User uses positional arguments
|
||||
- **WHEN** a user creates a command with `$1`, `$2`, `$3` placeholders
|
||||
- **AND** invokes it with `/review-pr 456 high alice`
|
||||
- **THEN** `$1` is "456", `$2` is "high", `$3` is "alice"
|
||||
|
||||
---
|
||||
|
||||
### Requirement: Bash Command Execution
|
||||
|
||||
The documentation SHALL explain the `!` prefix for executing bash commands within slash command files before the command runs.
|
||||
|
||||
#### Scenario: User includes dynamic context
|
||||
- **WHEN** a user adds `!git status` in their command file
|
||||
- **THEN** the git status output is included in the command context
|
||||
- **AND** Claude receives the current repository state
|
||||
|
||||
---
|
||||
|
||||
### Requirement: File Reference Syntax
|
||||
|
||||
The documentation SHALL explain the `@` prefix for including file contents in slash commands.
|
||||
|
||||
#### Scenario: User references a file
|
||||
- **WHEN** a user adds `@src/utils/helpers.js` in their command file
|
||||
- **THEN** the contents of that file are included in the command context
|
||||
|
||||
---
|
||||
|
||||
### Requirement: Frontmatter Fields
|
||||
|
||||
The documentation SHALL document all supported frontmatter fields:
|
||||
- `allowed-tools` - List of tools the command can use
|
||||
- `argument-hint` - Expected arguments for auto-completion
|
||||
- `description` - Brief description of the command
|
||||
- `model` - Specific model to use for this command
|
||||
- `disable-model-invocation` - Prevent SlashCommand tool from calling this command
|
||||
|
||||
#### Scenario: User creates command with frontmatter
|
||||
- **WHEN** a user creates a command with frontmatter fields
|
||||
- **THEN** Claude Code respects those configuration options
|
||||
- **AND** the command behaves according to the specified settings
|
||||
|
||||
---
|
||||
|
||||
### Requirement: Plugin Commands Documentation
|
||||
|
||||
The documentation SHALL explain the plugin command format: `/plugin-name:command-name` or simply `/command-name` when there are no naming conflicts.
|
||||
|
||||
#### Scenario: User invokes plugin command
|
||||
- **WHEN** a user types `/frontend-design:frontend-design`
|
||||
- **THEN** the corresponding plugin command executes
|
||||
|
||||
---
|
||||
|
||||
### Requirement: MCP Slash Commands Documentation
|
||||
|
||||
The documentation SHALL explain the MCP slash command format: `/mcp__<server-name>__<prompt-name> [arguments]`
|
||||
|
||||
#### Scenario: User invokes MCP command
|
||||
- **WHEN** a user types `/mcp__github__list_prs`
|
||||
- **THEN** the MCP server's prompt is executed
|
||||
|
||||
---
|
||||
|
||||
### Requirement: SlashCommand Tool Documentation
|
||||
|
||||
The documentation SHALL explain how Claude can programmatically invoke slash commands using the SlashCommand tool, including:
|
||||
- How to enable this via prompt or CLAUDE.md references
|
||||
- How to disable via permissions
|
||||
- The character budget limit (default 15,000, configurable via `SLASH_COMMAND_TOOL_CHAR_BUDGET`)
|
||||
|
||||
#### Scenario: User enables programmatic invocation
|
||||
- **WHEN** a user adds "Run /write-unit-test when writing tests" to CLAUDE.md
|
||||
- **THEN** Claude can automatically invoke that command when appropriate
|
||||
|
||||
---
|
||||
|
||||
### Requirement: Skills vs Slash Commands Comparison
|
||||
|
||||
The documentation SHALL include a comparison table helping users choose between Skills and Slash Commands based on:
|
||||
- Best use cases for each
|
||||
- File structure differences
|
||||
- Invocation method (explicit vs automatic)
|
||||
- Complexity level
|
||||
|
||||
#### Scenario: User decides between skill and command
|
||||
- **WHEN** a user needs to create a reusable capability
|
||||
- **THEN** they can use the comparison to decide whether a slash command or skill is more appropriate
|
||||
@@ -0,0 +1,42 @@
|
||||
## 1. Documentation Structure Updates
|
||||
|
||||
- [x] 1.1 Add "Types of Slash Commands" section with overview of built-in, custom, plugin, and MCP commands
|
||||
- [x] 1.2 Create comprehensive built-in commands reference table (40+ commands)
|
||||
- [x] 1.3 Update custom commands section with new features
|
||||
|
||||
## 2. Custom Command Features
|
||||
|
||||
- [x] 2.1 Document `$ARGUMENTS` placeholder for all arguments
|
||||
- [x] 2.2 Document individual argument placeholders (`$1`, `$2`, `$3`, etc.)
|
||||
- [x] 2.3 Document bash execution with `!` prefix (e.g., `!git status`)
|
||||
- [x] 2.4 Document file references with `@` prefix (e.g., `@src/file.js`)
|
||||
- [x] 2.5 Document thinking mode trigger via keywords
|
||||
|
||||
## 3. Frontmatter Updates
|
||||
|
||||
- [x] 3.1 Update frontmatter section with official fields
|
||||
- [x] 3.2 Document `allowed-tools` field with examples
|
||||
- [x] 3.3 Document `argument-hint` field for auto-completion
|
||||
- [x] 3.4 Document `description` field
|
||||
- [x] 3.5 Document `model` field for specific model selection
|
||||
- [x] 3.6 Document `disable-model-invocation` field
|
||||
|
||||
## 4. New Sections
|
||||
|
||||
- [x] 4.1 Add "Plugin Commands" section with `/plugin-name:command-name` pattern
|
||||
- [x] 4.2 Add "MCP Slash Commands" section with `/mcp__<server-name>__<prompt-name>` pattern
|
||||
- [x] 4.3 Add "SlashCommand Tool" section for programmatic invocation
|
||||
- [x] 4.4 Add "Skills vs Slash Commands" comparison table
|
||||
|
||||
## 5. Example Files
|
||||
|
||||
- [x] 5.1 Create new example showing bash execution feature (commit.md)
|
||||
- [x] 5.2 Create new example showing file references (commit.md includes @package.json example in README)
|
||||
- [x] 5.3 Update existing examples to use official frontmatter format (removed name/tags, added allowed-tools)
|
||||
- [x] 5.4 Add commit command example (from official docs)
|
||||
|
||||
## 6. Validation
|
||||
|
||||
- [x] 6.1 Verify all links work correctly
|
||||
- [x] 6.2 Test example commands format
|
||||
- [x] 6.3 Review for consistency with official documentation
|
||||
Reference in New Issue
Block a user