Publish to SkillHub

Publish a WorkBuddy skill to SkillHub using the official CLI. The workflow
is identical on macOS / Linux / WSL; on Windows Git Bash the official install.sh breaks, so a
Python-CLI workaround is provided.

When to use

Activate this skill when the user asks to publish / upload / push a skill to SkillHub, or supplies a
skh_... API token with an "autopush" intent. Do NOT auto-publish if the user has not provided a
token or clearly authorized a public release.

Prerequisites the agent CANNOT perform (ask the user)

These require the user's phone number, browser login, and a public account — never do them on the
user's behalf:

1. Register at https://skillhub.cn (phone + SMS code).
2. Real-name verification (face check) in 个人中心.
3. Create an API Token at 个人中心 → API keys (直链 /dashboard/keys). Copy the skh_... value —
   it is shown only once.

The user must paste that token into the conversation (or into scripts/publish_windows.py /
publish-skillhub.sh). Treat it as a secret: never write it to a file, memory, or the final report.

Step 1 — Verify the target skill's frontmatter

Read the target skill's SKILL.md. It MUST contain this YAML frontmatter (SkillHub fields, kept
alongside the WorkBuddy name / description / agent_created fields):

slug: your-unique-slug        # kebab-case, globally unique on SkillHub
displayName: Your Skill Name  # human-readable display name
version: 1.0.0                # semver
summary: Short overview       # one-line summary
license: MIT                  # SPDX license id

The CLI strictly validates only slug (kebab-case), version (semver), and displayName.
summary and license are recommended for the listing page. If slug collides (HTTP 409), rename
it to something globally unique — prefix with the user's handle, e.g. alice-product-dynamics.
See references/cli-reference.md for the full schema and error-code table.

Step 2 — Install the SkillHub CLI

macOS / Linux / WSL

curl -fsSL https://skillhub.cn/install/install.sh | bash -s -- --cli-only
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc
skillhub --version

Windows (Git Bash) — official script FAILS here

install.sh builds a temp dir whose path gets a C: prefix mixed in, so the inner tar/curl
cannot resolve it and the install aborts. Do not fight the script. Use the Python CLI instead:

1. The install kit is a tarball on Tencent COS. Download and extract it manually:
   bash curl -fsSL --max-time 60 \ https://skillhub-1388575217.cos.ap-guangzhou.myqcloud.com/install/latest.tar.gz \ -o skillhub_kit.tar.gz rm -rf skillhub_kit && mkdir skillhub_kit tar -xzf skillhub_kit.tar.gz -C skillhub_kit
2. The kit contains a pure-Python CLI: skillhub_kit/cli/skills_store_cli.py (standard library
   only — no pip install needed). Run it directly with any Python 3:
   bash python skillhub_kit/cli/skills_store_cli.py --help
   Prefer a managed Python (e.g. C:/Users/Administrator/.workbuddy/binaries/python/versions/3.13.12/python.exe)
   so the agent's environment stays isolated.

Or, to automate the download + extract + publish in one shot, run the bundled helper
scripts/publish_windows.py (works on any OS, but designed for the Windows path):

python scripts/publish_windows.py <skill_dir> \
  --token "skh_xxx" --changelog "首次发布"
# add --dry-run for the precheck; --kit-dest to reuse an already-extracted kit

Step 3 — Dry-run precheck

Always precheck before a real publish. It validates format only and never uploads:

# macOS / Linux / WSL
skillhub publish <skill_dir> --dry-run

# Windows (Python CLI)
python skillhub_kit/cli/skills_store_cli.py publish <skill_dir> --dry-run --token "skh_xxx"

Expect: ✓ Dry-run passed: <slug>@<version>. Fix any Error: SKILL.md missing ... by returning to
Step 1.

Step 4 — Publish

# macOS / Linux / WSL
skillhub publish <skill_dir> --changelog "首次发布"

# Windows (Python CLI) — explicit host + token
python skillhub_kit/cli/skills_store_cli.py publish <skill_dir> \
  --host "https://api.skillhub.cn" --token "skh_xxx" --changelog "首次发布"

On success: ✓ Published: skillId=xxxxx status=pending_review. The skill enters review; it becomes
visible once approved (check 个人中心 → 我的 Skill). Note: the CLI may print status=None even on
success — a non-zero exit code or a missing skillId is the real failure signal.

Step 5 — Update an existing skill

Keep slug unchanged, bump version (e.g. 1.0.1), optionally update displayName / summary,
then re-run Step 3 + Step 4 with a new --changelog describing the change.

Error handling

Network note (sandboxed agents)

In a sandboxed environment the outbound network to skillhub.cn / the COS host may be blocked. If
curl returns an empty file or connection error, request network access (e.g. run the Bash tool with
sandbox disabled) before retrying the download and publish commands.