10.3 Custom Commands for Your Workflow

Course: Claude Code - Power User Section: Customizing Claude Code Video Length: 2-5 minutes Presenter: Daniel Treasure

Opening Hook

You do the same thing repeatedly. "Review this for bugs." "Write tests for this function." "Refactor this and keep the behavior." Instead of typing it out every time, create a custom command. One slash, one word, done. Let's build commands that turbocharge your workflow.

Key Talking Points

1. What Are Custom Commands?

Slash commands you define that automate recurring tasks
Stored in ~/.claude/skills/ (user-level) or .claude/skills/ (project-level)
Each command has a name, description, intent, and instruction prompt
When you invoke /commandname, Claude reads your instructions and executes What to say: "Custom commands are muscle memory. Your team probably has a checklist for code reviews. Turn that into /review. The first time takes 5 minutes. The next 100 times take 5 seconds." What to show on screen: Terminal with claude /review command. Show the skill definition file. Show the output.

2. Good Commands Solve Frequent Problems

Commit message summaries: claude /commit reads staged changes, writes summary
Code reviews: claude /review checks for bugs, security, performance
Test generation: claude /test creates test skeletons for a file
Refactoring: claude /rename (with arguments) renames a function across codebase
Documentation: claude /doc generates docstrings for functions
Security audit: claude /security checks code for vulnerabilities What to say: "Not every task deserves a command. Create commands for things you do weekly, or monthly. Commands you do once a year? Just type it out." What to show on screen: Show 3-4 real commands in action. Show the time saved vs. typing the full instruction.

3. Building a Command: Name, Intent, Inputs, Outputs

Name: short, lowercase, descriptive (e.g., commit, review, test)
Description: one sentence explaining what it does
Intent: what Claude should do (the instruction prompt)
Inputs: what data the command works on (file path, code selection, diff)
Outputs: what the command produces (summary, report, code)
Tools: which tools the command can use (bash, read, write, etc.) What to say: "A good command name is so obvious you don't need help. A good intent is so clear that Claude knows exactly what's expected." What to show on screen: SKILL.md frontmatter showing name, description, intent, allowed-tools. Show the YAML structure.

4. Best Practices for Custom Commands

Keep names simple and verb-first when possible (review, test, audit)
Document the intent clearly—Claude follows instructions precisely
Use $ARGUMENTS placeholder for user input
Use dynamic context (!gh pr diff``) to grab live data
Test the command before sharing with team
Add examples in the skill description What to say: "The best commands are so useful that your team asks for them. The worst are so niche that only you use them." What to show on screen: A well-designed command vs. a confusing one. Show the difference in output clarity.

Demo Plan

Open ~/.claude/skills/ directory structure
Show an existing skill (SKILL.md) with YAML frontmatter
Create a new skill from scratch:
Create directory ~/.claude/skills/commit-summary/
Create SKILL.md with frontmatter
Write the intent prompt
Invoke the command: claude /commit-summary with staged changes
Show output and discuss how well it followed instructions
Create a second command that takes arguments: claude /rename OldName NewName
Test dynamic context in a command using !bash command``

Code Examples & Commands

List available skills:

ls -la ~/.claude/skills/

Basic skill structure (commit-summary):

~/.claude/skills/commit-summary/
├── SKILL.md          # The skill definition
└── context/          # Optional context files (README, examples)
    └── example.md

SKILL.md (commit-summary example):

---
name: commit-summary
description: "Generate a concise commit message from staged changes"
argument-hint: "(optional) custom focus area"
user-invocable: true
allowed-tools: ["bash", "read"]
model: "claude-opus-4-6"
---

# Commit Summary Generator

You are a git commit message writer. Analyze the staged changes and generate a concise, 
conventional commit message.

Format: `type(scope): description`

Types: feat, fix, docs, style, refactor, perf, test, chore

If the user provides $ARGUMENTS, focus on that area.

