Content
# Claude Code Zen MCP Skill Work
[](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 (e.g., 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, planning, execution, and repair, ensuring a clear and controllable process.
- 📝 **Automated Planning (`plan-down`)**: Generates a structured `plan.md` file, supporting multi-model verification, and eliminating manual task decomposition.
- 🔍 **5-Dimensional Code Review (`codex-code-reviewer`)**: Conducts a comprehensive review of code quality, security, performance, architecture, and documentation across five dimensions, providing a score.
- 📄 **Professional Document Generation (`simple-gemini` & `deep-gemini`)**: Automatically generates and maintains project knowledge base (`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 independently 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 Identification and Routing)
B --> C[P1: Problem Analysis<br/>Understand Requirements, Identify Root Cause]
C --> D[P2: Plan Development<br/>Invoke plan-down to Generate plan.md]
D --> E[P3: Execute Plan<br/>Coding, Testing, Documentation Update]
E --> F{Success?}
F -->|Yes| G[✅ Completion]
F -->|No| H[P4: Error Handling<br/>Fix Issues and Verify through Regression Gate]
H --> G
```
> For more details on architecture design, state machines, and data models, 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 specialized 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` File |
| `codex-code-reviewer` | **5-Dimensional Code Quality Review and Automated Repair** | Quality Report, Repaired Code |
| `simple-gemini` | **Standard Document 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., 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 all skill files under `skills/` to `~/.claude/skills/`
4. Copy `references/` folder to `~/.claude/references/`
5. Copy `CLAUDE.md` to `~/.claude/CLAUDE.md`
> **📁 Final Directory Structure**: `~/.claude/` contains three core components: `skills/`, `references/`, and `CLAUDE.md`
### 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 fees
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 (Ollama leave blank)
# CUSTOM_MODEL_NAME=llama3.2 # Default model name
```
> **💡 Using Local Models**: To use Ollama, vLLM, or LM Studio, configure the above `CUSTOM_API_*` parameters. For custom model capabilities (extended inference, vision, etc.), 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 configures 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 provides interactive configuration options. After selecting according to the actual situation, it will automatically write MCP configuration to .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 5 skills, 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 readability.`
**AI Response Process:**
1. **P1 Analysis**: AI analyzes `auth.py`, identifying key areas for refactoring (e.g., complex functions, repetitive code blocks).
2. **P2 Planning**: 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 performs 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 of at least 85%.`
**AI Response Process:**
1. **Automated Planning**: AI invokes `plan-down` to develop detailed development steps.
2. **Automated Execution**: Creates database models, writes backend routes, and generates frontend templates.
3. **Automated Review and Testing**: Each piece of code is reviewed by `codex-code-reviewer`. AI also invokes `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 rule and skill design of this project follows the core philosophy defined in the global configuration file `CLAUDE.md`.
- **G1: Documentation as First-Class Citizen**: Any code changes must be synchronized and updated to `PROJECTWIKI.md` and `CHANGELOG.md`, ensuring absolute consistency between documentation and code.
- **G8: Mandatory Skill Use (Anti-Laziness Principle)**: Critical tasks (e.g., planning, code review, document generation) must be executed by the most professional skills, eliminating direct processing by the "main model" to ensure output quality.
- **G9: Quantifiable Quality Goals**: All development activities should revolve around clear quality indicators, e.g., setting test coverage targets (`coverage_target`) at the beginning of tasks.
## 📚 Documentation Center
| Document | Content Description |
|----------------------------------------------------------------|----------------------------------------------------------|
| **[PROJECTWIKI.md](./PROJECTWIKI.md)** | **Project Knowledge Base (Core)**: Architecture design, decision records, 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 changes 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 was 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 is licensed under the [Apache 2.0 License](LICENSE).
