Content
# Claude Code Zen MCP Skill Work
[](LICENSE)
[](https://github.com/VCnoC/Claude-Code-Zen-mcp-Skill-Work)
> 🚀 **A ready-to-use rule system and skill package designed for AI programming agents.**
This project is not just a collection of tools, but 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**: Enables AI agents to autonomously call external command-line tools (such as Codex CLI, Gemini CLI) through Zen MCP, enabling 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 Fix, ensuring a clear and controllable process.
- 📝 **Automated Planning (`plan-down`)**: Eliminates manual task decomposition by automatically generating a structured `plan.md` and supporting multi-model validation.
- 🔍 **5-Dimensional Code Review (`codex-code-reviewer`)**: Conducts a comprehensive review and scoring of code from five dimensions: Quality, Security, Performance, Architecture, and Documentation.
- 📄 **Professional Documentation 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 "one-sentence requirement, fully automated development" mode, where AI can autonomously complete the entire process from planning to code implementation, review, testing, and documentation updates.
## 🏗️ Working Principle
The system processes user requests through a four-stage (P1-P4) workflow, centrally orchestrated by `main-router`. This process ensures that each task undergoes thorough analysis, rigorous planning, and strict quality validation.
```mermaid
flowchart LR
A[User Request] --> B(main-router<br/>Intent Recognition & Routing)
B --> C[P1: Analyze Problem<br/>Understand Requirements, Identify Root Cause]
C --> D[P2: Develop Solution<br/>Call plan-down to Generate plan.md]
D --> E[P3: Execute Solution<br/>Coding, Testing, Documentation Updates]
E --> F{Success?}
F -->|Yes| G[✅ Complete]
F -->|No| H[P4: Error Handling<br/>Fix Issues & Verify Through Regression Gate]
H --> G
```
> To learn more about the architecture design, state machine, and data model, please refer to **[PROJECTWIKI.md](./PROJECTWIKI.md)**.
## 🎯 Core Skill Package
This project provides a set of plug-and-play core skills, each empowering the AI agent with 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` File |
| `codex-code-reviewer` | **5-Dimensional Code Quality Review and Automated Fixes** | Quality Report, Fixed 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 Report |
## 🚀 Quick Start
### 1. Environment Requirements
- **[Python](https://www.python.org/)** >= 3.8**
- **[Git](https://git-scm.com/downloads)**
### 2. Installation Steps
This repository contains the **Zen MCP Server** and **core skill packages**, which can be installed in just three steps.
**Step 1: Clone the 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 the One-Click Installation Script**
The script will automatically complete the installation of the Zen MCP Server, copy the 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 unavailable (e.g., from a version cloned from GitHub), please 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 the user directory and install dependencies
2. Create the `~/.claude/` directory structure (if it does not exist)
3. Copy all skill files under `skills/` to `~/.claude/skills/`
4. Copy the `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 Startup
**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 (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 Endpoint (Ollama, vLLM, LM Studio, etc. Local Models)
# 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
```
> **💡 Using Local Models**: To use local inference services such as Ollama, vLLM, or LM Studio, configure the above `CUSTOM_API_*` parameters. To customize model capabilities (extended inference, vision, etc.), you can add model configurations in `zen-mcp-server/conf/custom_models.json`.
**Step 2: Start the Zen MCP Server**
```bash
cd ~/zen-mcp-server
# Recommended: Use the Startup Script (Automatically Configures the 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 startup script provides interactive configuration options. After selecting according to the actual situation, it will automatically write the MCP configuration to the .claude.json file.
```
### 4. Restart Claude code
Completely close Claude code and then restart it.
---
## ✅ Verify Installation
Start Claude code and enter:
```
Please use main-router to help me analyze the currently available skills
```
If you can see detailed descriptions of the 5 skills such as `main-router`, `plan-down`, etc., the installation is successful!
---
## 📖 Usage Examples
### Interactive Mode (Default)
In the default mode, AI will seek your confirmation at key decision points, ensuring you have complete control over the development process.
**Example:**
> `Refactor the auth.py file to improve its readability.`
**AI Response Flow:**
1. **P1 Analysis**: AI analyzes `auth.py`, identifying key areas for refactoring (such as complex functions, duplicate code blocks).
2. **P2 Solution**: AI proposes a refactoring plan (`plan.md`), such as "Split the `authenticate_user` function into three separate 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 tasks with high confidence, you can authorize AI to complete them fully automatically without human intervention.
**Example:**
> `Fully automate the addition of a user registration feature using SQLite to my Flask application, with a test coverage of no less than 85%.`
**AI Response Flow:**
1. **Automatic Planning**: AI calls `plan-down` to develop detailed development steps.
2. **Automatic Execution**: Creates database models, writes backend routes, and generates frontend templates.
3. **Automatic Review and Testing**: Each step of the code is automatically reviewed by `codex-code-reviewer`. AI also calls `simple-gemini` to write test cases, ensuring coverage reaches 85%.
4. **Automatic Logging**: All decisions and operations are recorded in `auto_log.md` for your audit at any time.
---
## 💡 Core Principles
The rules and skill design of this project follow the following core principles, which are defined in the global configuration file `CLAUDE.md`.
- **G1: Documentation as a First-Class Citizen**: Any changes to the code must be synchronized to `PROJECTWIKI.md` and `CHANGELOG.md`, ensuring absolute consistency between documentation and code.
- **G8: Mandatory Skill Usage (Anti-Laziness Principle)**: Critical tasks (such as planning, code review, documentation generation) must be performed 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 metrics. For example, the test coverage target (`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, Module Documentation. |
| **[CLAUDE.md](./CLAUDE.md)** | **Global Rules**: Defines G1-G11 global rules and P1-P4 workflow. |
| **[CHANGELOG.md](./CHANGELOG.md)** | **Change Log**: Records the version change history 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. |
---
## 🙏 Acknowledgments
The implementation of this project is inseparable from the inspiration and support of the following excellent open-source projects:
- **[HelloAgents](https://github.com/hellowind777/helloagents)**: Provided the initial design concepts for the `AGENTS.md` specification and 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).
