skill-release-plus

# skill-release-plus **Version**: 1.0.3 **Author**: Evan Song <[github.com/Songhonglei](https://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`](https://github.com/Songhonglei/build-better-skills) suite — see [Stages](https://github.com/Songhonglei/build-better-skills#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 ```bash # 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](https://www.npmjs.com/package/clawhub) | | `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 ```bash # 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: ```bash #!/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: ```bash 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.