Custom slash commands and skills transform Claude Code from a powerful AI assistant into your personalized development toolkit. By creating reusable prompts and workflows, you can standardize team practices, enforce coding standards, and eliminate repetitive typing.
Understanding the Command System Architecture
Claude Code's command system operates on a simple principle: markdown files in specific directories become executable commands. When you type /commandname, Claude Code looks for a matching file and injects its contents as your prompt.
Command Lookup Order
Claude Code searches for commands in this priority order:
- Project commands:
.claude/commands/in your current directory - User commands:
~/.claude/commands/in your home directory - Built-in commands: Claude Code's default commands like
/help,/clear,/init
Project commands take precedence, allowing you to override global commands for specific repositories.
Creating Simple Slash Commands
Basic Command Structure
Create a markdown file in your commands directory. The filename (without .md) becomes the command name:
# Create project-level commands directory
mkdir -p .claude/commands
# Create a simple command
touch .claude/commands/review.md
Edit .claude/commands/review.md:
Review this code for:
- Security vulnerabilities (injection, XSS, CSRF)
- Performance issues (N+1 queries, memory leaks)
- Code style violations
- Missing error handling
- Potential edge cases
Provide specific line numbers and suggested fixes.
Now /review expands to this entire prompt, ready to analyze whatever code you're discussing.
Using Placeholders
Commands support several dynamic placeholders:
| Placeholder | Description | Example Use |
|---|---|---|
$ARGUMENTS | Everything typed after the command | /translate $ARGUMENTS with input /translate Spanish |
$SELECTION | Currently selected text in editor | Review selected code block |
$FILE | Current file path | Reference the active file |
$DIRECTORY | Current working directory | Project context |
Example: Translation Command
.claude/commands/translate.md:
Translate the following code comments and strings to $ARGUMENTS.
Keep all code logic unchanged. Only translate human-readable text.
Preserve formatting and indentation.
Usage: /translate Japanese translates comments to Japanese.
Example: Documentation Generator
.claude/commands/document.md:
Generate comprehensive documentation for $ARGUMENTS in this codebase.
Include:
1. Overview and purpose
2. Function signatures with parameter descriptions
3. Return values and types
4. Usage examples
5. Common pitfalls or gotchas
Format as JSDoc/TSDoc comments ready to paste into the source.
Usage: /document the authentication middleware
Project-Level vs Global Commands
Project-Level Commands (.claude/commands/)
Best for:
- Team-specific workflows
- Project coding standards
- Repository-specific templates
- Commands that reference project structure
# Commit to version control
git add .claude/commands/
git commit -m "Add team slash commands"
Global Commands (~/.claude/commands/)
Best for:
- Personal productivity shortcuts
- Language-agnostic utilities
- Commands used across all projects
# Create global commands directory
mkdir -p ~/.claude/commands
Building Complex Skills
Skills extend commands with multi-step workflows, conditional logic, and structured output requirements.
Multi-Step Workflow Example
.claude/commands/feature.md:
# New Feature Implementation Workflow
You are implementing a new feature: $ARGUMENTS
Follow these steps in order:
## Step 1: Planning
- Identify affected files and components
- List required changes
- Note potential breaking changes
- Ask clarifying questions if requirements are ambiguous
## Step 2: Implementation
- Create necessary files with proper structure
- Write clean, documented code
- Follow existing project patterns
- Include TypeScript types where applicable
## Step 3: Testing
- Write unit tests for new functionality
- Cover edge cases and error conditions
- Verify tests pass: `npm test`
## Step 4: Documentation
- Update README if needed
- Add inline code comments
- Update API documentation
## Step 5: Review Checklist
Confirm before completing:
- [ ] All tests pass
- [ ] No TypeScript errors
- [ ] Code follows project style guide
- [ ] No sensitive data exposed
- [ ] Changes are backwards compatible
Present a summary of all changes made.
Code Review Skill
.claude/commands/pr-review.md:
# Pull Request Review
Perform a thorough code review with the following focus areas:
## Security Analysis
- Check for injection vulnerabilities
- Verify authentication/authorization
- Look for exposed secrets or credentials
- Review input validation
## Code Quality
- Assess readability and maintainability
- Check for code duplication
- Verify error handling
- Review naming conventions
## Performance
- Identify potential bottlenecks
- Check for unnecessary computations
- Review database query efficiency
- Look for memory leaks
## Testing
- Verify test coverage
- Check test quality
- Identify missing edge cases
## Output Format
Provide findings in this structure:
### Critical Issues (Must Fix)
- [Issue description with file:line reference]
### Suggestions (Should Consider)
- [Improvement suggestion]
### Positive Observations
- [Good practices noticed]
### Summary
[Overall assessment and recommendation: Approve / Request Changes]
Test Generator Skill
.claude/commands/test.md:
Generate comprehensive tests for $ARGUMENTS.
## Requirements
- Use the project's existing test framework
- Follow existing test file naming conventions
- Include setup and teardown where needed
## Test Categories
1. **Happy Path**: Normal expected usage
2. **Edge Cases**: Boundary conditions, empty inputs, limits
3. **Error Cases**: Invalid inputs, failures, exceptions
4. **Integration**: Interactions with dependencies (mock appropriately)
## Structure Each Test
```javascript
describe('[Component/Function Name]', () => {
describe('[Method/Scenario]', () => {
it('should [expected behavior] when [condition]', () => {
// Arrange
// Act
// Assert
});
});
});
Generate tests and explain the reasoning for each test case.
### Commit Helper Skill
`.claude/commands/commit.md`:
```markdown
# Smart Commit Assistant
Analyze the current staged changes and help create a proper commit.
## Steps
1. Run `git diff --staged` to see changes
2. Analyze the nature of changes (feature, fix, refactor, docs, etc.)
3. Identify the scope/component affected
4. Generate a commit message following Conventional Commits format
## Commit Message Format
[optional body with details]
[optional footer with breaking changes or issue references]
### Types
- `feat`: New feature
- `fix`: Bug fix
- `docs`: Documentation only
- `style`: Formatting, no code change
- `refactor`: Code change that neither fixes nor adds
- `perf`: Performance improvement
- `test`: Adding tests
- `chore`: Maintenance tasks
## Output
Provide:
1. Suggested commit message
2. Brief explanation of changes
3. Any concerns or suggestions before committing
Best Practices
Keep Commands Focused
Each command should do one thing well. Instead of a massive "do everything" command, create composable smaller commands:
.claude/commands/
├── lint.md # Run linting
├── test.md # Run tests
├── typecheck.md # Check TypeScript
├── validate.md # Combines lint + test + typecheck
Include Context Requirements
Specify what context the command needs:
# Required Context
Before running this command, ensure:
- You have a file open or selected
- The file is a React component
- Tests exist in __tests__ directory
# Command
[Your command content]
Version Your Commands
For team commands, include version and last updated:
<!-- Version: 1.2.0 | Updated: 2025-01-15 | Author: @teammate -->
[Command content]
Debugging Custom Commands
Command Not Found
- Verify file exists:
ls -la .claude/commands/ - Check filename matches command (no
.mdwhen calling) - Ensure markdown extension:
command.mdnotcommand.txt - Restart Claude Code to reload commands
Placeholder Not Expanding
- Use exact placeholder names:
$ARGUMENTSnot$args - Placeholders are case-sensitive
- Check for typos in placeholder names
Command Loads But Behaves Unexpectedly
- Review the markdown for formatting issues
- Test the command content by pasting it directly
- Check for conflicting global vs project commands
Viewing Available Commands
Type / in Claude Code to see all available commands, including your custom ones. Custom commands appear alongside built-in commands.
Additional Resources
- Claude Code Documentation
- Configure CLAUDE.md Files - Project-level AI configuration
- Use Hooks for Automation - Combine commands with hooks
- GitHub: awesome-claude-code - Community commands and skills
Want help building custom AI workflows for your team? Inventive HQ specializes in developer productivity and AI tooling. Contact us to discuss custom Claude Code integrations for your organization.