This skill directs Claude Code to leverage Zen MCP (Model Context Protocol) tools for comprehensive software development workflows. Zen MCP provides specialized tools that enable multi-model collaboration, systematic investigation, and expert validation for superior results.

When to Use Zen MCP

Always use Zen MCP tools when:

Planning features or architectural changes
Implementing new functionality
Debugging issues or investigating bugs
Analyzing existing code or architecture
Reviewing code for quality, security, or performance
Generating or updating documentation
Creating test suites
Performing security audits
Refactoring code
Validating git changes before committing

Use Zen MCP even for:

Tasks that seem simple but benefit from systematic analysis
Problems where you need high confidence in the solution
Scenarios requiring multi-perspective evaluation

Available Zen MCP Tools

Planning & Design

zen:planner - Interactive, sequential planning with revision and branching
- Use for: Complex project planning, system design, migration strategies
- Supports: Step-by-step planning, revision, branching, alternative approaches

Collaborative Thinking

zen:chat - General chat and collaborative thinking partner
- Use for: Brainstorming, development discussion, getting second opinions, exploring ideas
- Supports: Multi-turn conversations with continuation_id, websearch, thinking modes

Decision Making

zen:consensus - Multi-model consensus through structured debate
- Use for: Complex decisions, architectural choices, feature proposals, technology evaluations
- Supports: Multiple models with different stances (for/against/neutral)

Investigation & Analysis

zen:thinkdeep - Multi-stage investigation and reasoning
- Use for: Architecture decisions, complex bugs, performance challenges, security analysis
- Supports: Hypothesis testing, evidence-based investigation, expert validation
zen:analyze - Comprehensive code analysis
- Use for: Architecture, performance, maintainability, pattern analysis
- Types: architecture, performance, security, quality, general
zen:tracer - Systematic code tracing
- Use for: Execution flow analysis, dependency mapping, call chain tracing
- Modes: precision (execution flow), dependencies (structural relationships)

Code Quality & Security

zen:codereview - Systematic step-by-step code review
- Use for: Quality, security, performance, architecture review
- Types: full, security, performance, quick
- Validation: external (expert model) or internal
zen:secaudit - Comprehensive security audit
- Use for: OWASP Top 10, compliance evaluation, threat modeling
- Focus areas: owasp, compliance, infrastructure, dependencies, comprehensive
zen:precommit - Git change validation before committing
- Use for: Multi-repo validation, security review, change impact assessment
- Supports: Staged/unstaged changes, branch comparison

Debugging & Testing

zen:debug - Systematic debugging and root cause analysis
- Use for: Complex bugs, mysterious errors, performance issues, race conditions
- Supports: Hypothesis testing, evidence gathering, confidence tracking
zen:testgen - Comprehensive test suite generation
- Use for: Creating tests with edge case coverage for functions, classes, modules
- Analyzes: Code paths, failure modes, boundary conditions

Documentation & Refactoring

zen:docgen - Comprehensive code documentation generation
- Use for: Generating function/class docs, complexity analysis, call flow documentation
- Features: Big O analysis, dependency tracking, inline comments for complex logic
zen:refactor - Code refactoring analysis
- Use for: Code smell detection, decomposition planning, modernization
- Types: codesmells, decompose, modernize, organization

Model Selection Guidelines

Choose models based on task complexity:

Gemini Models (when GOOGLE_API_KEY configured):

gemini-2.5-pro - Deep reasoning + thinking mode (1M context)
- Use for: Complex problems, architecture, deep analysis
gemini-2.0-flash - Latest fast model (1M context)
- Use for: Fast analysis with experimental thinking, supports audio/video
gemini-2.5-flash - Ultra-fast (1M context)
- Use for: Quick analysis, simple queries, rapid iterations

OpenAI Models (when OPENAI_API_KEY configured):

o3 - Strong reasoning (200K context)
- Use for: Logical problems, code generation, systematic analysis
o3-mini - Fast O3 variant (200K context)
- Use for: Balanced performance/speed, moderate complexity
o4-mini - Latest reasoning model (200K context)
- Use for: Optimized shorter contexts, rapid reasoning
gpt-5 - Advanced model (400K context, 128K output)
- Use for: Advanced reasoning tasks
o3-pro - Professional-grade reasoning (200K context)
- EXTREMELY EXPENSIVE: Only for universe-scale complexity OR explicit user request

X.AI GROK Models (when XAI_API_KEY configured):

grok-4 - Frontier multimodal reasoning (256K context)
- Use for: Advanced reasoning with multimodal capabilities
grok-3 - Advanced reasoning (131K context)
- Use for: Complex analysis tasks

Default recommendation: Start with o3-mini or gemini-2.5-flash for most tasks. Escalate to o3 or gemini-2.5-pro for complex problems.

