Refinement for context size

2025-10-28 12:48:17 -05:00
parent 35d2069861
commit ddea00cb40
11 changed files with 1539 additions and 1196 deletions
--- a/claude-code/skills/claude-commands/SKILL.md
+++ b/claude-code/skills/claude-commands/SKILL.md
@@ -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.