creating-command

# Custom Slash Command Best Practices

## Quick Start

**First, ask the user**:
- Where to create the command file?
  - `.claude/commands/` (project-scoped, shared via git)
  - `~/.claude/commands/` (user-scoped, personal across all projects)

Then create a `.md` file:
```markdown
---
description: Review code for security vulnerabilities
---

Review this code for:
- SQL injection risks
- XSS vulnerabilities
- Authentication issues
```

## Essential Features

### 1. Frontmatter

See [frontmatter.md](references/frontmatter.md) for complete reference.

```markdown
---
description: Brief, specific description
argument-hint: [arg1] [arg2]
allowed-tools: Bash(git:*), Read, Edit
model: claude-sonnet-4-5-20250929
---
```

### 2. Arguments

**All arguments**: `$ARGUMENTS`
```markdown
Fix issue #$ARGUMENTS following coding standards
```

**Positional**: `$1`, `$2`, etc.
```markdown
---
argument-hint: [pr-number] [priority]
---
Review PR #$1 with priority $2
```

### 3. Bash Execution

Use exclamation mark followed by backtick-quoted bash command (requires `allowed-tools: Bash(...)`)

Syntax: `!backtick` + bash command + `backtick`

Example:
```markdown
---
allowed-tools: Bash(git:*)
---
Status: !backtick git status backtick
Recent: !backtick git log --oneline -5 backtick
```

### 4. File References

Prefix: `@`
```markdown
Review @src/utils/auth.js for security issues
Compare @old-version.ts with @new-version.ts
```

## Best Practices

### DO

**Write specific descriptions**:
```yaml
# ✓ Good
description: Create git commit with Conventional Commits format

# ✗ Bad
description: Git helper
```

**Use argument hints**:
```yaml
argument-hint: [component-name] [type:functional|class]
```

**Scope tools appropriately**:
```yaml
# ✓ Good - specific commands only
allowed-tools: Bash(git add:*), Bash(git commit:*)

# ✗ Bad - too broad
allowed-tools: Bash(*)
```

**Keep commands focused**:
```markdown
# ✓ Good - one clear purpose
Create unit tests for the selected code

# ✗ Bad - multi