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:

# 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:

# ❌ 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:

---
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:

# 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:

# ✓ 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:

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:

---
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:

---
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

# 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

---
description: Test bash
allowed-tools: Bash(echo:*)
---

!echo "Bash works"

Result above should show "Bash works"

Test File Loading

---
description: Test file loading
---

Content from @package.json

Above should show package.json content

Verify Command Registration

# List all commands
/help

# Look for your command in the list

Getting Help

If problems persist:

1. Check Official Documentation
2. Review command file syntax carefully
3. Test with minimal example first
4. Verify Claude Code version supports features