skill-hub-gateway

# Skill Hub Gateway

Default API base URL: `https://gateway-api.binaryworks.app`

Chinese documentation: `SKILL.zh-CN.md`

## Version Check Protocol (Agent)

- Official latest version source: `GET /skills/manifest.json` -> `data.version`.
- Local current version source: this installed `SKILL.md` frontmatter `version`.
- Compare versions using semantic version order (`major.minor.patch`).
- Check timing: once at session start, then at most once every 24 hours within the same session.
- If version check fails (network/timeout/parse error), do not block runtime execution. Continue current workflow and retry at the next allowed check window.

## Agent Decision Flow

- If `latest_version > current_version`, read the matching section under `Release Notes` in this document to build `update_summary`.
- Agent should show the user:
  - `current_version`
  - `latest_version`
  - `update_summary`
- User decision options:
  - `Update now`
  - `Remind me later in this session`
- If user chooses `Remind me later in this session`, suppress repeated prompts for the same target version until a new session starts.

## First-Time Onboarding (install_code)

Scripts auto-complete onboarding by default:

1. `POST /agent/install-code/issue` with `{"channel":"local"}` or `{"channel":"clawhub"}`.
2. Read `data.install_code`.
3. `POST /agent/bootstrap` with `{"agent_uid":"<agent_uid>","install_code":"<install_code>"}`.
4. Read `data.api_key`, then call runtime APIs with `X-API-Key` or `Authorization: Bearer <api_key>`.

Manual override:

- You can still provide `api_key` explicitly.
- If `agent_uid` and `owner_uid_hint` are omitted, scripts derive stable local defaults from the current workspace path.

## Runtime Contract (V2)

- Execute: `POST /skill/execute`
- Poll: `GET /skill/runs/:run_id`
- Image-based capabilities use `image_url`. In end-user product flows, users should upload files/attachments directly and should not need to paste URLs manually.
- Terminal states: `succeeded` and `fail...