Publisher

Make your skills easy to understand and impossible to ignore

Security Scan

The skill's files and runtime instructions are consistent with its stated purpose (generating README text and publishing a skill); it requires the user's existing GitHub/ClawdHub tooling and will modify and push repository files as expected.

Purpose & Capability

The name/description (generate README + publish) match the script and SKILL.md: the tool parses SKILL.md and VERSION, generates one-liners, updates SKILL.md frontmatter, initializes git, creates/pushes a GitHub repo with `gh`, and publishes with `clawdhub`. Required CLIs (gh, clawdhub, jq, git) are appropriate for these actions.

Instruction Scope

Runtime instructions and the script stay within the stated scope. The script reads SKILL.md and VERSION, may update SKILL.md description, may prompt to overwrite or require README.md, initializes a git repo if missing, creates/pushes a GitHub repo via `gh`, and runs `clawdhub publish`. These file writes, commits, and remote publishes are expected behavior for a publishing tool; users should be aware it will modify files and push to remotes.

Install Mechanism

No install spec is included; the package is instruction + shell script only. Nothing is downloaded from external URLs or extracted. This low-risk approach is proportionate to the skill's purpose.

Credentials

The skill requests no environment variables and does not embed credential handling. It relies on existing `gh` and `clawdhub` authentication (normal for tools that create repos and publish). There are no unrelated secrets or external credential requests in the files.

Persistence & Privilege

The skill does not request permanent/always-on presence and will not modify other skills or global agent settings. It performs user-triggered actions (file edits, git operations, remote publish) consistent with its purpose.

Assessment

This tool appears internally consistent and does what it claims, but before running: (1) ensure you have authenticated `gh` and `clawdhub` (it will use your accounts to create repos and publish); (2) be aware it may update SKILL.md frontmatter, overwrite README.md, initialize a git repo, commit, and push — back up files if you want to review changes first; (3) the script prompts before destructive actions, but double-check the chosen one-liner and generated README content before confirming publish; (4) if you lack GitHub/ClawdHub auth, `gh`/`clawdhub` will control what happens (the script will fail rather than exfiltrate secrets).

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

1. Reads your SKILL.md to understand what the skill does
2. Generates 3 one-liner options using proven patterns
3. Creates a README following GitHub best practices:
   • Problem/solution upfront
   • Inverted pyramid structure
   • Emoji headers for scannability
   • Bold outcomes
   • Under 15% text highlighting
4. Updates SKILL.md frontmatter with chosen description

Publishing

5. Creates GitHub repository (if doesn't exist)
6. Pushes code to GitHub
7. Publishes to ClawdHub with auto-detected version

---

🚀 Installation

clawdhub install skill-publisher

---

💡 Usage

cd ~/clawd/skills/your-skill
skill-publisher

The script will:

1. Show 3 one-liner options (choose or write your own)
2. Generate README preview
3. Ask for approval
4. 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

1. Checks for gh CLI (guides setup if missing)
2. Reads VERSION file for version number
3. Creates GitHub repo (using gh repo create)
4. Commits and pushes all files
5. 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