Skill release plus

skill-release-plus

Version: 1.0.3
Author: Evan Song <github.com/Songhonglei> Repo: https://github.com/Songhonglei/build-better-skills/tree/main/skills/skill-release-plus License: MIT (this repo) — clawhub mirror auto-uses MIT-0 (platform-enforced)
Part of: build-better-skills suite — see Stages for the lifecycle map.

Sign → Pack → Publish to multiple skill hubs in one command. Supports clawhub.com, skillhub.cn (Tencent Cloud), GitHub Releases, and any custom hub via a user-hook script.

---

Quick start

# Default: publish to clawhub only
python3 scripts/release.py --slug my-skill -m "first release" --version 1.0.0

# Publish to all three real hubs at once
python3 scripts/release.py --slug my-skill -m "ship it" --version 1.0.0 --target all

# Custom hub via user hook
python3 scripts/release.py --slug my-skill -m "v1" --version 1.0.0 \
    --target user-hook:/path/to/my-publish.sh

# Check token readiness before publishing
python3 scripts/release.py --check --target all

# Dry-run (sign + pack, skip publish)
python3 scripts/release.py --slug my-skill -m "test" --version 1.0.0 --dry-run

# Inspect current exclude rules
python3 scripts/release.py --show-exclude

---

Supported targets

Target	Status	Auth	Notes
clawhub	✅	SRP_CLAWHUB_TOKEN (env) or clawhub login	Wraps the clawhub CLI
skillhub-cn	✅	SRP_SKILLHUB_CN_TOKEN (env)	Tencent Cloud — POST /api/v1/community/skills/publish (multipart). Rate-limit 3 publish/min/token. Auto-retries on 429.
github-release	✅	SRP_GITHUB_TOKEN (env)	Pure git + GitHub REST API (no gh CLI required). Supports owner/repo[/subdir] for monorepo layouts.
user-hook:<path>	✅	Hook-defined	Your script receives metadata via env vars + JSON stdin, returns {"ok": true, "url": "..."} on stdout

Not supported: cn.clawhub-mirror.com (ByteDance Volcano) is a read-only public mirror of clawhub.com — publishing to clawhub automatically syncs there. There is no separate publish endpoint.

---

Installation

# Install Python 3.8+ (standard library only, no pip install needed)
git clone https://github.com/Songhonglei/build-better-skills.git
cd build-better-skills/skills/skill-release-plus

# Or install via clawhub:
clawhub install skill-release-plus

Dependencies:

• Python 3.8+ (standard library only — urllib, subprocess, tarfile, json, argparse, dataclasses, pathlib)
• git 2.x (for github-release target only)
• clawhub CLI (for clawhub target only — auto-detected from $PATH)
• skill-sign (optional — for content signing; skipped if not installed)
• PyYAML (optional — improves SKILL.md frontmatter parsing for edge cases; stdlib fallback handles description: "..." single-line and description: > folded scalar without it)

---

Configuration

Resolution priority (highest → lowest):

1. CLI args (--slug, --target, --version, etc.)
2. Process env vars (SRP_* private namespace)
3. Project-local ./.env
4. Global ~/.config/skill-release-plus/.env
5. Missing required key → onboarding prompt (interactive)

Environment variables (all SRP_* prefixed)

Variable	Required for	Description
SRP_CLAWHUB_TOKEN	clawhub target	clawhub API token (or run clawhub login)
SRP_SKILLHUB_CN_TOKEN	skillhub-cn target	Tencent skillhub.cn personal token (starts with skh_)
SRP_GITHUB_TOKEN	github-release target	GitHub PAT with repo scope
SRP_GITHUB_OWNER	github-release (optional)	Default repo owner (defaults to authenticated user)
SRP_GITHUB_REPO	github-release (optional)	Default repo name (defaults to slug)
SRP_GITHUB_BRANCH	github-release (optional)	Default branch (default: main)
SRP_GITHUB_BASIC_AUTH_HEADER	github-release (optional)	If true, use HTTP Basic Auth header instead of URL-embedded token
SRP_DEFAULT_TARGETS	optional	Comma-separated default target list (default: clawhub)
SRP_OUTPUT_DIR	optional	Package output directory (default: <cwd>/output/skill-release)
SRP_SIGN_OPTIONAL	optional	If true, skip signing when skill-sign not installed (default: true)
SRP_SIGN_SCRIPT	optional	Explicit path to sign.py (overrides auto-detection of skill-sign)

---

Architecture

