claude-plugins/claude-code/skills/claude-commands/troubleshooting.md

# Troubleshooting Slash Commands

Common problems and solutions.

## Command Not Found

**Symptoms**: `/mycommand` shows "Command not found"

**Solutions**:
1. Verify file exists in `.claude/commands/` directory
2. Check filename ends with `.md` extension
3. Ensure filename matches command name (dash-separated)
4. Restart Claude Code to reload commands

**Example**:
```bash
# Wrong location
./commands/review.md

# Correct location
./.claude/commands/review.md

# Usage
/review @file.js
```

## Arguments Not Working

**Symptoms**: Variables like `$ARGUMENTS` appear literally in output

**Solutions**:
1. Use correct syntax: `$ARGUMENTS`, `$1`, `$2` (not `${ARGUMENTS}`)
2. Don't escape dollar signs in command files
3. Verify arguments are passed when invoking command

**Example**:
```markdown
# ❌ Wrong
Review these files: ${ARGUMENTS}

# ✓ Correct
Review these files: $ARGUMENTS
```

## Bash Commands Not Executing

**Symptoms**: `!git status` appears as text instead of executing

**Solutions**:
1. Add `allowed-tools` frontmatter with Bash specification
2. Use specific patterns, not wildcard `*` unless necessary
3. Ensure bash command is valid and available

**Example**:
```markdown
---
description: Git workflow
allowed-tools: Bash(git status:*), Bash(git diff:*)
---

!git status
!git diff --stat
```

## File References Not Loading

**Symptoms**: `@file.js` doesn't load file content

**Solutions**:
1. Use `@` prefix before file path
2. Verify file path is correct (relative to project root)
3. Check file exists and is readable
4. Combine with positional arguments: `@$1`

**Example**:
```markdown
# Direct reference
Review @src/main.js for issues

# With argument
Review @$1 for issues

# Usage: /review src/main.js
```

## Permission Errors

**Symptoms**: "Tool not allowed" or permission denied errors

**Solutions**:
1. Add required tools to `allowed-tools` frontmatter
2. Use specific patterns instead of broad permissions
3. Separate file paths from command patterns

**Example**:
```yaml
# ✓ Good - specific permissions
allowed-tools: Read(src/**), Bash(git status:*), Bash(git diff:*)

# ⚠️ Risky - too permissive
allowed-tools: *
```

## Command Timeout

**Symptoms**: Command hangs or times out

**Solutions**:
1. Avoid long-running processes in `!` commands
2. Use background processes if needed
3. Break into smaller commands
4. Consider using subagents for complex workflows

## Model Not Respecting Instructions

**Symptoms**: Claude doesn't follow command template

**Solutions**:
1. Use clear, imperative language
2. Number steps explicitly
3. Add constraints section
4. Use `model: claude-sonnet-4` for complex commands

**Example**:
```markdown
Review $ARGUMENTS

YOU MUST:
1. Check for X
2. Verify Y
3. Report Z

DO NOT:
- Skip any files
- Suggest changes without explanation
```

## Description Not Showing in /help

**Symptoms**: Command appears but no description

**Solutions**:
1. Verify frontmatter has `description` field
2. Check YAML syntax (no tabs, proper spacing)
3. Keep description under 100 characters for /help display

**Example**:
```yaml
---
description: Review code for security issues
---
```

## Argument Hints Not Working

**Symptoms**: Autocomplete doesn't show expected arguments

**Solutions**:
1. Add `argument-hint` to frontmatter
2. Use standard format: `<arg1> <arg2>`
3. Use descriptive names

**Example**:
```yaml
---
description: Generate tests
argument-hint: <file-path> <function-name>
---
```

## Commands Conflict with Built-ins

**Symptoms**: Custom command doesn't run, built-in does instead

**Solutions**:
1. Use different command name
2. Avoid names like `/help`, `/clear`, `/init`
3. Use descriptive, unique names

## Debugging Tips

### Test Basic Structure
```bash
# Create minimal test command
cat > .claude/commands/test.md << 'EOF'
---
description: Test command
---

Echo test: $ARGUMENTS
EOF

# Try it
/test hello world
# Should output: Echo test: hello world
```

### Test Bash Execution
```markdown
---
description: Test bash
allowed-tools: Bash(echo:*)
---

!echo "Bash works"

Result above should show "Bash works"
```

### Test File Loading
```markdown
---
description: Test file loading
---

Content from @package.json

Above should show package.json content
```

### Verify Command Registration
```bash
# List all commands
/help

# Look for your command in the list
```

## Getting Help

If problems persist:
1. Check [Official Documentation](https://docs.claude.com/en/docs/claude-code/slash-commands)
2. Review command file syntax carefully
3. Test with minimal example first
4. Verify Claude Code version supports features