Workflow Patterns

For New Feature Implementation:

Start with zen:planner - Break down the feature into steps
Use zen:chat - Discuss approach and get second opinions
Use zen:analyze - Understand existing codebase architecture
Use zen:codereview - Review implementation before committing
Use zen:testgen - Generate comprehensive tests
Use zen:precommit - Validate all changes before commit

For Bug Investigation:

Start with zen:debug - Systematic investigation with hypothesis testing
Use zen:tracer - Trace execution flow or dependencies if needed
Use zen:thinkdeep - For complex bugs requiring deep analysis
Use zen:testgen - Create regression tests
Use zen:precommit - Validate fix before committing

For Code Quality Improvement:

Use zen:analyze - Assess current state
Use zen:refactor - Identify refactoring opportunities
Use zen:codereview - Review changes
Use zen:secaudit - Security audit if touching sensitive areas
Use zen:docgen - Update documentation
Use zen:precommit - Final validation

For Architectural Decisions:

Use zen:consensus - Get multi-model perspectives on options
Use zen:thinkdeep - Deep investigation of implications
Use zen:planner - Plan migration/implementation strategy
Use zen:chat - Discuss edge cases and considerations

Important Parameters

continuation_id

Reuse the same continuation_id to maintain conversation context across tool calls
This embeds complete conversation history - focus on new insights
Works across different Zen MCP tools

Thinking Modes

minimal (0.5%), low (8%), medium (33%), high (67%), max (100%)
Higher modes provide deeper reasoning but are slower
Use higher modes for complex problems

Confidence Levels (for debug, thinkdeep, analyze, etc.)

exploring - Just starting
low - Early investigation
medium - Some evidence
high - Strong evidence
very_high - Comprehensive understanding
almost_certain - Near complete confidence
certain - 100% confidence (prevents external validation)

Warning: Only use 'certain' when absolutely sure. It prevents expert model validation.

File Paths

Always use FULL absolute paths to files/folders
DO NOT SHORTEN file paths
Zen MCP tools need complete, real paths

Best Practices

DO:

✓ Use zen:chat for quick questions and brainstorming before starting work ✓ Use zen:planner for complex features to break them down systematically ✓ Use zen:debug instead of manual debugging for mysterious issues ✓ Use zen:codereview before committing significant changes ✓ Use zen:testgen to create comprehensive test coverage ✓ Use zen:precommit to catch issues before they hit the repo ✓ Provide continuation_id to maintain context across related tool calls ✓ Use full absolute file paths in all tool parameters ✓ Let Zen tools use websearch to find best practices and documentation

DON'T:

✗ Skip Zen tools for "quick fixes" that turn into complex problems ✗ Use 'certain' confidence level unless truly 100% confident ✗ Shorten or abbreviate file paths ✗ Try to solve complex problems without systematic investigation ✗ Commit code without running zen:precommit validation ✗ Skip zen:secaudit for security-sensitive changes

Examples

Example 1: Complex Bug

User: "There's a memory leak in the user session handler"

Claude Code should:
1. Use zen:debug with model='o3' to investigate systematically
2. Trace execution with zen:tracer if needed
3. Create regression tests with zen:testgen
4. Validate fix with zen:precommit

Example 2: New Feature

User: "Add OAuth2 authentication"

Claude Code should:
1. Use zen:planner with model='gemini-2.5-pro' to plan implementation
2. Use zen:chat to discuss security implications
3. Use zen:analyze to understand current auth architecture
4. Implement with continuous validation
5. Use zen:secaudit to ensure security
6. Use zen:testgen to create auth tests
7. Use zen:precommit before committing

Example 3: Code Quality

User: "Refactor the payment processing module"

Claude Code should:
1. Use zen:analyze type='quality' to assess current state
2. Use zen:refactor to identify opportunities
3. Use zen:consensus to evaluate different approaches
4. Use zen:codereview after refactoring
5. Use zen:docgen to update documentation

Integration with Claude Code

Claude Code automatically discovers and loads this skill when:

Working on any coding tasks
The user mentions planning, implementation, debugging, testing, or review
Complex problems require systematic analysis

You'll see "Using Zen MCP Development" in Claude's thinking when this skill is active.

Resources

All Zen MCP tools support websearch for finding documentation and best practices
Tools can request Claude to perform web searches for framework docs, API info, solutions
Most tools support multiple models - choose based on task complexity
Tools support thinking modes for deeper reasoning when needed

Summary

Zen MCP transforms Claude Code from a direct code executor into a systematic, multi-model development environment. Always reach for Zen MCP tools first for any non-trivial development task. The systematic investigation, expert validation, and multi-perspective analysis provided by these tools consistently produces better results than direct implementation.

name	Programming
description	Coding, programming, software development

Programming

Overview