Skill Hub Gateway

Default API base URL: INLINECODE0

Default site base URL (for upload route): INLINECODE1

Chinese documentation: INLINECODE2

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:

• - User decision options:

• - 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. 1. POST /agent/install-code/issue with {"channel":"local"} or {"channel":"clawhub"}.
2. Read data.install_code.
3. INLINECODE21 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: INLINECODE29
• Poll: INLINECODE30

Portal Actions (User Closure)

Action catalog (single default path per action):

• - portal.me -> INLINECODE32
• INLINECODE33 -> INLINECODE34
• INLINECODE35 -> INLINECODE36
• INLINECODE37 -> INLINECODE38
• INLINECODE39 -> INLINECODE40
• INLINECODE41 -> INLINECODE42
• INLINECODE43 -> INLINECODE44
• INLINECODE45 -> POST /user/vouchers/redeem (write)
• INLINECODE47 -> POST /user/recharge/orders (write)
• INLINECODE49 -> INLINECODE50

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.
• INLINECODE58 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.
• INLINECODE74 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.
• INLINECODE80 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. 1. Resolve runtime API key context (api_key, agent_uid, owner_uid_hint, base_url).
2. INLINECODE91 with X-API-Key + x-agent-uid to resolve user_id.
3. INLINECODE95 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])
• INLINECODE107 (CLI args: [api_key] <run_id> [base_url] [agent_uid] [owner_uid_hint])
• INLINECODE109 (CLI args: [api_key] [payload_json] [base_url] [agent_uid] [owner_uid_hint])
• INLINECODE111 (shared best-effort telemetry helper)
• INLINECODE112 (shared auto-bootstrap helper)
• INLINECODE113 (api-key -> user session bridge)
• INLINECODE114 (CLI args: [api_key] <action> <payload_json> [base_url] [agent_uid] [owner_uid_hint])
• INLINECODE116 (attachment URL/path normalization + upload)
• INLINECODE117
• INLINECODE118
• INLINECODE119

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:

• - Feedback script posts to POST /feedback/submit with runtime auth (X-API-Key) and attaches agent_uid + owner_uid_hint in metadata.

Capability IDs

• - INLINECODE130
• INLINECODE131
• INLINECODE132
• INLINECODE133
• INLINECODE134
• INLINECODE135
• INLINECODE136
• INLINECODE137
• INLINECODE138
• INLINECODE139
• INLINECODE140
• INLINECODE141
• INLINECODE142
• INLINECODE143
• INLINECODE144
• INLINECODE145
• INLINECODE146
• INLINECODE147
• INLINECODE148
• INLINECODE149
• INLINECODE150
• INLINECODE151
• INLINECODE152
• INLINECODE153
• INLINECODE154
• INLINECODE155
• INLINECODE156
• INLINECODE157
• INLINECODE158
• INLINECODE159

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.