publisher
Professional documentation and publishing for Clawdbot skills
Generate adoption-optimized READMEs and publish to GitHub + ClawdHub with one command.
⚠️ Requirements
- bash
jq (for JSON parsing)gh CLI (GitHub operations)clawdhub CLI (publishing)- git
📋 What It Does
Automates the complete publishing workflow:
Documentation Generation
- Reads your SKILL.md to understand what the skill does
- Generates 3 one-liner options using proven patterns
- Creates a README following GitHub best practices:
- Problem/solution upfront
- Inverted pyramid structure
- Emoji headers for scannability
- Bold outcomes
- Under 15% text highlighting
- Updates SKILL.md frontmatter with chosen description
Publishing
- Creates GitHub repository (if doesn't exist)
- Pushes code to GitHub
- Publishes to ClawdHub with auto-detected version
🚀 Installation
clawdhub install skill-publisher
💡 Usage
cd ~/clawd/skills/your-skill
skill-publisher
The script will:
- Show 3 one-liner options (choose or write your own)
- Generate README preview
- Ask for approval
- Publish to GitHub + ClawdHub
🎯 One-Liner Generation Patterns
The tool generates options using three proven patterns:
Pattern A: Continuous Benefit
Keep [thing] [desired state] [timeframe]
Example: "Keep your Claude access token fresh 24/7"
Pattern B: Elimination
[Do thing] without [pain point]
Example: "Build cross-device tools without hardcoding paths"
Pattern C: Automation
Automatically [action] [thing] [when]
Example: "Automatically refresh tokens before they expire"
📚 README Structure Generated
Follows the framework from GitHub's documentation best practices:
Essential Sections (above the fold)
- Title + subtitle
- The problem: (1 sentence)
- This tool: (1 sentence)
- 📋 Requirements
- ⚡ What It Does (outcome first, then features)
- 🚀 Installation
- 🔧 How It Works (result first, then process)
Optional Sections (collapsible)
- Configuration options
- Troubleshooting
- For Developers
- Implementation details
🔧 How It Works
Phase 1: Analysis
- Reads SKILL.md frontmatter (if exists)
- Extracts key information: name, description, requirements
- Parses scripts for dependencies
Phase 2: One-Liner Generation
Analyzes your SKILL.md description and generates 3 options:
- Pattern A: Continuous benefit format
- Pattern B: Pain point elimination format
- Pattern C: Automation format
Shows you all 3, lets you choose or write custom.
Phase 3: README Generation
Uses the template from ~/clawd/templates/README-template.md:
- Fills in title, problem, solution
- Extracts requirements from SKILL.md
- Generates "What It Does" from description
- Creates installation steps
- Builds "How It Works" with examples
Phase 4: Publishing
- Checks for
gh CLI (guides setup if missing) - Reads VERSION file for version number
- Creates GitHub repo (using
gh repo create) - Commits and pushes all files
- Publishes to ClawdHub with
clawdhub publish
📁 File Structure Expected
your-skill/
├── SKILL.md # Required: skill description
├── VERSION # Required: version number (e.g., "1.0.0")
├── scripts/ # Optional: your scripts
│ └── main.sh
├── README.md # Generated by this tool
└── .gitignore # Optional
⚙️ Configuration
No configuration needed. The tool auto-detects everything from:
SKILL.md (name, description, requirements)VERSION (version number)scripts/ (code examples, dependencies)
🐛 Troubleshooting
"gh: command not found"
Install GitHub CLI:
brew install gh
gh auth login
"SKILL.md not found"
Create a minimal SKILL.md:
---
name: your-skill
description: Brief description of what it does
---
# your-skill
More details about your skill here.
"VERSION file not found"
Create a VERSION file:
echo "1.0.0" > VERSION
📖 References
- GitHub documentation best practices: https://docs.github.com/en/contributing/writing-for-github-docs/best-practices-for-github-docs
- README template:
~/clawd/templates/README-template.md - One-liner formulas: See "One-Liner Generation Patterns" section above
License
MIT