release.py (dispatcher, 352 LOC)
  ├─ _lib_config.py         (4-layer config + parse_targets, 289 LOC)
  ├─ _lib_package.py        (sign / pack / exclude rules / multipart, 305 LOC)
  ├─ _lib_adapters_base.py  (BaseAdapter ABC, 98 LOC)
  └─ _adapter_*.py:
       ├─ clawhub          (CLI wrap, 185 LOC)
       ├─ github-release   (git + GitHub REST API, 392 LOC)
       ├─ skillhub-cn     (Tencent Cloud HTTP/multipart, 308 LOC)
       └─ user-hook       (subprocess + JSON envelope, 140 LOC)

Design principles:

• Single source of truth: One config/exclude.json, one signing pass, one tar.gz, fan out to N targets
• Adapter independence: Each adapter is a separate Python module subclassing BaseAdapter; no cross-adapter coupling
• Fail-open by default: One target failing does not block others (dispatcher reports per-target status)
• Protocol-agnostic base: BaseAdapter doesn't assume HTTP / multipart / git — adapters own their protocol

---

Writing a custom adapter (user-hook)

Create an executable script:

#!/bin/bash
# my-publisher.sh
set -e

# Hook receives:
#   $SRP_HOOK_SLUG, $SRP_HOOK_VERSION, $SRP_HOOK_CHANGELOG,
#   $SRP_HOOK_TAR_PATH, $SRP_HOOK_SKILL_DIR, $SRP_HOOK_DISPLAY_NAME

curl -sf -F "package=@$SRP_HOOK_TAR_PATH" \
     -F "version=$SRP_HOOK_VERSION" \
     "https://my-private-hub.example.com/publish"

# Print JSON envelope on stdout for the dispatcher to parse
echo '{"ok": true, "url": "https://my-private-hub.example.com/skills/'"$SRP_HOOK_SLUG"'"}'

Then invoke:

chmod +x my-publisher.sh
python3 scripts/release.py --slug my-skill -m "v1" --version 1.0.0 \
    --target user-hook:./my-publisher.sh

---

Exclude rules

Default config/exclude.json strips:

• VCS: .git, .svn, .hg
• IDE: .idea, .vscode, .DS_Store, Thumbs.db
• Build artifacts: __pycache__, *.pyc, node_modules, dist, build
• Secrets: .env, .secrets, *.pem, *.key, .token
• Test/dev: tests/__pycache__, .pytest_cache, .tox
• See full list: python3 scripts/release.py --show-exclude

---

Command reference

usage: release.py [-h] [--slug SLUG] [--changelog CHANGELOG]
                  [--version VERSION] [--display-name DISPLAY_NAME]
                  [--skill-dir SKILL_DIR] [--target TARGET] [--dry-run]
                  [--show-exclude] [--check]

options:
  -h, --help            show this help message and exit
  --slug SLUG           skill slug (lowercase, digits, hyphens)
  --changelog, -m       release changelog
  --version VERSION     explicit version (semver); default: auto-bump patch
  --display-name        human-readable display name (default: slug)
  --skill-dir SKILL_DIR  path to skill source directory (default: ./<slug>)
  --target TARGET       comma-separated targets, or "all". Default: clawhub.
                        Special: user-hook:<path> for custom hooks.
  --dry-run             sign + pack but skip publish
  --show-exclude        print current exclude rules and exit
  --check               check token readiness for selected targets

Exit codes:

• 0 — all targets succeeded
• 1 — at least one target failed (others may have succeeded)
• 2 — invalid arguments or config error

---

Triggers

This skill should be used when the user says:

• "publish skill X to clawhub / skillhub.cn / GitHub"
• "ship my skill to multiple hubs"
• "release X.Y.Z of my skill"
• "发布 skill 到 clawhub"
• "把 skill 推到 skillhub.cn"
• "skill 同时发到三个 hub"
• "用 user-hook 发到我自己的 hub"

---

Limitations

• skillhub-cn rate limit: 3 publish/minute/token. Dispatcher waits and retries on 429.
• github-release requires explicit --version: No auto-tag-bump (would require parsing existing tags reliably across owner/repo combos).
• skillhub-cn requires description in SKILL.md frontmatter (≤1024 bytes). YAML folded (>) scalar is supported.
• No rollback: If 2/3 targets succeed and 1 fails, you must manually clean up the 2 successes or accept partial state.

---

License

MIT (this repo). See LICENSE.

Note: when this skill is published to clawhub.com, the platform enforces MIT-0 license metadata on hub mirror — original repo MIT license is unchanged.