FoundryVTT/.claude/commands/.COMMANDS_TEMPLATE.md

description, allowed-tools, argument-hint, disable-model-invocation

description	allowed-tools	argument-hint	disable-model-invocation
Brief description of what this command does (shown in /help)	Bash(git status:*), Bash(git add:*), Read(*)	optional-parameter	false

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

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:

## Section Title
- Item 1
- Item 2

**Summary**: Key findings...

Or for code output:

// Expected code format
output_example();

Advanced Features

Bash Execution

Execute shell commands directly:

!ls -la
!git status
!npm test

Prefix commands with ! to run them immediately.

File References

Include file contents in the prompt:

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:

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:

1. Read the files in $ARGUMENTS
2. Analyze for [specific criteria]
3. Provide structured feedback

Execute then report:

1. Run: !command $1
2. Parse the output
3. Summarize results

Generate then write:

1. Generate [content type] based on $1
2. Write to specified location
3. Confirm completion

Error Handling

Handle common issues gracefully:

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:

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:

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:

description: Does stuff
description: Helper command
description: Command

Choosing Tool Permissions

Explicitly declare tools your command needs:

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

argument-hint: [file-path]

Analyze the file: $ARGUMENTS

Multiple arguments:

argument-hint: [source] [target]

Compare $1 to $2 and identify differences.

Optional arguments:

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:

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:

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:

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

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

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

1. Read files specified in $ARGUMENTS
2. Analyze for [criteria]
3. Generate structured report

2. Execute-Parse-Summarize

1. Run: !command $1
2. Parse the output
3. Summarize findings

3. Generate-Validate-Write

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

4. Compare-Diff-Suggest

1. Load both $1 and $2
2. Compare differences
3. Suggest improvements or migrations

5. Check-Fix-Verify

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.