← 3.23.4 →
1110 words Slides

3.3 Custom Slash Commands

Course: Claude Code - Essentials Section: Basic Input & Interaction Video Length: 2-5 minutes Presenter: Daniel Treasure

Opening Hook

The real power unlocks when you create your own commands. Instead of typing the same 10-sentence prompt every time you review a PR, you type /review-pr. That's the difference between Claude Code and an AI that really fits your workflow.

Key Talking Points

  1. Two Levels of Custom Commands
  2. Project Commands - .claude/commands/ (shared via git, team uses them)
  3. Personal Commands - ~/.claude/commands/ (just you, all projects)

  4. Can override: project commands take precedence over personal ones

  5. What a Custom Command Is

  6. A SKILL.md file with frontmatter (metadata) + instructions
  7. Lives in a directory named after the command

  8. Callable with /command-name in any Claude Code session

  9. Real-World Examples

  10. /review-pr - standardized PR review with your team's checklist
  11. /refactor-ts - TypeScript refactoring with your code style rules
  12. /bug-hunt - systematic debugging approach specific to your codebase
  13. /test-coverage - generate tests for uncovered lines

  14. /write-docs - documentation template for your project

  15. Anatomy of a Custom Command ```yaml

name: review-pr description: Review a pull request with focus on security and performance user-invocable: true allowed-tools: Read, Grep

Review the following PR changes: 1. Check for security issues 2. Check for performance regressions 3. Verify test coverage 4. Recommend improvements ```

  1. Arguments and Substitutions
  2. $ARGUMENTS - everything the user passed to the command
  3. $ARGUMENTS[0] - first argument
  4. $ARGUMENTS[1] - second argument

  5. Example: /fix-issue 123 → Claude knows the issue number

  6. Scope: Project vs. Personal

  7. Project (.claude/commands/): Enforce team standards
  8. Personal (~/.claude/commands/): Your personal shortcuts

  9. Both can exist simultaneously (project takes priority)

  10. Advanced Features (briefly mention, not deep-dive)

  11. disable-model-invocation: true - only you can invoke it
  12. context: fork - runs in isolated subagent
  13. allowed-tools - restrict what Claude can do in this command
  14. user-invocable: false - Claude invokes it automatically when relevant

Demo Plan

Live Walkthrough (3-5 minutes):

  1. Show Project Structure bash cd /path/to/project ls -la .claude/commands/ # Shows existing custom commands (if any) # Or: mkdir -p .claude/commands/

  2. Create a Simple Custom Command (2-3 minutes)

  3. Create a new command directory: bash mkdir .claude/commands/review-code

  4. Create SKILL.md: bash touch .claude/commands/review-code/SKILL.md

  5. Edit the file (show in editor): ```yaml --- name: review-code description: Review code for quality, readability, and best practices user-invocable: true allowed-tools: Read, Grep ---

    Review the following code: 1. Is the code readable and maintainable? 2. Are there any obvious bugs or logic errors? 3. Does it follow our code style conventions? 4. Are there performance issues? 5. Is error handling sufficient? 6. Are there security concerns? ```

  6. Test the Command (45 seconds)

  7. Back in Claude Code session: bash claude
  8. Type: /review-code src/components/Button.tsx
  9. Claude executes the custom command with the file

  10. Show Claude following the checklist

  11. Show Personal Commands Location (30 seconds)

  12. Explain: ~/.claude/commands/ is your personal directory
  13. Example personal command: /quick-test (personal testing shortcut)

  14. Say: "This works in ALL your projects, but only for you"

  15. Show Command with Arguments (Optional, 30 seconds)

  16. Create a command that uses $ARGUMENTS:
  17. Example: /refactor-to-async $ARGUMENTS[0] (refactor specific function)
  18. Show: /refactor-to-async loginFunction

Code Examples & Commands

Minimal Project Command

.claude/commands/review-code/
└── SKILL.md

SKILL.md content:

---
name: review-code
description: Thorough code review with focus on quality
user-invocable: true
---

Review this code for:
1. Readability and maintainability
2. Security vulnerabilities
3. Performance issues
4. Best practices for this language
5. Test coverage gaps

Command with Arguments

---
name: refactor-function
description: Refactor a function to be more readable
user-invocable: true
---

Refactor $ARGUMENTS[0] to:
1. Follow modern syntax and best practices
2. Reduce complexity
3. Improve type safety
4. Add comments explaining the logic

Usage:

/refactor-function loginHandler

Team-Level Command (Project Commands)

.claude/commands/pr-review/
└── SKILL.md

.claude/commands/security-audit/
└── SKILL.md

.claude/commands/write-test/
└── SKILL.md

All committed to git, all team members use the same checklist.

Personal Commands (Your Shortcuts)

~/.claude/commands/quick-explain/
└── SKILL.md

~/.claude/commands/find-todo/
└── SKILL.md

~/.claude/commands/performance-check/
└── SKILL.md

Works in every project you touch.

Gotchas & Tips

  1. Gotcha: Directory name = command name
  2. Directory: .claude/commands/my-command/
  3. Usage: /my-command
  4. Must use lowercase and hyphens

  5. Underscores don't work in command invocation

  6. Gotcha: SKILL.md must be in the command directory

  7. Right: .claude/commands/review/SKILL.md
  8. Wrong: .claude/commands/SKILL.md

  9. Wrong: .claude/review/SKILL.md

  10. Tip: Start simple, evolve

  11. First command: simple checklist (no arguments)
  12. Second: add one $ARGUMENTS variable

  13. Advanced: add allowed-tools, context: fork, etc.

  14. Tip: Project commands in git = team standard

  15. Team does code reviews the same way
  16. New team members learn your process

  17. PR checklist is code (can be versioned)

  18. Tip: Personal commands for your habits

  19. Your debugging workflow
  20. Your refactoring style
  21. Your documentation template

  22. Lives in ~/.claude/commands/, ignored by git

  23. Gotcha: Custom commands don't override built-in ones

  24. Can't create /help, /clear, /config as custom commands
  25. Built-ins always take priority

  26. Name your commands thoughtfully to avoid confusion

  27. Tip: Use descriptions that matter

  28. Good: "Review code for security, performance, and readability"
  29. Bad: "Review code"

  30. Claude uses descriptions to decide when to auto-invoke

  31. Gotcha: Relative paths in commands

  32. $ARGUMENTS[0] might be a relative path
  33. Test thoroughly with different working directories

  34. Use absolute paths or validate input in the SKILL.md

  35. Tip: Combine with shell commands (!)

  36. Advanced: use ! prefix in command body to run shell commands
  37. Example: /test command runs !npm test to get live results
  38. See 3.4 (Bash Mode) for deeper dive

Lead-out

Custom commands are where Claude Code starts to feel like it's built for you, not the other way around. In the next video, bash mode, you'll see how to run actual shell commands from within Claude Code—which is how commands can execute your tests, builds, and scripts automatically.

Reference URLs

  • Official Docs - Skills & Custom Commands: https://code.claude.com/docs/en/skills (section: "Creating Your First Skill")
  • Official Docs - Skill Locations: https://code.claude.com/docs/en/skills (section: "Skill Locations")
  • Official Docs - String Substitutions: https://code.claude.com/docs/en/skills (section: "String Substitutions")

Prep Reading

  • Official: Skills documentation - comprehensive guide to SKILL.md structure
  • Recent Articles: "Inside the Development Workflow of Claude Code's Creator" - Boris Cherny uses custom commands heavily
  • Context: from docs: Custom commands live alongside code in version control (team practice)