skill-releaser

What this skill does

# Skill Releaser

Orchestrates the full skill publication pipeline from internal repo to ClawhHub.

## When to Use

- User says "release {skill}" or "publish {skill} to clawhub"
- User says "prepare {skill} for release" or "check release readiness"
- User says "review {skill} for publication"
- Cron-triggered release check during refactory pipeline

## Assumptions

**How OpenClaw and user interact during release:**
- Agent runs on a machine with shell access (exec tool) for git and CLI operations
- User communicates via messaging channel (Telegram, Discord, Signal, etc.) — likely on a phone
- User reviews the private GitHub repo directly in their browser/phone — the repo IS the review artifact, not a text summary
- User approves or rejects by replying to the agent's message (natural language: "approve", "revise: fix the readme", "reject")
- Agent can create and manage GitHub repos via `gh` CLI on behalf of the user's authenticated account
- Agent pushes to the private staging repo BEFORE requesting user review, so there is something to review
- Agent does NOT publish anything publicly without explicit user approval — this is a hard gate
- The repo starts private for staging and review. At release time, history is erased via orphan branch + force push (single clean commit), then flipped to public
- The full release can span multiple sessions — the private staging repo preserves state so any agent can resume
- Multiple skills can be in different stages of the pipeline simultaneously

## Prerequisites

- `gh` CLI authenticated (for repo creation and visibility changes)
- `clawhub` CLI installed (for ClawhHub publishing)
- A skill directory with at least a `SKILL.md` file

## Scope & Boundaries

**This skill handles:** The full release pipeline — structure scaffolding, OPSEC scanning, review, publishing.
**This skill does NOT handle:** Skill content creation or design. The SKILL.md must already describe what the skill does. Everything else (boilerplate, structure, scaffolding) is this pipeline's job.

A user with a finished SKILL.md should be able to say "release this skill" and this skill handles everything from there — including generating all missing structure files.

## Automation Model

The pipeline has two fully automated phases separated by one human gate. **Both single and batch releases follow the same model.**

### Single Skill
```
Phase 1 (AUTO): Steps 1-7 — scaffold, validate, stage, scan, review, push
     ↓
  GATE: User reviews private repo, replies "approve" / "revise" / "reject"
     ↓
Phase 2 (AUTO): Steps 9-12 — erase history, flip public, publish, verify scan, deliver
```

### Batch Release (multiple skills)
```
Phase 1 (PARALLEL): Spawn subagents — one per skill, all run Phase 1 simultaneously
     ↓
  GATE: ONE batch review message with all repo links
        User replies: "approve all" / "approve A,C; revise B: fix readme"
     ↓
Phase 2 (PARALLEL): Spawn subagents for approved skills, all publish simultaneously
     ↓
  DELIVERY: ONE batch summary with all links and scan results
```

**Batch rules:**
- Never serialize releases — spawn parallel subagents for Phase 1
- Never block on one approval to start the next Phase 1
- Assign each skill a short unique ID (A, B, C...) in the batch review message
- Collect all Phase 1 results, present ONE batch review message with short IDs
- Accept batch approvals: "approve all" / "approve A,C" / "revise B: fix readme"
- Run all Phase 2s in parallel after approval

**Design principles:**
- User says "release these skills" once. Agent runs all Phase 1s in parallel without interruption.
- Agent sends ONE message: all review links + recommendations. Then waits.
- User replies once. Agent runs all Phase 2s in parallel without interruption.
- Agent sends ONE delivery message with all results.
- If any step fails, agent fixes it automatically and continues. Only report to user if unfixable.
- Rate limits, retries, and delays are handled silently (sleep + retry, not "rate limited, should I try again?")

**Anti-patterns (never do these):**
- Do not serialize releases — always parallelize with subagents
- Do not block on approval for skill A before starting Phase 1 for skill B
- Do not send per-skill review messages — batch them
- Do not ask "should I create the repo?" — just create it
- Do not report intermediate steps — only the batch review and batch delivery
- Do not ask about rate limits or transient errors — retry silently

## Process

### Step 1: Structure Scaffolding (Auto-Generate Boilerplate)
Before any quality checks, generate all missing structure files from the existing SKILL.md:

**Auto-generate if missing:**

| File | Source | Generation Method |
|------|--------|-------------------|
| `skill.yml` | SKILL.md frontmatter + triggers | Extract name, description, version, triggers from SKILL.md |
| `README.md` | SKILL.md description + usage | GitHub landing page for humans: what it does, how to install, future work. NOT agent instructions. |
| `CHANGELOG.md` | Version from skill.yml + git log | `## v{version} — {date}` + summary of current state |
| `tests/test-triggers.json` | SKILL.md triggers + "When to Use" | `shouldTrigger` from triggers list, `shouldNotTrigger` from anti-patterns |
| `scripts/` | Create directory | Empty dir or placeholder README if no scripts needed |
| `references/` | Create directory | Empty dir or placeholder README if no references needed |
| `LICENSE` | Default MIT | Standard MIT license text |
| `.gitignore` | Standard | `node_modules/`, `.DS_Store`, `*.log` |

**Rules:**
- Never overwrite existing files — only generate what's missing
- All generated content derives from SKILL.md — no hallucinated features
- If SKILL.md lacks enough info to generate a file, flag it as a content gap (user must fix SKILL.md first)
- Generated README.md must make sense to a stranger who has never seen the skill before

**Validation after scaffolding:**
- Run `scripts/validate-structure.sh` — must score 8/8
- If not 8/8, identify what's still missing and fix it

### Step 1.5: Version Bump (updates only)
If this skill has been published before, bump the version before proceeding:

1. **Check current published version:**
```bash
clawhub inspect {slug}
```

2. **Bump version** in both `skill.yml` and `SKILL.md` frontmatter:
   - Patch (1.0.0 → 1.0.1): bug fixes, typos, minor doc updates
   - Minor (1.0.0 → 1.1.0): new features, new sections, structural changes
   - Major (1.0.0 → 2.0.0): breaking changes, full rewrites

3. **Update CHANGELOG.md** with new version entry describing what changed

4. **Verify `display_name` is set in `skill.yml`** — this is the human-readable title shown on ClawhHub.
   It must be set explicitly; never derive it from the slug or guess it.
   If missing, add it now:
   ```yaml
   display_name: "Human Readable Title"  # Required — used as ClawhHub listing title
   ```
   Rules:
   - Title case, plain English, no jargon
   - Describes what the skill does, not how it's implemented
   - Example: slug `autonomous-task-runner` → `display_name: "Autonomous Task Runner"`
   - Example: slug `skill-releaser` → `display_name: "Skill Releaser"`

Skip this step for first-time releases (but still verify `display_name` exists).

### Step 2: Readiness Check
Verify the skill directory is complete:
- `SKILL.md` exists with description and usage instructions
- `skill.yml` exists with name, description, triggers
- Structure score 8/8 (from Step 1)
- No obvious OPSEC violations (quick scan)

If any check fails, report what needs fixing. Do not proceed.

### Step 3: Create Private Staging Repo
```bash
# Check if repo already exists
gh repo view your-org/openclaw-skill-{name} 2>/dev/null

# If not, create it — CRITICAL: use the SANITIZED description, not the source skill.yml
# Run OPSEC scan on the description string BEFORE passing to gh repo create
gh repo create your-org/openclaw-skill-{name} --private --description "{sanitized description}"
```

**OPSEC on repo metadata:** The