Engineering
September 8, 2025
Complete Claude Code Best Practices Guide (Part 2): Custom Commands - Your AI Shortcuts to Productivity
Effective collaboration is the backbone of any successful team, but too often, it’s slowed down by disconnected tools, endless email threads, and scattered information. Read on to learn more.
This is part 2 of a 3-part series on Claude Code best practices that transformed how we build software at Kasava. Part 1 covered documentation structure and organization with CLAUDE.md files and the CLAUDE_FILES_INDEX.
Commands and Agents are a great way to customize Claude Code to not only use the right patterns for code development but also to use the right chain of reasoning and research techniques to ensure that all options are explored and best practices are interrogated and validated.
Let's start with commands because they're the gateway drug to custom agents. In your .claude/commands/ directory, each markdown file becomes a slash command. Here's our most-used commands at Kasava:
The /blog Command That Writes Itself
What This Command Does:
🔍 Searches your codebase for relevant examples
✍️ Maintains your writing voice and style
🎯 Structures posts with intro, body, and conclusion
💾 Automatically saves to the blog/ directory
🌐 Uses web research for additional context
Now when I type /blog How we reduced our embedding costs by 90%, Claude doesn't just write generic content - it pulls real examples from our codebase, maintains my writing voice, and saves it in the right place.
The /issues Command That Manages GitHub
What This Command Does:
🆕 Creates new issues with proper labels
🔍 Searches for duplicate issues before creating
🔗 Links related issues together
📋 Generates issue templates
📊 Creates issue reports
🏷️ Uses consistent label taxonomy
The /think Command for Complex Problem-Solving
This one's special. Sometimes you need Claude to really think through a problem:
What This Command Does:
🧠 Restates problems for clarity
🔬 Breaks down complex components
📚 Researches existing codebase patterns
💡 Proposes multiple solution approaches
⚖️ Evaluates trade-offs systematically
🎯 Recommends best approach with justification
📝 Creates step-by-step implementation plans
The structured thinking process consistently produces better solutions than just asking Claude to solve something.
The /style Command for Consistent Code
What This Command Does:
🔍 Analyzes existing code patterns
📏 Documents naming conventions
🏗️ Captures code organization structure
💬 Identifies commenting practices
⚠️ Documents error handling patterns
🧪 Recognizes testing approaches
📄 Generates comprehensive STYLE_GUIDE.md
The /update Command for Maintenance
What This Command Does:
📅 Checks file freshness (>7 days old)
🤖 Creates subagents for parallel updates
🔄 Compares and updates outdated info
🎨 Maintains original formatting
✅ Updates CLAUDE_FILES_INDEX.md timestamps
🔧 Keeps documentation synchronized
This keeps your CLAUDE.md files fresh and accurate as your project evolves.
The /visualize Command for Architecture Diagrams
What This Command Does:
📊 Creates flowcharts for code flow
🗃️ Generates database ERD diagrams
🏛️ Visualizes system architecture
🔄 Maps API interaction sequences
🧩 Shows class and module relationships
🌐 Diagrams network infrastructure
📐 Supports Mermaid, PlantUML, and Graphviz
Full disclosure -- I found this one on Github and I would credit but I forgot to star their repo...
The /work Command for Issue Management
What This Command Does:
🔌 Connects to GitHub via MCP server
📋 Lists and prioritizes open issues
🎯 Selects issues to work on
🌿 Creates feature branches
💻 Writes clear, tested code
📚 Updates documentation
💾 Commits with descriptive messages
🚀 Creates pull requests
🧹 Cleans up workspace
This command turns Claude into an autonomous contributor who can pick up GitHub issues and work on them end-to-end.
The /upgrade Command with Agent Delegation
What This Command Does:
🎯 Analyzes upgrade requirements
🤖 Delegates to specialized agents:
Cloudflare → cloudflare-backend-architect
Mastra → mastra-workflow-architect
Search → vector-search-architect
Frontend → nextjs-frontend-expert
Extension → browser-extension-developer
📋 Reviews specialist recommendations
🧪 Implements with testing
📝 Updates documentation
Command Design Principles
1. Make Them Specific
Bad: /help - too vague
Good: /debug-api - clear purpose
2. Use $ARGUMENTS Effectively
Commands can take arguments. Use them to make your commands flexible:
———
Pro Tips from the Trenches
Start with your biggest pain point - What do you ask Claude to do repeatedly? That's your first command.
Include examples in your commands - Show Claude exactly what good output looks like
Document your commands - Keep a list of available commands in your main CLAUDE.md
The Bottom Line
Custom commands transformed Claude from a general assistant into a specialized toolkit. Each command is a shortcut to productivity, armed with your team's specific context and practices.
Start small. Create one command for something you do repeatedly. Watch as your productivity multiplies.
The real magic isn't in having AI write code - it's in having AI that writes code the way your team writes code, following your processes, and understanding your context.
Next Up
In Part 3, we'll dive deep into specialized agents - the secret weapons that turned Claude from a coding assistant into a full team member. Spoiler: our `cloudflare-backend-architect` agent writes better Workers code than most humans.
———
This is part 2 of a 3-part series on Claude Code best practices. Next up: Specialized agents - your domain experts that bring deep knowledge to complex problems.


