Clawhub Publishing Workflow

SKILL.md

---
name: ClawHub Publishing Workflow
description: Complete workflow for publishing OpenClaw skills to ClawHub - includes authentication troubleshooting, bot detection workarounds, and the mother skill philosophy.
status: Production Ready
version: 1.0.0
---

# ClawHub Publishing Workflow 🚀

**Description:** Complete workflow for publishing OpenClaw skills to ClawHub - includes authentication troubleshooting, bot detection workarounds, and the mother skill philosophy.

**Status:** ✅ **PRODUCTION READY** (Version 1.0.0)

## 🎯 When to Use

- Publishing a new skill to ClawHub for the first time
- Updating an existing published skill
- Troubleshooting ClawHub authentication issues
- Understanding bot detection challenges with ClawHub
- Implementing the "mother skill" philosophy

## 📋 Prerequisites

1. **ClawHub CLI installed:**
   ```bash
   npm install -g clawhub
   ```

2. **GitHub account** (for ClawHub registration)
3. **ClawHub API token** from: https://clawhub.ai/settings/tokens

## 🚀 Complete Workflow

### Phase 1: Authentication (DISCOVERED METHOD)
```bash
# Get token from ClawHub settings (format: clh_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx)
# Then use the CORRECT authentication method (discovered through trial and error):
clawhub login --token "YOUR_TOKEN_HERE" --no-browser

# Verify authentication:
clawhub whoami
# Should show: ✔ your-username

# WRONG METHODS WE TRIED:
# ❌ export CLAWHUB_TOKEN="token" (doesn't work)
# ❌ echo "token" > ~/.clawhub/token (doesn't work)
# ✅ clawhub login --token "token" --no-browser (CORRECT)
```

### Phase 2: Skill Preparation
```bash
# 1. Create skill directory structure
your-skill/
├── SKILL.md
├── references/ (optional)
├── templates/ (optional)
├── scripts/ (optional)
└── assets/ (optional)

# 2. Validate skill structure
./scripts/validate.sh

# 3. Check for personal information (critical for community sharing)
grep -i "C:\\\\\\\\\|/home/\|password\|token\|secret" SKILL.md || echo "Clean"
```

### Phase 3: Publishing
```bash
# IMPORTANT: Version must be valid semver (2.2.0 not 2.2)
clawhub publish /path/to/your-skill \
  --slug "your-unique-slug" \
  --name "Skill Display Name" \
  --version "1.0.0" \
  --changelog "Initial release"

# Slug rules:
# - Lowercase, hyphens only
# - Must be globally unique on ClawHub
# - If taken, append "-v2" or "-backup"
```

### Phase 4: Verification
```bash
# Skill undergoes security scan (takes a few minutes)
clawhub inspect your-slug

# Once scan completes, skill is available at:
# https://clawhub.ai/s/YOUR_USERNAME/your-slug
```

## ⚠️ Pitfalls & Solutions (LEARNED FROM EXPERIENCE)

### Pitfall 1: Bot Detection (Vercel Security Checkpoint)
**Symptoms:** "We're verifying your browser" page blocks authentication
**Solution:** 
- Use token authentication (`clawhub login --token --no-browser`)
- For browser auth: Enable Camo Fox + residential proxies in BrowserBase

### Pitfall 2: Incorrect Authentication Methods
**Symptoms:** "Not logged in" despite having token
**Solution:** Use exact command: `clawhub login --token TOKEN --no-browser`

### Pitfall 3: Invalid Semver Version
**Symptoms:** "--version must be valid semver" error
**Solution:** Use proper semver: "1.0.0", "2.2.0" (not "2.2")

### Pitfall 4: Slug Conflicts
**Symptoms:** "Only the owner can publish updates"
**Solution:** Check slug availability, use unique slug

## ✅ Verification Steps

### Authentication Test
```bash
clawhub whoami
# Expected: ✔ username
```

### Skill Structure Test
```bash
# Create validation script in your skill:
cat > scripts/validate.sh << 'EOF'
#!/bin/bash
echo "=== Skill Validation ==="
[ -f "SKILL.md" ] && echo "✅ SKILL.md exists" || echo "❌ SKILL.md missing"
EOF
chmod +x scripts/validate.sh
```

### Publish Test
```bash
# No dry-run option available, so publish small test skill first
```

## 🦊 Bot Detection & Camo Fox

### When Browser Auth is Required
If you need browser authentication (for token generation):
1. Enable Camo Fox in BrowserBase dashboard
2. Configure residential proxies
3. Use browser with stealth features enabled

### Environment Variables for BrowserBase
```bash
export BROWSERBASE_CAMO_FOX=true
export BROWSERBASE_PROXY_TYPE=residential
```

## 🐕 Mother Skill Philosophy

A **mother skill** is:
- **Comprehensive**: End-to-end solution for a specific problem
- **Battle-tested**: Proven in real-world use
- **Community-evolved**: Improves with community feedback
- **Branded**: British dry humour + canine wisdom (optional but fun)

### Brand Elements (Optional)
- British phrases: "Right then", "Bob's your uncle", "Sorted"
- Canine personas: Romeo, Luna, Buster, Thomas
- Signature: "Put that in your pipe and smoke it!"

## 🔧 Troubleshooting Commands

```bash
# Check CLI version
clawhub -V

# Check authentication methods
clawhub auth --help

# Get token help
clawhub login --help

# List your published skills
# Visit: https://clawhub.ai/u/YOUR_USERNAME
```

## 📁 Example Skill Structure

```
clawhub-publish-mother-skill/
├── SKILL.md                    # Main documentation
├── scripts/
│   ├── validate.sh            # Validation script
│   └── test-publish.sh        # Test publishing
└── references/
    ├── checklist.md           # Publishing checklist
    └── camo-fox.md           # Bot detection guide
```

## 🔄 Version History

- **v1.0.0:** Initial skill creation with discovered authentication method
- **v1.0.1:** Added bot detection guidance and mother skill philosophy

## 🤝 Community Contributions

This skill documents approaches discovered through trial and error. If you find better methods, update and share!

**HELL YEAH, ClawHub publishing mastered!** 🎯

*Based on real discovery: clawhub login --token TOKEN --no-browser*
*British dry humour + canine personas optional but recommended*