movq/claude-plugins
2
0
Fork 0
Code Issues Pull Requests Actions Releases Activity

Refinement for context size

Browse Source
This commit is contained in:
movq
2025-10-28 12:48:17 -05:00
parent 35d2069861
commit ddea00cb40
11 changed files with 1539 additions and 1196 deletions
Download Patch File Download Diff File Expand all files Collapse all files

347
claude-code/skills/claude-commands/SKILL.md
View File

@@ -1,6 +1,6 @@
---
name: Slash Command Creator
description: Create custom slash commands for Claude Code with argument handling, bash execution, and file references. Use PROACTIVELY when building reusable prompts, automating workflows, creating project-specific commands, or when users mention "create a command", "reusable prompt", "/something", or "slash command". NOT for complex multi-file operations.
description: Create custom slash commands for Claude Code with argument handling, bash execution, and file references. Use PROACTIVELY when users repeat similar prompts 3+ times, mention "create a command", "reusable prompt", "/something", or "slash command". Triggers BEFORE user asks explicitly to suggest command creation for repeated workflows. NOT for complex multi-file operations.
---
# Slash Command Development
@@ -10,21 +10,20 @@ description: Create custom slash commands for Claude Code with argument handling
Use this skill when:
- Creating custom slash commands for Claude Code
- Building reusable prompt templates
- Automating repetitive tasks with commands
- Setting up project-specific workflows
- Converting manual prompts to slash commands
- User repeats similar prompts 3+ times
- Automating repetitive tasks
- Converting manual workflows to commands
Do NOT use this skill for:
- Creating full plugins (use claude-plugin skill)
- Creating full plugins (use claude-plugins skill)
- Setting up hooks (use claude-hooks skill)
- Complex multi-file operations (use subagents)
## Quick Start
### Create Command File
Create a command file in `.claude/commands/`:
```bash
# Project-specific (team shared)
mkdir -p .claude/commands
cat > .claude/commands/review.md << 'EOF'
---
@@ -45,12 +44,12 @@ EOF
## Command Locations
| Location | Scope | Version Control | Use For |
|----------|-------|-----------------|---------|
| `.claude/commands/` | Project (team) | In git | Team workflows, standards |
| `~/.claude/commands/` | User (personal) | Not in git | Personal productivity |
| Location | Scope | Use For |
|----------|-------|---------|
| `.claude/commands/` | Project (team) | Team workflows, standards |
| `~/.claude/commands/` | User (personal) | Personal productivity |
## Command Syntax
## Essential Syntax
### Basic Structure
@@ -64,313 +63,143 @@ Prompt content here
$ARGUMENTS
```
### Filename = Command Name
**File name = Command name**: `review.md` → `/review`
```bash
# File: .claude/commands/test.md
# Command: /test
# File: .claude/commands/commit-push.md
# Command: /commit-push
```
## Frontmatter Options
### Frontmatter Options
```yaml
---
description: Generate unit tests for a function # Shows in /help
argument-hint: <file-path> <function-name> # Autocomplete hint
allowed-tools: Read(*), Bash(git:*) # Tool permissions
model: claude-haiku-4 # Override default model
disable-model-invocation: true # Prevent auto-invocation
description: Generate unit tests for a function # Required
argument-hint: <file-path> <function-name> # Autocomplete
allowed-tools: Read(*), Bash(git:*) # Permissions
model: claude-haiku-4 # Model override
---
```
## Argument Handling
### $ARGUMENTS - All Arguments
### Arguments
```markdown
---
description: Explain multiple files
---
Explain these files: $ARGUMENTS
$ARGUMENTS # All arguments
$1, $2, $3 # Positional arguments
@$1 or @file.js # Load file content
```
**Usage**: `/explain @src/a.js @src/b.js @src/c.js`
### Positional ($1, $2, $3...)
```markdown
---
description: Compare two approaches
argument-hint: <approach1> <approach2>
---
Compare approach "$1" versus "$2" and recommend which is better.
**Examples**:
```bash
/compare REST GraphQL # $1="REST", $2="GraphQL"
/review @src/main.js # Loads main.js content
/explain @src/a.js @src/b.js # Loads both files
```
**Usage**: `/compare REST GraphQL`
### Bash Execution
### File References with @
Prefix with `!` to execute before processing:
```markdown
---
description: Review a file
---
Review @$1 for code quality issues.
```
**Usage**: `/review src/auth.js`
Claude reads `src/auth.js` automatically.
## Bash Execution with !
Prefix commands with `!` to execute before processing:
```markdown
---
description: Show git status and suggest next steps
allowed-tools: Bash(git status:*), Bash(git diff:*)
description: Git workflow helper
allowed-tools: Bash(git:*)
---
!git status
!git diff --stat
Based on the current git state, suggest what I should do next.
Based on above, suggest next steps.
```
**Important**: Must include `allowed-tools` with Bash specifications.
**Important**: Must include `allowed-tools` with Bash patterns.
## Complete Examples
### Security Review
## Quick Examples
### Simple Review Command
```markdown
---
description: Comprehensive security review of code files
allowed-tools: Read(*), Grep(*)
argument-hint: <files...>
description: Review code quality
---
Perform a security audit on: $ARGUMENTS
Review @$1 for:
1. Logic errors
2. Code style
3. Performance issues
Check for:
1. SQL injection vulnerabilities
2. XSS vulnerabilities
3. Authentication/authorization issues
4. Hardcoded secrets or credentials
5. Unsafe deserialization
6. Path traversal vulnerabilities
For each issue found:
- Severity level (Critical/High/Medium/Low)
- Location (file:line)
- Explanation of the vulnerability
- Recommended fix with code example
Provide specific fixes.
```
### Commit + Push
### Multi-Step Workflow
```markdown
---
description: Review changes, commit, and push to remote
description: Commit and push changes
allowed-tools: Bash(git:*)
---
!git status
!git diff
Review the changes above and:
1. Create an appropriate commit message
2. Commit the changes
3. Push to remote
1. Review changes
2. Create commit message
3. Commit and push
Ask for confirmation before pushing.
```
### Test Generator
```markdown
---
description: Generate comprehensive tests for a function
argument-hint: <file> <function-name>
model: claude-sonnet-4
---
For the function "$2" in @$1:
1. Analyze the function's behavior
2. Identify edge cases
3. Generate comprehensive unit tests including:
- Happy path tests
- Edge case tests
- Error condition tests
- Boundary value tests
Use the project's existing test framework and patterns.
Ask confirmation before push.
```
For more examples, see [examples.md](examples.md)
## Command Patterns
### Review Pattern
```markdown
---
description: Review X for Y
---
Review $ARGUMENTS for [specific criteria]
Include:
- [Aspect 1]
- [Aspect 2]
```
### Generate Pattern
```markdown
---
description: Generate X from Y
---
Generate [output type] for: $ARGUMENTS
Requirements:
- [Requirement 1]
- [Requirement 2]
```
### Compare Pattern
```markdown
---
description: Compare X and Y
argument-hint: <option1> <option2>
---
Compare "$1" versus "$2"
Analyze:
- [Comparison aspect 1]
- [Comparison aspect 2]
Recommendation: [Which is better and why]
```
## Testing Commands
```bash
# See all available commands
/help
# Test with different arguments
/mycommand arg1
/mycommand @file.js
/mycommand @file1.js @file2.js
```
## Best Practices
### 1. Clear Descriptions
### ✓ Do
- Clear descriptions under 100 chars
- Specific tool permissions
- Meaningful command names (kebab-case)
- Self-documenting prompts
- Include argument hints
```yaml
# Good
description: Generate unit tests for a specific function
### ✗ Avoid
- Vague descriptions ("Helper", "Utils")
- Wildcard permissions (`allowed-tools: *`)
- Short cryptic names (`/gt`, `/rs`)
- Hardcoded secrets or paths
- Missing frontmatter
# Bad
description: Testing
```
### 2. Explicit Arguments
```yaml
# Good
argument-hint: <file-path> <function-name>
# Bad (no hint)
```
### 3. Specific Tool Permissions
```yaml
# Good - minimal permissions
allowed-tools: Bash(git status:*), Bash(git diff:*)
# Risky - too permissive
allowed-tools: *
```
### 4. Meaningful Names
## Testing
```bash
# Good
/generate-tests
/review-security
/commit-and-push
# List all commands
/help
# Bad
/gt
/rs
/cap
# Test with arguments
/mycommand arg1
/mycommand @file.js
```
### 5. Self-Documenting Content
```markdown
Review code for:
1. Logic errors
2. Style issues
3. Performance problems
$ARGUMENTS
```
## Troubleshooting
## Common Issues
| Problem | Solution |
|---------|----------|
| Command not found | Check file is in `.claude/commands/`, ends with `.md` |
| Arguments not working | Use `$ARGUMENTS`, `$1`, `$2` (not `${ARGUMENTS}`) |
| Bash not executing | Add `allowed-tools` frontmatter with `Bash()` pattern |
| File references not loading | Verify file path, use `@` prefix |
| Command not found | Check `.claude/commands/`, restart Claude |
| Arguments not working | Use `$ARGUMENTS`, not `${ARGUMENTS}` |
| Bash not executing | Add `allowed-tools: Bash(...)` |
| File not loading | Use `@` prefix, verify path |
## Security Considerations
For detailed troubleshooting, see [troubleshooting.md](troubleshooting.md)
### Limit Tool Access
## Security
**Limit permissions**:
```yaml
# Specific commands only
allowed-tools: Bash(git status:*), Bash(git log:*)
# ✓ Specific
allowed-tools: Bash(git status:*), Bash(git diff:*)
# Never use unless required
# ✗ Too broad
allowed-tools: *
```
### No Hardcoded Secrets
**No secrets**:
```markdown
# Bad - hardcoded API key
!curl -H "API-Key: sk-abc123..." api.example.com
# ✗ Bad
!curl -H "API-Key: sk-abc123..."
# Good - use environment variables
!curl -H "API-Key: $MY_API_KEY" api.example.com
```
### Validate User Input
```markdown
# Risky - no validation
!rm -rf $1
# Better - validate first
Confirm you want to delete: $1
(Then use interactive confirmation)
# ✓ Good
!curl -H "API-Key: $MY_API_KEY"
```
## Command Template
@@ -387,13 +216,17 @@ allowed-tools: [Specific patterns if needed]
$ARGUMENTS
```
## Resources
## Additional Resources
- [Complete Examples](examples.md) - Working command configurations
- [Advanced Patterns](patterns.md) - Complex workflows
- [Official Documentation](https://docs.claude.com/en/docs/claude-code/slash-commands)
- [Plugin Development](../claude-plugin/SKILL.md) - Packaging commands
**Need more?**
- [Complete Examples](examples.md) - 10+ working commands
- [Command Patterns](patterns.md) - Reusable templates
- [Troubleshooting Guide](troubleshooting.md) - Problem solutions
- [Official Docs](https://docs.claude.com/en/docs/claude-code/slash-commands)
- [Plugin Development](../claude-plugins/SKILL.md) - Package commands
💡 **Tip**: Start with manual prompts, identify repetition, then create commands. Commands are for workflows you use 3+ times.
---
**Remember**: Slash commands are for reusable prompts. Start with manual prompts, identify patterns you repeat, then codify them as commands.
**Remember**: Slash commands = reusable prompts. Keep them simple, specific, and secure.

216
claude-code/skills/claude-commands/examples.md Normal file
View File

@@ -0,0 +1,216 @@
# Command Examples
Complete, working slash command examples.
## Security Review
```markdown
---
description: Comprehensive security review of code files
allowed-tools: Read(*), Grep(*)
argument-hint: <files...>
---
Perform a security audit on: $ARGUMENTS
Check for:
1. SQL injection vulnerabilities
2. XSS vulnerabilities
3. Authentication/authorization issues
4. Hardcoded secrets or credentials
5. Unsafe deserialization
6. Path traversal vulnerabilities
For each issue found:
- Severity level (Critical/High/Medium/Low)
- Location (file:line)
- Explanation of the vulnerability
- Recommended fix with code example
```
**Usage**: `/security-review @src/auth.js @src/api.js`
## Commit + Push
```markdown
---
description: Review changes, commit, and push to remote
allowed-tools: Bash(git:*)
---
!git status
!git diff
Review the changes above and:
1. Create an appropriate commit message
2. Commit the changes
3. Push to remote
Ask for confirmation before pushing.
```
**Usage**: `/commit-push`
## Test Generator
```markdown
---
description: Generate comprehensive tests for a function
argument-hint: <file> <function-name>
model: claude-sonnet-4
---
For the function "$2" in @$1:
1. Analyze the function's behavior
2. Identify edge cases
3. Generate comprehensive unit tests including:
- Happy path tests
- Edge case tests
- Error condition tests
- Boundary value tests
Use the project's existing test framework and patterns.
```
**Usage**: `/generate-tests src/utils.js calculateTotal`
## Documentation Generator
```markdown
---
description: Generate JSDoc/TSDoc comments for code
---
Generate comprehensive documentation for: $ARGUMENTS
Include:
- Function/class description
- Parameter types and descriptions
- Return value description
- Usage examples
- Edge cases and error conditions
```
**Usage**: `/document @src/api/users.js`
## API Endpoint Creator
```markdown
---
description: Create REST API endpoint with tests
argument-hint: <method> <path> <description>
---
Create a $1 endpoint at "$2" that $3
Include:
1. Route handler with validation
2. Controller logic
3. Unit tests
4. Integration tests
5. API documentation
```
**Usage**: `/api POST /users/login "authenticates a user"`
## Refactor Command
```markdown
---
description: Refactor code for better maintainability
---
Refactor $ARGUMENTS
Focus on:
- Extract repeated code into functions
- Improve naming clarity
- Reduce complexity
- Add error handling
- Maintain existing behavior
Show before/after comparison.
```
**Usage**: `/refactor @src/legacy.js`
## Performance Analyzer
```markdown
---
description: Analyze code for performance bottlenecks
allowed-tools: Read(*), Grep(*)
---
Analyze $ARGUMENTS for performance issues
Check for:
1. O(n²) or worse algorithms
2. Unnecessary re-renders (React)
3. Memory leaks
4. Inefficient database queries
5. Large bundle sizes
Provide specific optimization suggestions with code examples.
```
**Usage**: `/performance @src/components/DataTable.tsx`
## Dependency Audit
```markdown
---
description: Audit project dependencies
allowed-tools: Bash(npm:*), Read(package.json)
---
!npm outdated
!npm audit
Review dependencies and:
1. Identify security vulnerabilities
2. Find outdated packages
3. Detect unused dependencies
4. Recommend updates or replacements
```
**Usage**: `/audit-deps`
## Code Cleanup
```markdown
---
description: Clean up code formatting and style
allowed-tools: Read(*), Write(*), Bash(npx prettier:*)
---
Clean up $ARGUMENTS
1. Remove unused imports
2. Fix formatting issues
3. Resolve linter warnings
4. Remove console.logs
5. Add missing type annotations
```
**Usage**: `/cleanup @src/**/*.ts`
## Migration Helper
```markdown
---
description: Help migrate code to new API/library version
argument-hint: <files> <from-version> <to-version>
---
Migrate $1 from version $2 to $3
1. Identify breaking changes
2. Update deprecated APIs
3. Fix type errors
4. Update tests
5. Verify functionality
```
**Usage**: `/migrate @src/app.js 3.0 4.0`

93
claude-code/skills/claude-commands/patterns.md Normal file
View File

@@ -0,0 +1,93 @@
# Command Patterns
Common patterns for creating effective slash commands.
## Review Pattern
```markdown
---
description: Review X for Y
---
Review $ARGUMENTS for [specific criteria]
Include:
- [Aspect 1]
- [Aspect 2]
```
**Use for**: Code review, security audits, style checks
## Generate Pattern
```markdown
---
description: Generate X from Y
---
Generate [output type] for: $ARGUMENTS
Requirements:
- [Requirement 1]
- [Requirement 2]
```
**Use for**: Test generation, documentation, boilerplate code
## Compare Pattern
```markdown
---
description: Compare X and Y
argument-hint: <option1> <option2>
---
Compare "$1" versus "$2"
Analyze:
- [Comparison aspect 1]
- [Comparison aspect 2]
Recommendation: [Which is better and why]
```
**Use for**: Technology comparisons, approach evaluation
## Workflow Pattern
```markdown
---
description: Execute multi-step workflow
allowed-tools: Bash(git:*), Read(*), Write(*)
---
!git status
!git diff
1. [Step 1]
2. [Step 2]
3. [Step 3]
Ask for confirmation before final step.
```
**Use for**: Git workflows, build processes, deployment
## Analysis Pattern
```markdown
---
description: Analyze X and provide insights
---
Analyze $ARGUMENTS
Focus on:
1. [Key metric 1]
2. [Key metric 2]
3. [Key metric 3]
Provide actionable recommendations.
```
**Use for**: Performance analysis, complexity metrics, dependency review

235
claude-code/skills/claude-commands/troubleshooting.md Normal file
View File

@@ -0,0 +1,235 @@
# 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