153 lines
4.8 KiB
Markdown
153 lines
4.8 KiB
Markdown
<commands>
|
|
|
|
## Command Namespacing
|
|
|
|
Organize commands in subdirectories. Subdirectory names appear as labels but don't change invocation.
|
|
|
|
- `commands/command.md` → `/command`
|
|
- `commands/namespace/command.md` → `/command` (labeled with namespace)
|
|
|
|
## Command File Structure
|
|
|
|
Command files can contain optional frontmatter followed by the prompt content.
|
|
|
|
**Frontmatter (Optional but Recommended):**
|
|
|
|
```yaml
|
|
---
|
|
description: Brief description of what this command does
|
|
argument-hint: [issue-number] [priority]
|
|
allowed-tools: "Bash(git:*), Read, Write"
|
|
model: claude-3-5-haiku-20241022
|
|
disable-model-invocation: false
|
|
---
|
|
```
|
|
|
|
All frontmatter fields are optional:
|
|
- `description`: Brief description (defaults to first line of prompt). Include this for SlashCommand tool discovery.
|
|
- `argument-hint`: Expected arguments for auto-completion
|
|
- `allowed-tools`: Tools this command can use (inherits from conversation if omitted)
|
|
- `model`: Specific model to use (inherits from conversation if omitted)
|
|
- `disable-model-invocation`: Set to true to prevent SlashCommand tool from calling this command (defaults to false)
|
|
|
|
**Prompt Content:**
|
|
|
|
After frontmatter (or if no frontmatter), the markdown content becomes the prompt Claude receives.
|
|
|
|
Simple example:
|
|
```
|
|
Run the test suite and report any failures in the scratchpad.
|
|
```
|
|
|
|
Example with frontmatter:
|
|
```yaml
|
|
---
|
|
description: Fix GitHub issues following TDD workflow
|
|
argument-hint: [issue-number]
|
|
allowed-tools: "Bash(gh:*), Read, Write, Edit"
|
|
---
|
|
|
|
Analyze GitHub issue $ARGUMENTS and create a fix:
|
|
1. Use `gh issue view $ARGUMENTS` to read the issue
|
|
2. Identify the root cause
|
|
3. Implement a fix
|
|
4. Run tests to verify
|
|
```
|
|
|
|
## Argument Handling
|
|
|
|
Commands support two argument patterns:
|
|
|
|
**`$ARGUMENTS` - All arguments as single string:**
|
|
|
|
Captures everything after the command name as one value.
|
|
|
|
Example:
|
|
|
|
- Command file contains: `Fix issue $ARGUMENTS`
|
|
- Invocation: `/fix-issue 123 high-priority`
|
|
- Result: `$ARGUMENTS` becomes `123 high-priority`
|
|
- Claude receives: `Fix issue 123 high-priority`
|
|
|
|
**Positional Parameters (`$1`, `$2`, `$3`) - Individual arguments:**
|
|
|
|
Access specific arguments separately, like shell script parameters.
|
|
|
|
Example:
|
|
|
|
- Command file contains: `Review PR #$1 with priority $2 assigned to $3`
|
|
- Invocation: `/review-pr 456 high alice`
|
|
- Result: `$1` = `456`, `$2` = `high`, `$3` = `alice`
|
|
- Claude receives: `Review PR #456 with priority high assigned to alice`
|
|
|
|
**When to use each:**
|
|
|
|
- `$ARGUMENTS`: All input as single value (commit messages, search queries, issue numbers with descriptions)
|
|
- `$1, $2, $3`: Multiple distinct values (PR number + priority + assignee, file path + operation + output format)
|
|
|
|
## Special Command Features
|
|
|
|
**Bash Execution (`!` prefix):**
|
|
|
|
Execute bash commands before the slash command runs. The output is included in the command context.
|
|
|
|
Example:
|
|
|
|
```yaml
|
|
---
|
|
description: Analyze current git status and suggest next steps
|
|
allowed-tools: "Bash(git:*)"
|
|
---
|
|
|
|
Current git status:
|
|
!`git status --short`
|
|
|
|
Based on the above status, suggest what to do next.
|
|
```
|
|
|
|
Note: Requires `allowed-tools` frontmatter with Bash tool specified.
|
|
|
|
**File References (`@` prefix):**
|
|
|
|
Include file contents directly in the command context.
|
|
|
|
Example:
|
|
|
|
```markdown
|
|
Review the implementation in @src/auth/login.js and suggest improvements.
|
|
```
|
|
|
|
**Extended Thinking:**
|
|
|
|
Activate extended thinking by including relevant keywords in command definitions.
|
|
|
|
Example:
|
|
|
|
```markdown
|
|
Think deeply about the architecture implications of this change and analyze thoroughly before proposing a solution.
|
|
```
|
|
|
|
## Commands vs Other Formats
|
|
|
|
**Command vs Skill:** Command is a prompt stored in `.claude/commands/`, invoked explicitly with `/`. Skill is instructions in a folder, invoked automatically when Claude determines it's relevant.
|
|
|
|
**Command vs CLAUDE.md:** Command is a prompt you explicitly invoke when needed. CLAUDE.md is context automatically loaded at the start of every conversation.
|
|
|
|
**Command vs Just Typing:** Command saves typing for repeated prompts, shareable via git. Typing is appropriate for one-off requests or things you don't repeat.
|
|
|
|
## What Matters When Generating Command Prompts
|
|
|
|
When your prompt-writing skill generates a prompt for a command, it should:
|
|
|
|
**Understand the use case:** Is this a repeated workflow? Does it need parameters?
|
|
|
|
**Be complete:** The prompt should contain all instructions needed. Commands don't have special powers - they're just text that becomes Claude's input.
|
|
|
|
**Use $ARGUMENTS appropriately:** If the workflow needs input, use `$ARGUMENTS`. If it doesn't, don't include it.
|
|
|
|
**Be explicit:** Commands execute exactly as written. Don't assume Claude will infer missing steps.
|
|
|
|
**Consider prompting techniques:** Commands can use any prompting strategy (CoT, Few-Shot, XML, etc.) - they're just prompts in files.
|
|
|
|
</commands>
|