Steps:
1. Read the staged diff: !`git diff --cached`
2. Identify files changed
3. Determine commit type (feat, fix, etc.)
4. Write a one-line summary (50 chars max)
5. Add body if needed (explaining why, not what)

Output only the commit message, ready to use.

SKILL.md (code-review example):

---
name: review
description: "Review code for bugs, security, performance, and style"
argument-hint: "filepath or 'staged' for staged changes"
user-invocable: true
allowed-tools: ["bash", "read"]
model: "claude-opus-4-6"
---

# Code Review

You are a thorough code reviewer. Analyze the provided code and identify:
1. Bugs (logic errors, edge cases)
2. Security issues (injection, auth, secrets)
3. Performance problems (O(n²) loops, memory leaks)
4. Style violations (naming, structure, clarity)
5. Test gaps (untested paths)

Arguments:
- If $ARGUMENTS is "staged", review staged git changes
- If $ARGUMENTS is a filepath, review that file

Output format:
- Each issue on its own line
- Format: [SEVERITY] [CATEGORY] message
- Severity: critical, high, medium, low
- Category: bug, security, perf, style, test

Only report real issues. Don't nitpick style that's already consistent.

SKILL.md (refactor with arguments):

---
name: refactor
description: "Refactor code according to a pattern"
argument-hint: "pattern: extract-function, simplify-conditional, rename, etc."
user-invocable: true
allowed-tools: ["read", "write", "bash"]
model: "claude-opus-4-6"
---

# Refactoring Assistant

You help refactor code safely. Supported patterns: $ARGUMENTS

Patterns:
- extract-function: pull logic into a new function
- simplify-conditional: flatten nested if/else
- rename: rename a variable or function
- remove-duplication: consolidate repeated logic

Provide the refactored code with a brief explanation of changes.

Invoke a command:

# Simple command
claude /commit-summary

# Command with arguments
claude /refactor extract-function

# Command reading a file
claude /review src/api.ts

Dynamic context in a skill (git diff):

---
name: pr-checklist
description: "Generate a PR checklist based on the PR diff"
user-invocable: true
allowed-tools: ["bash"]
---

# PR Checklist Generator

You are a PR reviewer. Generate a checklist for code review.

Use the PR diff: !`git diff main...$(git rev-parse --abbrev-ref HEAD)`

Format:
- [ ] Item
- [ ] Item

Only include checks relevant to the diff. If no security changes, skip security checks.

Gotchas & Tips

Gotcha: $ARGUMENTS refers to user input at command invocation. If the user doesn't provide arguments, $ARGUMENTS is empty. Handle that gracefully in your prompt.

Tip: Use allowed-tools to restrict what Claude can do. A review command doesn't need write access—use allowed-tools: ["read", "bash"].

Tip: Commands live in version control. Put them in .claude/skills/ (project level) so your whole team benefits.

Gotcha: Dynamic context (!command) runs in the session's working directory. If someone runs claude /review from a different folder, the diff command might fail. Clarify paths in your prompt.

Tip: Test commands with edge cases—empty files, very large files, unusual inputs. Fix your prompt before sharing.

Tip: Use the "context" field to include reference docs. A /security command might include OWASP guidelines in its context folder.

Lead-out

Custom commands save time for you. Next, we'll standardize for your team—how to enforce coding standards, naming conventions, and commit patterns so everyone's Claude behaves the same way.

Reference URLs

Custom Skills documentation
SKILL.md specification and YAML frontmatter fields
String substitution reference ($ARGUMENTS, $N, etc.)
Dynamic context with ! commands

Prep Reading

What are the top 5 instructions you give Claude repeatedly?
Which of those could become commands?
What outputs would your team reuse?

Notes for Daniel: Custom commands are about discovering your personal workflow. Don't make this theoretical—show real commands you actually use. The demo should feel practical, not academic. Emphasize that commands are low-friction to create and update, so people should experiment.

Quick Reference