Skill Hub Gateway

---
name: skill-hub-gateway
description: "Unified gateway skill for async execute/poll, portal user closure, and telemetry feedback workflows."
---

# Skill Hub Gateway

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

Default site base URL (for upload route): `https://gateway.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.

## Legacy Runtime Contract (Compatibility)

- Execute: `POST /skill/execute`
- Poll: `GET /skill/runs/:run_id`

## Portal Actions (User Closure)

Action catalog (single default path per action):

- `portal.me` -> `GET /user/me`
- `portal.balance` -> `GET /user/points/balance`
- `portal.ledger.query` -> `GET /user/points/ledger`
- `portal.usage.query` -> `GET /user/usage`
- `portal.skill.execute` -> `POST /user/skills/execute`
- `portal.skill.poll` -> `GET /user/skills/runs/:runId`
- `portal.skill.presentation` -> `GET /user/skills/runs/:runId/presentation`
- `portal.voucher.redeem` -> `POST /user/vouchers/redeem` (write)
- `portal.recharge.create` -> `POST /user/recharge/orders` (write)
- `portal.recharge.get` -> `GET /user/recharge/orders/:orderId`

Write safety gate:

- `portal.voucher.redeem` and `portal.recharge.create` require `payload.confirm === true`.
- If `confirm` is missing or not `true`, action runner rejects the call locally and does not send write traffic.

## Payload Contract

Default payload conventions:

- `payload.input` is the primary input object for `portal.skill.execute`.
- `payload.request_id` is optional and passed through as-is.
- Query actions use `payload` fields directly as query params (`date_from`, `date_to`, `service_id`, `channel`).

Media normalization conventions:

- Prefer explicit URL fields already present in input: `image_url`, `audio_url`, `file_url`.
- If `attachment.url` exists, map it to the capability target URL field.
- If `file_path` exists, auto-upload through `{site_base}/api/blob/upload`, with fallback to `{site_base}/api/blob/upload-file` when `@vercel/blob/client` is unavailable, then backfill URL into input before execution.
- For agent runtimes that do not include `@vercel/blob/client`, you can also pre-upload media via your backend (for example Vercel Blob) and pass `attachment.url` or explicit URL fields.
- `site_base_url` is a guarded field: runtime only accepts the trusted configured site base URL (default `https://gateway.binaryworks.app` or env `SKILL_SITE_BASE_URL`).
- Users should not need to manually paste media URLs in normal product flows.

Presentation files:

- `portal.skill.presentation` accepts optional `include_files=true` to return `visual.files.assets` with rendered file URLs.
- `portal-action.mjs` defaults `include_files=true` for `portal.skill.presentation` unless explicitly disabled.
- Image runs return `overlay` (boxed image), plus `mask` / `cutout` assets when available.
- Audio runs normalize data URLs to `output.media_files.assets` with uploaded file URLs when blob storage is configured.

## Runtime Auth Bridge

User-scoped actions use a fixed auth bridge:

1. Resolve runtime API key context (`api_key`, `agent_uid`, `owner_uid_hint`, `base_url`).
2. `GET /agent/me` with `X-API-Key` + `x-agent-uid` to resolve `user_id`.
3. `POST /user/api-key-login` with `user_id + api_key` to obtain `userToken`.
4. Execute Portal Action with `Authorization: Bearer <userToken>`.

## Insufficient Points Recovery

For `POINTS_INSUFFICIENT` responses:

- Keep `error.code` and `error.message` unchanged.
- Preserve and surface `error.details.recharge_url` when available.
- Diagnostic logs should recommend `portal.recharge.create` or direct open of `recharge_url`.

## Bundled Files

- `scripts/execute.mjs` (CLI args: `[api_key] [capability] [input_payload] [base_url] [agent_uid] [owner_uid_hint]`)
- `scripts/poll.mjs` (CLI args: `[api_key] <run_id> [base_url] [agent_uid] [owner_uid_hint]`)
- `scripts/feedback.mjs` (CLI args: `[api_key] [payload_json] [base_url] [agent_uid] [owner_uid_hint]`)
- `scripts/telemetry.mjs` (shared best-effort telemetry helper)
- `scripts/runtime-auth.mjs` (shared auto-bootstrap helper)
- `scripts/portal-auth.mjs` (api-key -> user session bridge)
- `scripts/portal-action.mjs` (CLI args: `[api_key] <action> <payload_json> [base_url] [agent_uid] [owner_uid_hint]`)
- `scripts/attachment-normalize.mjs` (attachment URL/path normalization + upload)
- `references/capabilities.json`
- `references/openapi.json`
- `SKILL.zh-CN.md`

## Telemetry and Feedback

