Complete Claude Code Best Practices Guide (Part 2): Custom Commands - Your AI Shortcuts to Productivity
Complete Claude Code Best Practices Guide (Part 2): Custom Commands - Your AI Shortcuts to Productivity
Sep 8, 2025
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
<!-- .claude/commands/blog.md -->
You are a product manager tasked with writing a blog post about a given topic.
The topic for your blog post is:<topic>$ARGUMENTS</topic>
Look through the existing project structure for relevant information.
To gather additional information, use the web research agent.
When writing, follow this structure:
1. Introduction: Hook the reader
2. Main body: 2-4 sections exploring different aspects
3. Conclusion: Summarize and provide call to action
Maintain a conversational and engaging tone. Use examples from the actual
codebase where relevant.
When finished, save to the blog/ directory.
---
This is your LinkedIn profile:
<linkedin>[Your or your colleague's linkedin profile.]</linkedin>
---
<example_post>[Example posts for tone and style follow...]<
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
<!-- .claude/commands/issues.md -->
You are a GitHub issues manager for the Kasava project.
Task: $ARGUMENTS
Available operations:
- Create new issues with proper labels and assignees
- Search existing issues for duplicates
- Link related issues
- Create issue templates
- Generate issue reports
Always check for duplicates before creating new issues.Use our label taxonomy:
- bug: Something isn't working
- enhancement: New feature or request
- documentation: Improvements or additions to documentation
- performance: Performance improvements
- tech-debt: Code refactoring or cleanup
Format issues with:
1. Clear, searchable ttles
2. Reproduction steps (for bugs)
3. Expected vs actual behavior
4. Environment details
5. Related PR/issue linksThe /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
<!-- .claude/commands/think.md -->
Approach this problem methodically:
1. Understand: Restate the problem in your own words
2. Analyze: Break down the components
3. Research: Look through the codebase for similar patterns
4. Design: Propose 2-3 different approaches
5. Evaluate: Compare trade-offs of each approach
6. Recommend: Choose the best approach with justification
7. Plan: Create step-by-step implementation plan
Problem: $ARGUMENTS
Take your time. Think through edge cases. Consider performance implications.
Reference existing code patterns where applicable
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
<!-- .claude/commands/style.md -->
You are tasked with creating a comprehensive style guide for writing code
that future AI prompts should follow.
Carefully examine the code in the following directory:
<relevant_directory>$ARGUMENTS</relevant_directory>
Analyze the code patterns, design choices, and conventions used throughout
the project. Pay attention to:
- Naming conventions (variables, functions, classes)
- Code organization and structure
- Commenting and documentation practices
- Indentation and formatting
- Error handling and logging
- Use of design patterns or architectural styles
- Testing approaches (if visible in the code)
Create a document called STYLE_GUIDE.md that outlines the best practices
and conventions for writing code in this project
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
<!-- .claude/commands/update.md -->
You are tasked with updating all existing CLAUDE.md files in a project directory
with the current information of the project.
Look at the CLAUDE_FILES_INDEX.md file and identify each file path that has a
updated_at value of more than 7 days ago. Create a subagent for each file.
For each subagent:
- Analyze the content of the corresponding CLAUDE.md file
- Compare the existing information with the updated project information
- Identify any outdated, incorrect, or missing information
- Update the file content with current project information
- Maintain the original structure and formatting
After all subagents have completed their updates,
update the relevant files in CLAUDE_FILES_INDEX.md with the current
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
<!-- .claude/commands/visualize.md -->
Analyzes code and architecture to generate explanatory diagrams.
<architecture_location>
$ARGUMENTS
</architecture_location>
**Default Output Location**: `/docs/diagrams/` directory
This command transforms complex code, logic, and system architectures
into clear, visual diagrams.
Generates:
- Code flow visualization (flowcharts)
- Database schema visualization (ERDs)
- System architecture diagrams
- API interaction sequences
- Class and module relationships
- Network and infrastructure diagrams
Output formats: Mermaid (default), PlantUML, Graphviz DOTFull 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
<!-- .claude/commands/work.md -->
You are an AI assistant tasked with managing and working on GitHub issues.
1. Connect to the preconfigured MCP server for Github
2. List all open issues on the repository (or work on specific issue if provided)
3. Select one to work on (oldest or highest priority)
4. Create a new branch for your changes
5. Work on the issue with clear, tested code
6. Update documentation as needed
7. Commit changes with descriptive messages
8. Push branch and create pull request
9. Clean up workspace when done
Your goal is to look for open issues, select one to work on, and
create a pull request when the work is
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
<!-- .claude/commands/upgrade.md -->
Analyze the requested upgrade and delegate to the appropriate specialist:
Task: $ARGUMENTS
If this involves:
- Cloudflare services → Use cloudflare-backend-architect agent
- Mastra workflows → Use mastra-workflow-architect agent
- Search/embeddings → Use vector-search-architect agent
- Frontend React → Use nextjs-frontend-expert agent
- Chrome extension → Use browser-extension-developer agent
Approach:
1. Identify the domain
2. Engage the specialist agent
3. Review their recommendations
4. Implement with proper testing
5. Update relevant CLAUDE.md filesCommand 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:
<!-- .claude/commands/test.md -->
Run tests for the specified component or feature:
<target>$ARGUMENTS</target>
If no target specified, run all tests.If target is a file path,
run tests for that file.If target is a feature name, run related test suites
———
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.
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
<!-- .claude/commands/blog.md -->
You are a product manager tasked with writing a blog post about a given topic.
The topic for your blog post is:<topic>$ARGUMENTS</topic>
Look through the existing project structure for relevant information.
To gather additional information, use the web research agent.
When writing, follow this structure:
1. Introduction: Hook the reader
2. Main body: 2-4 sections exploring different aspects
3. Conclusion: Summarize and provide call to action
Maintain a conversational and engaging tone. Use examples from the actual
codebase where relevant.
When finished, save to the blog/ directory.
---
This is your LinkedIn profile:
<linkedin>[Your or your colleague's linkedin profile.]</linkedin>
---
<example_post>[Example posts for tone and style follow...]<
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
<!-- .claude/commands/issues.md -->
You are a GitHub issues manager for the Kasava project.
Task: $ARGUMENTS
Available operations:
- Create new issues with proper labels and assignees
- Search existing issues for duplicates
- Link related issues
- Create issue templates
- Generate issue reports
Always check for duplicates before creating new issues.Use our label taxonomy:
- bug: Something isn't working
- enhancement: New feature or request
- documentation: Improvements or additions to documentation
- performance: Performance improvements
- tech-debt: Code refactoring or cleanup
Format issues with:
1. Clear, searchable ttles
2. Reproduction steps (for bugs)
3. Expected vs actual behavior
4. Environment details
5. Related PR/issue linksThe /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
<!-- .claude/commands/think.md -->
Approach this problem methodically:
1. Understand: Restate the problem in your own words
2. Analyze: Break down the components
3. Research: Look through the codebase for similar patterns
4. Design: Propose 2-3 different approaches
5. Evaluate: Compare trade-offs of each approach
6. Recommend: Choose the best approach with justification
7. Plan: Create step-by-step implementation plan
Problem: $ARGUMENTS
Take your time. Think through edge cases. Consider performance implications.
Reference existing code patterns where applicable
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
<!-- .claude/commands/style.md -->
You are tasked with creating a comprehensive style guide for writing code
that future AI prompts should follow.
Carefully examine the code in the following directory:
<relevant_directory>$ARGUMENTS</relevant_directory>
Analyze the code patterns, design choices, and conventions used throughout
the project. Pay attention to:
- Naming conventions (variables, functions, classes)
- Code organization and structure
- Commenting and documentation practices
- Indentation and formatting
- Error handling and logging
- Use of design patterns or architectural styles
- Testing approaches (if visible in the code)
Create a document called STYLE_GUIDE.md that outlines the best practices
and conventions for writing code in this project
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
<!-- .claude/commands/update.md -->
You are tasked with updating all existing CLAUDE.md files in a project directory
with the current information of the project.
Look at the CLAUDE_FILES_INDEX.md file and identify each file path that has a
updated_at value of more than 7 days ago. Create a subagent for each file.
For each subagent:
- Analyze the content of the corresponding CLAUDE.md file
- Compare the existing information with the updated project information
- Identify any outdated, incorrect, or missing information
- Update the file content with current project information
- Maintain the original structure and formatting
After all subagents have completed their updates,
update the relevant files in CLAUDE_FILES_INDEX.md with the current
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
<!-- .claude/commands/visualize.md -->
Analyzes code and architecture to generate explanatory diagrams.
<architecture_location>
$ARGUMENTS
</architecture_location>
**Default Output Location**: `/docs/diagrams/` directory
This command transforms complex code, logic, and system architectures
into clear, visual diagrams.
Generates:
- Code flow visualization (flowcharts)
- Database schema visualization (ERDs)
- System architecture diagrams
- API interaction sequences
- Class and module relationships
- Network and infrastructure diagrams
Output formats: Mermaid (default), PlantUML, Graphviz DOTFull 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
<!-- .claude/commands/work.md -->
You are an AI assistant tasked with managing and working on GitHub issues.
1. Connect to the preconfigured MCP server for Github
2. List all open issues on the repository (or work on specific issue if provided)
3. Select one to work on (oldest or highest priority)
4. Create a new branch for your changes
5. Work on the issue with clear, tested code
6. Update documentation as needed
7. Commit changes with descriptive messages
8. Push branch and create pull request
9. Clean up workspace when done
Your goal is to look for open issues, select one to work on, and
create a pull request when the work is
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
<!-- .claude/commands/upgrade.md -->
Analyze the requested upgrade and delegate to the appropriate specialist:
Task: $ARGUMENTS
If this involves:
- Cloudflare services → Use cloudflare-backend-architect agent
- Mastra workflows → Use mastra-workflow-architect agent
- Search/embeddings → Use vector-search-architect agent
- Frontend React → Use nextjs-frontend-expert agent
- Chrome extension → Use browser-extension-developer agent
Approach:
1. Identify the domain
2. Engage the specialist agent
3. Review their recommendations
4. Implement with proper testing
5. Update relevant CLAUDE.md filesCommand 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:
<!-- .claude/commands/test.md -->
Run tests for the specified component or feature:
<target>$ARGUMENTS</target>
If no target specified, run all tests.If target is a file path,
run tests for that file.If target is a feature name, run related test suites
———
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.
Kasava
No Spam. Just Product updates.
Company
Kasava. All right reserved. © 2025
Kasava
No Spam. Just Product updates.
Company
Kasava. All right reserved. © 2025
Kasava
No Spam. Just Product updates.
Company
Kasava. All right reserved. © 2025
Kasava
No Spam. Just Product updates.
Company
Kasava. All right reserved. © 2025