# 🛠️ Claude Code Customizations Suite

> **Complete automated setup for 40+ specialized agents, MCP tools, and professional integrations**

---

## 📑 Table of Contents

1. [Overview](#-overview)
2. [What's Included](#️-whats-included)
3. [Directory Structure](#-directory-structure)
4. [Installation](#-installation)
5. [Verification](#-verification)
6. [Configuration](#-configuration)
7. [Key Features](#-key-features)
8. [Troubleshooting](#-troubleshooting)

---

## 🎯 Overview

This repository contains automated scripts to replicate a fully customized Claude Code environment with custom agents, MCP tools, and plugins.

**Package Version:** 1.0.0
**Claude Code Compatible:** Latest (2025+)
**Node.js Required:** 14+
**Platform:** Linux, macOS, WSL2

---

## ✨ What's Included

### 🤖 Custom Agents (40+ specialized agents)

#### Engineering Agents (7)
→ **ai-engineer** - AI/ML feature implementation, LLM integration
→ **backend-architect** - API design, database architecture, server-side logic
→ **devops-automator** - CI/CD pipelines, infrastructure, monitoring
→ **frontend-developer** - React/Vue/Angular UI development
→ **mobile-app-builder** - iOS/Android React Native development
→ **rapid-prototyper** - Quick MVP/prototype building (6-day cycle focused)
→ **test-writer-fixer** - Automatic test writing and fixing

#### Marketing Agents (7)
→ **tiktok-strategist** - TikTok marketing and viral content strategies
→ **growth-hacker** - Growth strategies and viral mechanics
→ **content-creator** - Content creation for various platforms
→ **instagram-curator** - Instagram content strategy
→ **reddit-community-builder** - Reddit community engagement
→ **twitter-engager** - Twitter engagement strategies
→ **app-store-optimizer** - ASO and app store optimization

#### Product Agents (3)
→ **sprint-prioritizer** - 6-day sprint planning and feature prioritization
→ **feedback-synthesizer** - User feedback analysis and insights
→ **trend-researcher** - Market trend identification (TikTok/App Store focus)

#### Studio Operations Agents (8)
→ **studio-producer** - Cross-team coordination and resource allocation
→ **project-shipper** - Launch coordination and go-to-market activities
→ **studio-coach** - Elite performance coach for other agents
→ **analytics-reporter** - Analytics and reporting
→ **finance-tracker** - Financial tracking and management
→ **infrastructure-maintainer** - Infrastructure maintenance
→ **legal-compliance-checker** - Legal and compliance checks
→ **support-responder** - Customer support responses

#### Project Management Agents (3)
→ **experiment-tracker** - A/B test and experiment tracking
→ **project-shipper** - Project shipping coordination
→ **studio-producer** - Studio production management

#### Testing Agents (6)
→ **test-writer-fixer** - Test writing and fixing (code change triggered)
→ **api-tester** - API testing
→ **performance-benchmarker** - Performance benchmarking
→ **test-results-analyzer** - Test results analysis
→ **tool-evaluator** - Tool evaluation
→ **workflow-optimizer** - Workflow optimization

#### Design Agents (6)
→ **ui-ux-pro-max** - Professional UI/UX design with 50+ styles, 97 palettes, WCAG
→ **ui-designer** - UI design and implementation
→ **ux-researcher** - UX research and user experience
→ **brand-guardian** - Brand consistency
→ **visual-storyteller** - Visual storytelling
→ **whimsy-injector** - Add delightful/playful UI elements (auto-triggered after UI changes)

#### Bonus Agents (2)
→ **studio-coach** - Performance coaching
→ **joker** - Humor and entertainment

---

### 🔧 MCP (Model Context Protocol) Tools

#### Vision Analysis Tools (`mcp__zai-mcp-server__`)

→ **analyze_image** - General-purpose image analysis
→ **analyze_video** - Video content analysis (MP4, MOV, M4V up to 8MB)
→ **ui_to_artifact** - Convert UI screenshots to:
  → `code` - Generate frontend code
  → `prompt` - Generate AI prompt for recreation
  → `spec` - Extract design specifications
  → `description` - Natural language description
→ **extract_text_from_screenshot** - OCR text extraction from screenshots
→ **diagnose_error_screenshot** - Error message and stack trace diagnosis
→ **ui_diff_check** - Compare two UI screenshots for differences
→ **analyze_data_visualization** - Extract insights from charts/graphs/dashboards
→ **understand_technical_diagram** - Analyze architecture/flowchart/UML/ER diagrams

#### Web & Research Tools

→ **mcp__web-search-prime__webSearchPrime** - Enhanced web search with:
  → Domain filtering (whitelist/blacklist)
  → Time-based filtering (day/week/month/year)
  → Location-based results (CN/US)
  → Content size control (medium/high)

→ **mcp__web-reader__webReader** - Web scraper and converter:
  → Fetch any URL
  → Convert to markdown or text
  → Image handling
  → Link and image summaries

#### GitHub Tools (`mcp__zread__`)

→ **get_repo_structure** - Get GitHub repo directory structure
→ **read_file** - Read files from GitHub repos
→ **search_doc** - Search GitHub repo docs, issues, commits

#### Additional Tools

→ **mcp__4_5v_mcp__analyze_image** - Image analysis with URL support
→ **mcp__glm_camp_server__claim_glm_camp_coupon** - Claim GLM promotional rewards

---

### 🎯 Custom Skills

→ **glm-plan-bug:case-feedback** - Submit bug/issue feedback for GLM Coding Plan
→ **glm-plan-usage:usage-query** - Query GLM Coding Plan usage statistics

---

## 📁 Directory Structure

```
~/.claude/
├── agents/
│   ├── engineering/          # 7 engineering agents
│   ├── marketing/            # 7 marketing agents
│   ├── product/              # 3 product agents
│   ├── studio-operations/    # 8 studio operations agents
│   ├── project-management/   # 3 project management agents
│   ├── testing/              # 6 testing agents
│   ├── design/               # 6 design agents
│   └── bonus/                # 2 bonus agents
├── plugins/
│   ├── cache/                # Downloaded plugins
│   ├── marketplaces/         # Plugin marketplaces
│   ├── installed_plugins.json
│   └── known_marketplaces.json
├── hooks/                    # Custom hooks
├── settings.json             # Main settings
└── settings.local.json       # Local permissions
```

---

## 🚀 Installation

### Option 1: Export from Existing Machine

If you have an existing machine with these customizations:

```bash
# 1. Export customizations
./export-claude-customizations.sh

# 2. Transfer the archive to new machine
scp claude-customizations-*.tar.gz user@new-machine:~/

# 3. On new machine, extract and install
tar -xzf claude-customizations-*.tar.gz
cd claude-customizations-export
./install-claude-customizations.sh
```

---

### Option 2: Fresh Installation

For a fresh installation on a new machine:

```bash
# 1. Download or clone the setup scripts
# 2. Run the installer
./install-claude-customizations.sh

# 3. Copy agent definitions from source (if available)
scp -r user@source:~/.claude/agents/* ~/.claude/agents/

# 4. Restart Claude Code
```

---

### Option 3: Manual Installation

```bash
# 1. Create directory structure
mkdir -p ~/.claude/agents/{engineering,marketing,product,studio-operations,project-management,testing,design,bonus}
mkdir -p ~/.claude/plugins/{cache,marketplaces}

# 2. Install MCP tools
npm install -g @z_ai/mcp-server @z_ai/coding-helper

# 3. Create settings.json
cat > ~/.claude/settings.json << 'EOF'
{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "YOUR_TOKEN_HERE",
    "ANTHROPIC_BASE_URL": "https://api.anthropic.com",
    "API_TIMEOUT_MS": "3000000",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
  },
  "enabledPlugins": {
    "glm-plan-bug@zai-coding-plugins": true,
    "glm-plan-usage@zai-coding-plugins": true
  }
}
EOF

# 4. Copy agent files (from source or repository)
# 5. Copy plugin configurations
# 6. Restart Claude Code
```

---

## ✅ Verification

After installation, verify everything is working:

### 1. Check agents are loaded

```bash
ls -la ~/.claude/agents/*/
```

### 2. Check MCP tools

→ Start a Claude Code session
→ The tools should be available automatically
→ Check for `mcp__zai-mcp-server__*` tools
→ Check for `mcp__web-search-prime__webSearchPrime`
→ Check for `mcp__web-reader__webReader`
→ Check for `mcp__zread__*` tools

### 3. Check plugins

```bash
cat ~/.claude/plugins/installed_plugins.json
```

### 4. Test a custom agent

```
Use the Task tool with subagent_type="tiktok-strategist"
```

---

## ⚙️ Configuration

### API Credentials

Edit `~/.claude/settings.json` and add your credentials:

```json
{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "your-api-token-here",
    "ANTHROPIC_BASE_URL": "https://api.anthropic.com"
  }
}
```

### Permissions

Edit `~/.claude/settings.local.json` to customize allowed commands.

### Agent Customization

Each agent is defined in a `.md` file in `~/.claude/agents/<category>/`. Edit these files to customize agent behavior.

### MCP Server Configuration

MCP servers are configured through the `@z_ai/coding-helper` package. The preset MCP services include:

1. **zai-mcp-server** - Vision analysis (installed via npm/npx)
2. **web-search-prime** - Web search (HTTP endpoint)
3. **web-reader** - Web scraping (HTTP endpoint)
4. **zread** - GitHub reader (HTTP endpoint)

---

## 🎨 Key Features

### 6-Day Development Cycle Focus

Many agents are optimized for rapid 6-day development sprints:
→ **sprint-prioritizer** - Plan sprints
→ **rapid-prototyper** - Quick MVPs
→ **project-shipper** - Launch coordination
→ **studio-producer** - Resource management

### Automatic Quality Assurance

Certain agents trigger automatically:
→ **test-writer-fixer** - Auto-runs after code changes
→ **whimsy-injector** - Auto-triggers after UI changes

### Viral Marketing Focus

Multiple agents for app growth:
→ **tiktok-strategist** - TikTok-specific strategies
→ **trend-researcher** - Identifies viral trends
→ **growth-hacker** - Growth strategies

### Studio Production Workflow

Agents for team coordination:
→ **studio-producer** - Cross-team coordination
→ **studio-coach** - Performance coaching
→ **project-shipper** - Launch management

---

## 🔧 Troubleshooting

### MCP Tools Not Working

1. Check npm packages are installed:
   ```bash
   npm list -g @z_ai/mcp-server @z_ai/coding-helper
   ```

2. Verify settings.json has correct configuration

3. Check Claude Code is using the latest version

### Agents Not Showing

1. Verify agent files exist in `~/.claude/agents/`
2. Check file permissions
3. Restart Claude Code completely

### Plugin Issues

1. Check `~/.claude/plugins/installed_plugins.json`
2. Verify plugin cache exists
3. Re-run installation script

---

## 🏗️ Architecture

### How Custom Agents Work

Each agent is a markdown file with:
→ Name and description
→ System prompt/instructions
→ Tool access permissions
→ Trigger conditions

Agents are invoked via the Task tool:
```
Task(subagent_type="tiktok-strategist", prompt="...")
```

### How MCP Tools Work

MCP tools are registered via Model Context Protocol servers:
1. Server is defined in `@z_ai/coding-helper`
2. Server starts (stdio or HTTP)
3. Claude Code discovers available tools
4. Tools are invoked with parameters
5. Results return to Claude

### How Plugins Work

Plugins are npm packages with:
→ `plugin.json` - Metadata
→ `skills/` - Skill definitions
→ `hooks/` - Event hooks
→ `.mcp.json` - MCP server config (optional)

---

## 🚀 Advanced Usage

### Creating Custom Agents

1. Create a new `.md` file in appropriate category
2. Follow existing agent structure
3. Restart Claude Code
4. Use via Task tool

### Adding New MCP Tools

1. Install MCP server: `npm install -g <mcp-package>`
2. Configure in settings or via `@z_ai/coding-helper`
3. Restart Claude Code
4. Tools become available automatically

### Creating Custom Skills

1. Create plugin structure
2. Add skill definitions
3. Register in `installed_plugins.json`
4. Invoke via Skill tool

---

## 📞 Support and Contributions

For issues, questions, or contributions:
1. Check existing documentation
2. Review agent definitions for examples
3. Test with simple tasks first
4. Enable debug mode if needed

---

## 📝 License

These customizations are provided as-is for use with Claude Code.

---

## 📋 Changelog

### Version 1.0.0 (2025-01-15)
→ Initial release
→ 40+ custom agents across 8 categories
→ 4 MCP tool integrations
→ 2 custom skills
→ Automated installation scripts
→ Complete documentation

---

**Generated by Claude Code Customizations Package**
**Last Updated:** 2025-01-16
**Version:** 1.0.0