Initial commit: Claude Code Customization Suite - 40+ agents, MCP tools, and automation scripts
This commit is contained in:
uroma
295
SCRIPTS-GUIDE.md
Normal file
295
SCRIPTS-GUIDE.md
Normal file
@@ -0,0 +1,295 @@
|
||||
# Claude Code Customizations - Scripts Guide
|
||||
|
||||
This guide explains all the automated scripts created for managing Claude Code customizations.
|
||||
|
||||
## Available Scripts
|
||||
|
||||
### 1. `install-claude-customizations.sh` 📥
|
||||
|
||||
**Purpose**: Automated installer for setting up Claude Code customizations on a new machine.
|
||||
|
||||
**Usage**:
|
||||
```bash
|
||||
./install-claude-customizations.sh
|
||||
```
|
||||
|
||||
**What it does**:
|
||||
- Checks prerequisites (Node.js, npm, python3, curl)
|
||||
- Creates directory structure (~/.claude/agents/, plugins/, etc.)
|
||||
- Configures settings.json and settings.local.json
|
||||
- Installs MCP tools (@z_ai/mcp-server, @z_ai/coding-helper)
|
||||
- Sets up plugin configurations
|
||||
- Creates agent directory structure (you must copy agent files separately)
|
||||
|
||||
**Options**:
|
||||
- `--skip-agents` - Skip agent file copying (if already present)
|
||||
- `--help` - Show help message
|
||||
|
||||
**Best for**: Fresh installation on a new machine when you have access to agent files from another source.
|
||||
|
||||
---
|
||||
|
||||
### 2. `export-claude-customizations.sh` 📦
|
||||
|
||||
**Purpose**: Export/pack existing customizations for transfer to another machine.
|
||||
|
||||
**Usage**:
|
||||
```bash
|
||||
./export-claude-customizations.sh
|
||||
```
|
||||
|
||||
**What it does**:
|
||||
- Copies all agent definitions from ~/.claude/agents/
|
||||
- Exports plugin configurations
|
||||
- Creates settings template (without sensitive API tokens)
|
||||
- Exports hooks if present
|
||||
- Creates README and MANIFEST
|
||||
- Packages everything into a .tar.gz archive
|
||||
|
||||
**Output**:
|
||||
- `claude-customizations-YYYYMMDD_HHMMSS.tar.gz` - Compressed archive
|
||||
- `claude-customizations-export/` - Unpacked directory (optional cleanup)
|
||||
|
||||
**Best for**: Backing up your customizations or transferring to another machine.
|
||||
|
||||
---
|
||||
|
||||
### 3. `create-complete-package.sh` 🎁
|
||||
|
||||
**Purpose**: Creates a complete, distributable package with ALL agent files included.
|
||||
|
||||
**Usage**:
|
||||
```bash
|
||||
./create-complete-package.sh
|
||||
```
|
||||
|
||||
**What it does**:
|
||||
- Copies ALL agent files from current machine
|
||||
- Copies plugin configurations
|
||||
- Creates settings templates
|
||||
- Copies hooks
|
||||
- Generates install.sh script (self-contained installer)
|
||||
- Generates verify.sh script
|
||||
- Creates comprehensive README
|
||||
- Packages everything into .tar.gz archive
|
||||
|
||||
**Output**:
|
||||
- `claude-customizations-complete-YYYYMMDD_HHMMSS.tar.gz` - Complete package
|
||||
- `claude-complete-package/` - Unpacked directory with:
|
||||
- `agents/` - All agent .md files
|
||||
- `plugins/` - Plugin configurations
|
||||
- `config/` - Settings templates
|
||||
- `install.sh` - Automated installer
|
||||
- `verify.sh` - Verification script
|
||||
- `README.md` - Package documentation
|
||||
- `MANIFEST.json` - Package metadata
|
||||
|
||||
**Best for**: Creating a complete, ready-to-distribute package that includes everything.
|
||||
|
||||
---
|
||||
|
||||
### 4. `verify-claude-setup.sh` ✅
|
||||
|
||||
**Purpose**: Verify that customizations are properly installed.
|
||||
|
||||
**Usage**:
|
||||
```bash
|
||||
./verify-claude-setup.sh
|
||||
```
|
||||
|
||||
**What it checks**:
|
||||
- Directory structure (Claude, agents, plugins)
|
||||
- Agent categories (8 categories)
|
||||
- Configuration files (settings.json, etc.)
|
||||
- MCP tools availability (npx, @z_ai packages)
|
||||
- Plugin registrations (glm-plan-bug, glm-plan-usage)
|
||||
- Critical agent files exist and have content
|
||||
- Settings file validity (JSON format, API token configured)
|
||||
|
||||
**Output**:
|
||||
- Pass/Fail status for each check
|
||||
- Summary with totals
|
||||
- Exit code 0 if all pass, 1 if any fail
|
||||
|
||||
**Best for**: Troubleshooting installation issues or confirming setup is complete.
|
||||
|
||||
---
|
||||
|
||||
## Workflow Examples
|
||||
|
||||
### Scenario 1: Transfer to New Machine
|
||||
|
||||
**On source machine**:
|
||||
```bash
|
||||
# Create complete package
|
||||
./create-complete-package.sh
|
||||
|
||||
# Transfer archive
|
||||
scp claude-customizations-complete-*.tar.gz user@new-machine:~/
|
||||
```
|
||||
|
||||
**On new machine**:
|
||||
```bash
|
||||
# Extract
|
||||
tar -xzf claude-customifications-complete-*.tar.gz
|
||||
cd claude-complete-package
|
||||
|
||||
# Install
|
||||
./install.sh
|
||||
|
||||
# Verify
|
||||
./verify.sh
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Scenario 2: Fresh Install Without Agent Files
|
||||
|
||||
```bash
|
||||
# Run installer (creates directory structure)
|
||||
./install-claude-customizations.sh
|
||||
|
||||
# Manually copy agent files
|
||||
scp -r user@source:~/.claude/agents/* ~/.claude/agents/
|
||||
|
||||
# Verify
|
||||
./verify-claude-setup.sh
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Scenario 3: Backup Customizations
|
||||
|
||||
```bash
|
||||
# Export current setup
|
||||
./export-claude-customizations.sh
|
||||
|
||||
# Store archive safely
|
||||
mv claude-customizations-*.tar.gz ~/backups/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Scenario 4: Create Distribution Package
|
||||
|
||||
```bash
|
||||
# Create complete package for distribution
|
||||
./create-complete-package.sh
|
||||
|
||||
# Upload to share location
|
||||
# (GitHub Releases, Google Drive, etc.)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Script Comparison
|
||||
|
||||
| Script | Creates Package | Installs | Verifies | Includes Agents |
|
||||
|--------|----------------|----------|----------|-----------------|
|
||||
| install-claude-customizations.sh | ❌ | ✅ | ❌ | ❌ (copies structure only) |
|
||||
| export-claude-customizations.sh | ✅ | ❌ | ❌ | ✅ |
|
||||
| create-complete-package.sh | ✅ | ✅ (via install.sh) | ✅ (via verify.sh) | ✅ |
|
||||
| verify-claude-setup.sh | ❌ | ❌ | ✅ | N/A |
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference
|
||||
|
||||
### To Install Everything:
|
||||
```bash
|
||||
./create-complete-package.sh # On machine with customizations
|
||||
# Transfer to new machine, then:
|
||||
./install.sh # Included in package
|
||||
./verify.sh # Included in package
|
||||
```
|
||||
|
||||
### To Just Backup:
|
||||
```bash
|
||||
./export-claude-customizations.sh
|
||||
```
|
||||
|
||||
### To Just Verify:
|
||||
```bash
|
||||
./verify-claude-setup.sh
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## File Locations
|
||||
|
||||
All scripts are located in: `/home/uroma/`
|
||||
|
||||
- `install-claude-customizations.sh`
|
||||
- `export-claude-customizations.sh`
|
||||
- `create-complete-package.sh`
|
||||
- `verify-claude-setup.sh`
|
||||
|
||||
Documentation:
|
||||
- `CLAUDE-CUSTOMIZATIONS-README.md` - Complete feature documentation
|
||||
- `SCRIPTS-GUIDE.md` - This file
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Script not executable?
|
||||
```bash
|
||||
chmod +x /path/to/script.sh
|
||||
```
|
||||
|
||||
### Permission denied?
|
||||
```bash
|
||||
bash /path/to/script.sh
|
||||
```
|
||||
|
||||
### npx not found?
|
||||
```bash
|
||||
# Install Node.js from https://nodejs.org/
|
||||
# Or use nvm: curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
|
||||
```
|
||||
|
||||
### Agent files not copying?
|
||||
- Check source directory exists: `ls ~/.claude/agents/`
|
||||
- Check permissions: `ls -la ~/.claude/agents/`
|
||||
- Verify script has read permissions
|
||||
|
||||
---
|
||||
|
||||
## Customization
|
||||
|
||||
### Modify Agent Categories
|
||||
|
||||
Edit the `CATEGORIES` array in scripts:
|
||||
```bash
|
||||
CATEGORIES=("engineering" "marketing" "product" "studio-operations" "project-management" "testing" "design" "bonus")
|
||||
```
|
||||
|
||||
### Add Custom MCP Tools
|
||||
|
||||
Edit the MCP installation section in install scripts:
|
||||
```bash
|
||||
npm install -g your-custom-mcp-server
|
||||
```
|
||||
|
||||
### Change Package Format
|
||||
|
||||
Edit the tar command in export scripts:
|
||||
```bash
|
||||
# For zip instead:
|
||||
zip -r package.zip claude-complete-package/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Support
|
||||
|
||||
For issues with:
|
||||
- **Scripts**: Check script permissions and dependencies
|
||||
- **Installation**: Run verify script to identify issues
|
||||
- **Agent behavior**: Check agent .md files in ~/.claude/agents/
|
||||
- **MCP tools**: Verify npm packages installed with `npm list -g`
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: 2025-01-15
|
||||
**Version**: 1.0.0
|
||||
Reference in New Issue
Block a user