- Bundled scripts now support best-effort telemetry emit for auth/execute/poll/feedback flows.
- Telemetry is non-blocking and does not change runtime exit semantics if telemetry delivery fails.
- Optional environment variables:
  - `SKILL_TELEMETRY_ENABLED` (`true` by default)
  - `SKILL_TELEMETRY_BASE_URL` (defaults to runtime `base_url`)
  - `SKILL_TELEMETRY_TIMEOUT_MS` (`2000` by default)
- Feedback script posts to `POST /feedback/submit` with runtime auth (`X-API-Key`) and attaches `agent_uid` + `owner_uid_hint` in metadata.

## Capability IDs

- `human_detect`
- `image_tagging`
- `tts_report`
- `embeddings`
- `reranker`
- `asr`
- `tts_low_cost`
- `markdown_convert`
- `face-detect`
- `person-detect`
- `hand-detect`
- `body-keypoints-2d`
- `body-contour-63pt`
- `face-keypoints-106pt`
- `head-pose`
- `face-feature-classification`
- `face-action-classification`
- `face-image-quality`
- `face-emotion-recognition`
- `face-physical-attributes`
- `face-social-attributes`
- `political-figure-recognition`
- `designated-person-recognition`
- `exhibit-image-recognition`
- `person-instance-segmentation`
- `person-semantic-segmentation`
- `concert-cutout`
- `full-body-matting`
- `head-matting`
- `product-cutout`
## Release Notes

When publishing a new version, add a new section here. Agent update summaries must be generated from this block.

### 2.4.2 (2026-03-12)

**What's New**

- Added `/api/blob/upload-file` direct-upload fallback for `file_path` flows when `@vercel/blob/client` is unavailable.
- Added `portal.skill.presentation` file rendering (`visual.files.assets`) for overlay/mask/cutout URLs.
- Added audio output normalization to return `output.media_files.assets` with uploaded file URLs when blob storage is configured.

**Breaking/Behavior Changes**

- None.

**Migration Notes**

- For agent runtimes without `@vercel/blob/client`, send `file_path` as before; the runtime now falls back to direct upload.
- To receive rendered files, call `portal.skill.presentation` with `include_files=true` or rely on the portal default.

### 2.4.1 (2026-03-12)

**What's New**

- Added server-side `portal.skill.execute` input normalization for `attachment.url` (both `input.attachment.url` and top-level `attachment.url`).
- Added explicit media URL precedence guard (`image_url`/`audio_url`/`file_url` take priority over `attachment.url` when both are present).
- Added end-to-end tests for upload-first execution payload compatibility and precedence behavior.
- Clarified fallback guidance for runtimes missing `@vercel/blob/client` to use backend pre-upload URLs.

**Breaking/Behavior Changes**

- None.

**Migration Notes**

- Existing `portal-action.mjs` workflows remain compatible.
- For local file workflows in constrained agent runtimes, prefer backend pre-upload then pass `attachment.url` or explicit media URL.

### 2.4.0 (2026-03-12)

**What's New**

- Added Portal Actions contract for single-skill user closure flows (`portal.me`, balance/ledger/usage, execute/poll/presentation, voucher and recharge actions).
- Added local double-confirm write gate: `portal.voucher.redeem` and `portal.recharge.create` require `confirm=true`.
- Added runtime auth bridge script (`portal-auth.mjs`) for `api_key -> user session`.
- Added action runner (`portal-action.mjs`) and attachment normalization script (`attachment-normalize.mjs`) with `attachment.url` and `file_path` support.
- Standardized insufficient-points diagnostics to preserve `recharge_url` in passthrough envelopes.

**Breaking/Behavior Changes**

- Write actions now fail fast locally when `confirm=true` is absent.

**Migration Notes**

- Existing `execute.mjs` and `poll.mjs` workflows remain available.
- Portal users should call `portal-action.mjs` for user closure actions.

### 2.3.4 (2026-03-11)

**What's New**

- Added best-effort telemetry emit in runtime scripts for auth/execute/poll flows.
- Added `scripts/feedback.mjs` to submit structured feedback via runtime auth (`X-API-Key`).
- Added shared telemetry helper with optional env controls (`SKILL_TELEMETRY_*`).

**Breaking/Behavior Changes**

- None.

**Migration Notes**

- Existing execute/poll calls remain unchanged.
- If you run scripts in constrained environments, allow optional telemetry calls to `/agent/telemetry/ingest` and `/telemetry/ingest`.

### 2.3.3 (2026-03-11)

**What's New**

- Standardized user-facing guidance around upload-based flows: do not expose manual URL/JSON fields for media/document inputs.
- Updated capability reference examples and wording to match upload-first product UX.
- Renamed CLI argument label from `input_json` to `input_payload` for consistency with structured payload semantics.

**Breaking/Behavior Changes**

- None.

**Migration Notes**

- Existing runtime API calls remain unchanged.
- If your integration shows custom input forms, prefer file/attachment inputs instead of manual URL/JSON text fields.