FoundryVTT/.claude/commands/.COMMANDS_TEMPLATE.md

---
description: Brief description of what this command does (shown in /help)
allowed-tools: Bash(git status:*), Bash(git add:*), Read(*)
# Optional: Explicitly declare which tools this command needs
# Format: Tool(pattern:*) or Tool(*)
# Examples:
# - Bash(git *:*) - Allow all git commands
# - Read(*), Glob(*) - Allow file reading and searching
# - Write(*), Edit(*) - Allow file modifications

argument-hint: [optional-parameter]
# Optional: Hint text showing expected arguments
# Appears in command autocompletion and help
# Examples: [file-path], [branch-name], [message]

disable-model-invocation: false
# Optional: Set to true if this is a simple prompt that doesn't need AI processing
# Use for commands that just display text or run simple scripts
---

# Command Template

Clear, concise instructions for Claude on what to do when this command is invoked.

## Technology Adaptation

**IMPORTANT**: This command adapts to the project's technology stack.

**Configuration Source**: [CLAUDE.md](../../CLAUDE.md)

Before executing, consult CLAUDE.md for:
- **Package Manager**: (npm, NuGet, pip, cargo, Maven) - Use correct install/test/build commands
- **Build Tool**: (dotnet, npm scripts, make, cargo) - Use correct build commands
- **Test Framework**: (xUnit, Jest, pytest, JUnit) - Use correct test commands
- **Language**: (C#, TypeScript, Python, Rust, Java) - Follow syntax conventions
- **Project Structure**: Navigate to correct paths for src, tests, config

## MCP Server Integration

**Available MCP Servers**: Leverage configured MCP servers for enhanced capabilities.

### Serena MCP

**Code Tools**: `find_symbol`, `find_referencing_symbols`, `get_symbols_overview`, `search_for_pattern`, `rename_symbol`

**Persistent Memory** (stored in `.serena/memories/`):
- `write_memory` - Store command findings, patterns, decisions
- `read_memory` - Recall past information
- `list_memories` - Browse all memories

Use for command-specific persistent knowledge.

### Memory MCP

**Temporary Context** (in-memory, cleared after session):
- `create_entities` - Track entities during command execution
- `create_relations` - Model relationships
- `add_observations` - Add details

Use for temporary command state.

### Other MCP Servers
- **context7**: Library documentation
- **fetch**: Web content
- **playwright**: Browser automation
- **windows-mcp**: Windows automation

## Arguments

If your command accepts arguments, explain how to use them:

**$ARGUMENTS** - All arguments passed to the command as a single string
**$1** - First positional argument
**$2** - Second positional argument
**$3** - Third positional argument, etc.

### Example Usage:

```
/command-name argument1 argument2 argument3
```

In the command file:
- `$ARGUMENTS` would be: "argument1 argument2 argument3"
- `$1` would be: "argument1"
- `$2` would be: "argument2"
- `$3` would be: "argument3"

## Instructions

Provide clear, step-by-step instructions for Claude:

1. **First step**: What to do first
   - Specific action or tool to use
   - Expected behavior

2. **Second step**: Next action
   - How to process information
   - What to check or validate

3. **Final step**: Output or result
   - Format for results
   - What to return to the user

## Expected Output

Describe the format and structure of the command's output:

```markdown
## Section Title
- Item 1
- Item 2

**Summary**: Key findings...
```

Or for code output:
```language
// Expected code format
output_example();
```

## Advanced Features

### Bash Execution

Execute shell commands directly:

```markdown
!ls -la
!git status
!npm test
```

Prefix commands with `!` to run them immediately.

### File References

Include file contents in the prompt:

```markdown
Review this file: @path/to/file.js
Compare these files: @file1.py @file2.py
```

Use `@` prefix to automatically include file contents.

### Conditional Logic

Add conditional instructions:

```markdown
If $1 is "quick":
  - Run fast analysis only
  - Skip detailed checks

If $1 is "full":
  - Run comprehensive analysis
  - Include all checks
  - Generate detailed report
```

## Examples

### Example 1: Basic Usage
```
/command-name
```
**Expected behavior**: Description of what happens

### Example 2: With Arguments
```
/command-name src/app.js detailed
```
**Expected behavior**: How arguments affect behavior

### Example 3: Advanced Usage
```
/command-name @file.js --option
```
**Expected behavior**: Combined features

## Best Practices

### When to Use This Command
- Scenario 1: When you need...
- Scenario 2: For tasks involving...
- Scenario 3: To quickly...

### Common Patterns

**Read then analyze:**
```markdown
1. Read the files in $ARGUMENTS
2. Analyze for [specific criteria]
3. Provide structured feedback
```

**Execute then report:**
```markdown
1. Run: !command $1
2. Parse the output
3. Summarize results
```

**Generate then write:**
```markdown
1. Generate [content type] based on $1
2. Write to specified location
3. Confirm completion
```

## Error Handling

Handle common issues gracefully:

```markdown
If no arguments provided:
  - Show usage example
  - Ask user for required input

If file not found:
  - List similar files
  - Suggest corrections

If operation fails:
  - Explain the error
  - Suggest next steps
```

## Integration with Other Features

### Works well with:
- **Hooks**: Can trigger pre/post command hooks
- **Subagents**: Can invoke specialized agents
- **Skills**: Commands can activate relevant skills
- **MCP Servers**: Can use MCP tools and resources

### Combine with tools:
```markdown
Use Read tool to load $1
Use Grep to search for $2
Use Edit to update findings
```

## Notes and Tips

- Keep commands focused on a single task
- Use descriptive names (verb-noun pattern)
- Document all arguments clearly
- Provide helpful examples
- Consider error cases
- Test with team members

---

## Template Usage Guidelines

### Naming Commands

**Good names** (verb-noun pattern):
- `/review-pr` - Review pull request
- `/generate-tests` - Generate unit tests
- `/check-types` - Check TypeScript types
- `/update-deps` - Update dependencies

**Poor names**:
- `/fix` - Too vague
- `/test` - Conflicts with built-in
- `/help` - Reserved
- `/my-command-that-does-many-things` - Too long

### Writing Descriptions

The `description` field appears in `/help` output:

**Good descriptions**:
```yaml
description: Review pull request for code quality and best practices
description: Generate unit tests for specified file or module
description: Update package dependencies and check for breaking changes
```

**Poor descriptions**:
```yaml
description: Does stuff
description: Helper command
description: Command
```

### Choosing Tool Permissions

Explicitly declare tools your command needs:

```yaml
# Read-only command
allowed-tools: Read(*), Grep(*), Glob(*)

# Git operations
allowed-tools: Bash(git status:*), Bash(git diff:*), Bash(git log:*)

# File modifications
allowed-tools: Read(*), Edit(*), Write(*), Bash(npm test:*)

# Comprehensive access
allowed-tools: Bash(*), Read(*), Write(*), Edit(*), Grep(*), Glob(*)
```

**Pattern syntax**:
- `Tool(*)` - All operations
- `Tool(pattern:*)` - Specific operation (e.g., `Bash(git status:*)`)
- `Tool(*pattern*)` - Contains pattern

### Using Arguments Effectively

**Simple single argument**:
```yaml
argument-hint: [file-path]
```
```markdown
Analyze the file: $ARGUMENTS
```

**Multiple arguments**:
```yaml
argument-hint: [source] [target]
```
```markdown
Compare $1 to $2 and identify differences.
```

**Optional arguments**:
```markdown
If $1 is provided:
  - Use $1 as the target
Otherwise:
  - Use current directory
```

### Command Categories

Organize related commands in subdirectories:

```
.claude/commands/
├── COMMANDS_TEMPLATE.md
├── git/
│   ├── commit.md
│   ├── review-pr.md
│   └── sync.md
├── testing/
│   ├── run-tests.md
│   ├── generate-tests.md
│   └── coverage.md
└── docs/
    ├── generate-readme.md
    └── update-api-docs.md
```

Invoke with: `/git/commit`, `/testing/run-tests`, etc.

### Combining with Bash Execution

Execute shell commands inline:

```markdown
First, check the current branch:
!git branch --show-current

Then check for uncommitted changes:
!git status --short

If there are changes, show them:
!git diff
```

### Combining with File References

Include file contents automatically:

```markdown
Review the implementation in @$1 and suggest improvements.

Compare the old version @$1 with the new version @$2.

Analyze these related files:
@src/main.js
@src/utils.js
@tests/main.test.js
```

### Model Selection Strategy

Choose the right model for the task:

```yaml
# For complex reasoning and code generation (default)
model: claude-3-5-sonnet-20241022

# For fast, simple tasks (commit messages, formatting)
model: claude-3-5-haiku-20241022

# For most complex tasks (architecture, security reviews)
model: claude-opus-4-20250514
```

### Disabling Model Invocation

For simple text commands that don't need AI:

```yaml
---
description: Show project documentation
disable-model-invocation: true
---

# Project Documentation

Visit: https://github.com/org/repo

## Quick Links
- [Setup Guide](docs/setup.md)
- [API Reference](docs/api.md)
- [Contributing](CONTRIBUTING.md)
```

## Command vs Skill: When to Use What

### Use a **Command** when:
- ✅ User needs to explicitly trigger the action
- ✅ It's a specific workflow or routine task
- ✅ You want predictable, on-demand behavior
- ✅ Examples: `/review-pr`, `/generate-tests`, `/commit`

### Use a **Skill** when:
- ✅ Claude should automatically use it when relevant
- ✅ It's specialized knowledge or expertise
- ✅ You want Claude to discover it based on context
- ✅ Examples: PDF processing, Excel analysis, specific frameworks

### Can be **Both**:
Create a command that explicitly invokes a skill:
```markdown
---
description: Perform comprehensive code review
---

Activate the Code Review skill and analyze $ARGUMENTS for:
- Code quality
- Best practices
- Security issues
- Performance opportunities
```

---

## Testing Your Command

### 1. Basic Functionality
```
/command-name
```
Verify it executes without errors.

### 2. With Arguments
```
/command-name arg1 arg2
```
Check argument handling works correctly.

### 3. Edge Cases
```
/command-name
/command-name ""
/command-name with many arguments here
```

### 4. Tool Permissions
Verify declared tools work without extra permission prompts.

### 5. Team Testing
Have colleagues try the command and provide feedback.

---

## Quick Reference Card

| Element | Purpose | Required |
|---------|---------|----------|
| `description` | Shows in /help | ✅ Recommended |
| `allowed-tools` | Pre-approve tools | ❌ Optional |
| `argument-hint` | Show expected args | ❌ Optional |
| `model` | Specify model | ❌ Optional |
| `disable-model-invocation` | Skip AI for static text | ❌ Optional |
| Instructions | What to do | ✅ Yes |
| Examples | Usage demos | ✅ Recommended |
| Error handling | Handle failures | ✅ Recommended |

---

## Common Command Patterns

### 1. Read-Analyze-Report
```markdown
1. Read files specified in $ARGUMENTS
2. Analyze for [criteria]
3. Generate structured report
```

### 2. Execute-Parse-Summarize
```markdown
1. Run: !command $1
2. Parse the output
3. Summarize findings
```

### 3. Generate-Validate-Write
```markdown
1. Generate [content] based on $1
2. Validate against [rules]
3. Write to $2 or default location
```

### 4. Compare-Diff-Suggest
```markdown
1. Load both $1 and $2
2. Compare differences
3. Suggest improvements or migrations
```

### 5. Check-Fix-Verify
```markdown
1. Check for [issues] in $ARGUMENTS
2. Apply fixes automatically
3. Verify corrections worked
```

---

**Pro tip**: Start with simple commands and gradually add complexity. Test each feature before adding the next. Share with your team early for feedback.