Custom Command File Rules

Beginner

Standards for creating custom slash commands in .claude/commands/ — naming conventions, prompt structure, parameter handling, and documentation requirements for team consistency.

File Patterns

**/.claude/commands/**

This rule applies to files matching the patterns above.

Rule Content

rule-content.md

# Custom Command File Rules

## Rule
All custom slash commands MUST be markdown files in `.claude/commands/` with clear prompt text, output format instructions, and parameter documentation.

## File Naming
```
.claude/commands/
  review-pr.md           # verb-noun, kebab-case
  scaffold-component.md  # descriptive action
  deploy-check.md        # clear purpose
```

### Good Names
```
review-pr.md
scaffold-component.md
fix-types.md
write-tests.md
explain-code.md
```

### Bad Names
```
r.md              # Too short, unclear
mycommand.md      # Not descriptive
doStuff.md        # camelCase, vague
helper.md         # What does it help with?
```

## Prompt Structure

### Good — Specific and Structured
```markdown
Review the current git diff against main. For each file changed, check:

1. **Type Safety**: No \`any\` types, proper null handling, exhaustive switches
2. **Error Handling**: All async operations wrapped in try/catch
3. **Performance**: No N+1 queries, no unnecessary re-renders
4. **Security**: No hardcoded secrets, proper input validation

Format output as:
- CRITICAL: [description] (file:line)
- WARNING: [description] (file:line)
- SUGGESTION: [description] (file:line)

End with a summary: X critical, Y warnings, Z suggestions.
```

### Bad — Vague and Unstructured
```markdown
Review the code and tell me if it's good.
```

## Parameter Usage
- Use `$ARGUMENTS` for user input: "Create a component named $ARGUMENTS"
- Document expected parameter format in a comment at the top
- Provide default behavior when no arguments given

## Output Format
Every command MUST specify the expected output format:
- Use structured formats (bullet lists, tables, sections)
- Include severity levels for review commands
- Specify file paths and line numbers where applicable

## Anti-Patterns
- Commands without output format instructions (inconsistent results)
- Overly long prompts (> 50 lines) — split into multiple commands
- Commands that duplicate built-in functionality (/review, /help)
- Missing parameter documentation

FAQ

Discussion

Loading comments...

# Custom Command File Rules ## Rule All custom slash commands MUST be markdown files in `.claude/commands/` with clear prompt text, output format instructions, and parameter documentation. ## File Naming ``` .claude/commands/ review-pr.md # verb-noun, kebab-case scaffold-component.md # descriptive action deploy-check.md # clear purpose ``` ### Good Names ``` review-pr.md scaffold-component.md fix-types.md write-tests.md explain-code.md ``` ### Bad Names ``` r.md # Too short, unclear mycommand.md # Not descriptive doStuff.md # camelCase, vague helper.md # What does it help with? ``` ## Prompt Structure ### Good — Specific and Structured ```markdown Review the current git diff against main. For each file changed, check: 1. **Type Safety**: No \`any\` types, proper null handling, exhaustive switches 2. **Error Handling**: All async operations wrapped in try/catch 3. **Performance**: No N+1 queries, no unnecessary re-renders 4. **Security**: No hardcoded secrets, proper input validation Format output as: - CRITICAL: [description] (file:line) - WARNING: [description] (file:line) - SUGGESTION: [description] (file:line) End with a summary: X critical, Y warnings, Z suggestions. ``` ### Bad — Vague and Unstructured ```markdown Review the code and tell me if it's good. ``` ## Parameter Usage - Use `$ARGUMENTS` for user input: "Create a component named $ARGUMENTS" - Document expected parameter format in a comment at the top - Provide default behavior when no arguments given ## Output Format Every command MUST specify the expected output format: - Use structured formats (bullet lists, tables, sections) - Include severity levels for review commands - Specify file paths and line numbers where applicable ## Anti-Patterns - Commands without output format instructions (inconsistent results) - Overly long prompts (> 50 lines) — split into multiple commands - Commands that duplicate built-in functionality (/review, /help) - Missing parameter documentation