Content
# Tool List
[](LICENSE)
[](https://github.com/VCnoC/Claude-Code-Zen-mcp-Skill-Work)
> 🚀 **An out-of-the-box rule system and skill package designed for AI programming intelligent agents.**
This project is more than just a collection of tools; it's a standardized workflow and quality assurance mechanism. It empowers AI agents to complete complex programming tasks more efficiently and reliably through intelligent routing, multi-stage workflows, and automated code reviews.
## ✨ Core Features
- 🔗 **CLI Bridging Capability**: Enables AI agents to autonomously call external command-line tools (like Codex CLI, Gemini CLI) through Zen MCP, achieving cross-tool collaboration.
- 🧠 **Intelligent Routing (`main-router`)**: Automatically selects the most suitable skill based on user intent, serving as the "brain" of the entire system.
- 📊 **Structured Workflow (P1-P4)**: Decomposes complex development tasks into four standard stages: analysis, solution, execution, and repair, ensuring a clear and controllable process.
- 📝 **Automated Planning (`plan-down`)**: Automatically generates structured `plan.md` files and supports multi-model verification, eliminating manual task decomposition.
- 🔍 **5-Dimensional Code Review (`codex-code-reviewer`)**: Conducts comprehensive code reviews and scoring from five dimensions: quality, security, performance, architecture, and documentation.
- 📄 **Professional Document Generation (`simple-gemini` & `deep-gemini`)**: Automatically generates and maintains project knowledge bases (`PROJECTWIKI.md`), change logs (`CHANGELOG.md`), and in-depth technical analysis reports.
- 🤖 **Fully Automated Mode**: Supports a "one-sentence requirement, fully automated development" mode, where AI can autonomously complete tasks from planning to code implementation, review, testing, and documentation updates.
## 🏗️ Working Principle
The system processes user requests through a four-stage (P1-P4) workflow, unified and dispatched by `main-router`. This process ensures that each task undergoes thorough analysis, rigorous planning, and strict quality verification.
```mermaid
flowchart LR
A[User Request] --> B(main-router<br/>Intent Recognition and Routing)
B --> C[P1: Problem Analysis<br/>Understand Requirements, Locate Root Cause]
C --> D[P2: Solution Development<br/>Call plan-down to Generate plan.md]
D --> E[P3: Execute Solution<br/>Coding, Testing, Documentation Updates]
E --> F{Success?}
F -->|Yes| G[✅ Completion]
F -->|No| H[P4: Error Handling<br/>Repair Issues and Verify through Regression Gate]
H --> G
```
> For more details on architecture design, state machines, and data models, please refer to **[PROJECTWIKI.md](./PROJECTWIKI.md)**.
## 🎯 Core Skill Package
This project provides a set of plug-and-play core skills, each granting AI agents a professional capability.
| Skill | Core Responsibility | Main Output |
|-----------------------|------------------------------------|--------------------------------|
| `main-router` | **Intelligent Routing and Task Scheduling** | Routing Decisions, Global State Management |
| `plan-down` | **Task Decomposition and Plan Generation** | `plan.md` Files |
| `codex-code-reviewer` | **5-Dimensional Code Quality Review and Automated Repair** | Quality Reports, Repaired Code |
| `simple-gemini` | **Standard Documentation and Test Code Generation** | `README`, `PROJECTWIKI`, Test Files |
| `deep-gemini` | **In-Depth Technical Analysis and Report Generation** | Architecture/Performance Analysis Reports |
## 🚀 Quick Start
### 1. Environment Requirements
- **[Python](https://www.python.org/)** >= 3.8
- **[Git](https://git-scm.com/downloads)**
### 2. Installation Steps
This repository includes **Zen MCP Server** and **Core Skill Package**. Installation can be completed in three steps.
**Step 1: Clone Repository**
```bash
git clone https://github.com/VCnoC/Claude-Code-Zen-mcp-Skill-Work.git
cd Claude-Code-Zen-mcp-Skill-Work
```
**Step 2: Run One-Click Installation Script**
The script will automatically complete the installation of Zen MCP Server, copy skill packages, and configure global rules.
- **Linux / macOS**:
```bash
chmod +x install.sh && ./install.sh
```
- **Windows**:
```powershell
.\install.ps1
```
> **💡 Tip**: If the one-click script is not available (e.g., for versions cloned from GitHub), use the manual installation steps below.
#### Linux / macOS Manual Installation
```bash
# 1. Copy and Install Zen MCP Server
cp -r zen-mcp-server ~/zen-mcp-server
cd ~/zen-mcp-server
pip3 install -r requirements.txt
cd ..
# 2. Copy Skill Packages, Shared Resources, and Global Rules
mkdir -p ~/.claude/skills
cp -r skills/* ~/.claude/skills/
cp -r references ~/.claude/references
cp CLAUDE.md ~/.claude/CLAUDE.md
```
#### Windows Manual Installation
```powershell
# 1. Copy and Install Zen MCP Server
Copy-Item -Path ".\zen-mcp-server" -Destination "$env:USERPROFILE\zen-mcp-server" -Recurse
cd "$env:USERPROFILE\zen-mcp-server"
pip install -r requirements.txt
cd $OLDPWD
# 2. Copy Skill Packages, Shared Resources, and Global Rules
New-Item -ItemType Directory -Path "$env:USERPROFILE\.claude\skills" -Force
Copy-Item -Path ".\skills\*" -Destination "$env:USERPROFILE\.claude\skills\" -Recurse
Copy-Item -Path ".\references" -Destination "$env:USERPROFILE\.claude\references" -Recurse
Copy-Item -Path ".\CLAUDE.md" -Destination "$env:USERPROFILE\.claude\CLAUDE.md"
```
**Manual Installation Core Steps Summary**:
1. Copy `zen-mcp-server/` to user directory and install dependencies
2. Create `~/.claude/` directory structure (if it doesn't exist)
3. Copy `skills/` under all skill files to `~/.claude/skills/`
4. Copy `references/` folder to `~/.claude/references/`
5. Copy `CLAUDE.md` to `~/.claude/CLAUDE.md`
> **📁 Final Directory Structure**: `~/.claude/` contains `skills/`, `references/`, and `CLAUDE.md` three core components
### 3. Configuration and Launch
**Step 1: Configure API Keys**
Edit the configuration file located at `~/zen-mcp-server/.env` (or `%USERPROFILE%\zen-mcp-server\.env`), and fill in your API Keys.
```dotenv
# OpenAI API Key (used for code review, etc.)
OPENAI_API_KEY=sk-your-openai-api-key-here
# Google Gemini API Key (supports native format and OpenAI compatible format)
GEMINI_API_KEY=your-gemini-api-key-here
# ⚠️ Strongly recommended: specify allowed models to avoid unexpected high costs
OPENAI_ALLOWED_MODELS=gpt-4-turbo,gpt-4o
# Optional: use custom API endpoints (Ollama, vLLM, LM Studio, etc.)
# CUSTOM_API_URL=http://localhost:11434/v1 # API endpoint (must end with /v1)
# CUSTOM_API_KEY= # API key (leave blank for Ollama)
# CUSTOM_MODEL_NAME=llama3.2 # Default model name
```
> **💡 Use Local Models**: To use Ollama, vLLM, or LM Studio and other local inference services, configure the above `CUSTOM_API_*` parameters. If you need to customize model capabilities (extended reasoning, vision, etc.), you can add model configurations in `zen-mcp-server/conf/custom_models.json`.
**Step 2: Launch Zen MCP Server**
```bash
cd ~/zen-mcp-server
# Recommended: use launch script (automatically configure environment)
# Linux/Mac users
chmod +x run-server.sh
./run-server.sh
# Windows users
.\run-server.ps1
# Or run directly
python3 server.py # Linux/Mac
python server.py # Windows
The launch script will provide interactive configuration options. After selecting according to the actual situation, it will automatically write MCP configuration into .claude.json file
```
### 4. Restart Claude Code
Completely close Claude code and then restart.
## ✅ Verify Installation
Launch Claude code and input:
```
Please use main-router to help me analyze available skills
```
If you can see detailed descriptions of `main-router`, `plan-down`, and other five skills, it indicates that the installation is successful!
## 📖 Usage Examples
### Interactive Mode (Default)
In default mode, AI will seek your confirmation at key decision points to ensure you have complete control over the development process.
**Example:**
> `Help me refactor the auth.py file to improve its readability.`
**AI Response Process:**
1. **P1 Analysis**: AI analyzes `auth.py`, identifies key areas for refactoring (e.g., complex functions, duplicated code blocks).
2. **P2 Solution**: AI proposes a refactoring plan (`plan.md`), e.g., "Split the `authenticate_user` function into three independent private functions," and waits for your approval.
3. **P3 Execution**: After your confirmation, AI executes the refactoring and verifies code quality through `codex-code-reviewer`.
### Fully Automated Mode
For high-trust tasks, you can authorize AI to complete tasks fully automatically without human intervention.
**Example:**
> `Fully automate the addition of a user registration feature using SQLite for my Flask application, with a test coverage rate of at least 85%.`
**AI Response Process:**
1. **Automated Planning**: AI calls `plan-down` to formulate detailed development steps.
2. **Automated Execution**: Create database models, write backend routes, and generate frontend templates.
3. **Automated Review and Testing**: Each code step is reviewed automatically by `codex-code-reviewer`. AI also calls `simple-gemini` to write test cases, ensuring a coverage rate of 85%.
4. **Automated Documentation**: All decisions and operations are recorded in `auto_log.md` for your audit.
## 💡 Core Philosophy
The rules and skill designs of this project follow the core philosophies defined in the global configuration file `CLAUDE.md`.
- **G1: Documentation as a First-Class Citizen**: Any code changes must be synchronized and updated to `PROJECTWIKI.md` and `CHANGELOG.md` to ensure absolute consistency between documentation and code.
- **G8: Mandatory Skill Use (Anti-Laziness Principle)**: Critical tasks (e.g., planning, code review, documentation generation) must be executed by the most professional skills, eliminating direct handling by "main models" to ensure output quality.
- **G9: Quantifiable Quality Goals**: All development activities should revolve around clear quality indicators, e.g., test coverage targets (`coverage_target`) must be set at the beginning of the task.
## 📚 Documentation Center
| Document | Content Description |
|----------------------------------------------------------------|----------------------------------------------------------|
| **[PROJECTWIKI.md](./PROJECTWIKI.md)** | **Project Knowledge Base (Core)**: Architecture design, decision records, and module documentation. |
| **[CLAUDE.md](./CLAUDE.md)** | **Global Rules**: Defines G1-G11 global rules and P1-P4 workflow. |
| **[CHANGELOG.md](./CHANGELOG.md)** | **Change Log**: Records all version change histories of the project. |
| **[skills/shared/tool_parameter_contract.md](./skills/shared/tool_parameter_contract.md)** | **Tool Parameter Contract**: Detailed parameter descriptions for all tools in Zen MCP Server. |
## 🙏 Acknowledgements
The implementation of this project is inspired and supported by the following excellent open-source projects:
- **[HelloAgents](https://github.com/hellowind777/helloagents)**: Provided `AGENTS.md` specifications and initial design concepts for multi-stage workflows.
- **[Zen MCP Server](https://github.com/BeehiveInnovations/zen-mcp-server)**: Provided a stable and reliable MCP server implementation.
## 📄 License
This project adopts the [Apache 2.0 License](LICENSE).
