Operating reference

Docs for the full SkillHub marketplace, not just a manifest format.

Use this page as the product-grade reference for SkillHub's registry, marketplace, runtime gateway, review governance, ledger, payout, notification, and admin operations.

Browse marketplace Publish a skill Open admin readiness

Three P0 journeys that define the product

The P0 product is judged by whether these paths connect. A listing must become project state, review state, runtime state, ledger state, notification state, and operator state.

Developer / Agent Builder

Discover, install, and test

01Search/filter

02Inspect trust

03Install to project

04Run test

05Monitor updates

Listing -> project install -> governed runtime test -> logs and cost follow-up

Start in marketplace

Publisher / Skill Author

Upload, submit, monetize, and improve

01Paste manifest

02Save draft

03Submit version

04Repair checks

05Monetize and improve

Draft -> exact version review -> checks -> pricing blockers -> feedback and payout readiness

Start publishing

Reviewer / Finance / Super Admin

Review, govern, and launch

01Prioritize reviews

02Govern risk

03Process money

04Deliver notifications

05Audit launch

Review queue -> trust action -> incident -> finance/payout -> launch readiness and audit

Open operations

Reference domains

Each domain exists because it creates a reason for users to return after the first visit: safer runtime use for developers, review and revenue loops for publishers, and governable operations for admins.

Registry and marketplace

SkillHub packages are versioned contracts. Public discovery should prefer approved versions and never silently replace installed behavior.

draft -> submitted -> in_review -> verified/rejected
Immutable verified and installed versions
Similar and replacement skill paths

Runtime gateway

Runtime calls go through the same governance path whether an agent uses REST, MCP, SDK, or the console test runner.

Project API key
Install and policy check
Budget, rate limit, subscription, log, and metering

Review and trust

Publishers need precise repair loops, not vague rejection notes. Automated checks must carry blocker, field, category, and next action.

Manifest/runtime/example/security checks
Three-business-day review SLA
Reviewer notes and audit trail

Ledger and payouts

Usage does not pay publishers directly. Billable usage and subscription periods first create immutable commercial records.

Transactions -> splits -> balances
Refunds and disputes create adjustments
Payout review reserves eligible balances

Notifications and webhooks

In-app notifications, email rows, and webhook outbox rows are separate so user preferences do not suppress organization webhook delivery.

Template-rendered delivery
Retry and provider metadata
Signed webhook fan-out

Admin operations

Admin operators need secret-safe readiness, identity, review, risk, finance, payout, delivery, webhook, and audit surfaces from one console.

Launch credibility thresholds
Migration and schema visibility
Reason-required privileged decisions

Required before review

Manifest quality bar

Identityname, displayName, version, category, tags, changelog, support path

Runtimehttp, mcp, or restricted local execution with entrypoint and transport posture

SchemasinputSchema, outputSchema, examples, required fields, and typed result shape

Permissionsnetwork, browser, filesystem, secrets, sensitive data, destructive or payment workflows

Commercialpricing model, paid blockers, publisher profile, terms acceptance, payout readiness

Trustreview status, automated checks, incidents, feedback, deprecation, replacement guidance

skillhub.jsonschema v0.1

{
  "schemaVersion": "0.1",
  "name": "support-triage",
  "displayName": "Support Triage",
  "version": "0.1.0",
  "runtime": {
    "type": "http",
    "entrypoint": "https://api.example.com/skill"
  },
  "permissions": {
    "network": false,
    "browser": false,
    "filesystem": "none",
    "secrets": []
  },
  "inputSchema": { "type": "object" },
  "outputSchema": { "type": "object" }
}

Runtime governance path

MCP tools/call and REST runtime invocation must reuse the same governance path. Console tests are useful because they prove this path before agents run autonomously.

01Authenticate project key

02Resolve installed skill and pinned version

03Check policy, approval, budget, rate limit, and subscription

04Invoke runtime and record invocation

05Post usage or subscription ledger state when billable

runtime.shgoverned invoke

curl -X POST "$SKILLHUB_API_URL/v1/runtime/invoke" \
  -H "Authorization: Bearer $SKILLHUB_PROJECT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "skillSlug": "support-triage",
    "input": { "ticket": "Customer cannot connect OAuth" }
  }'

API

API map for the operating platform

These groups are the public and console API surfaces that make the marketplace operational. Final payment capture stays deferred, while P0 payouts use manual PayPal/Alipay transfer records on top of the modeled state machines.

Marketplace

Public discovery, skill detail, publisher trust, and marketplace recommendation inputs.

GET /v1/skills/searchGET /v1/skills/:slugGET /v1/publishersGET /v1/publishers/:slug

Publisher

Organization-scoped publishing, version creation, exact-version submission, and pricing readiness.

POST /v1/skillsPOST /v1/publisher/skills/:slug/versionsPOST /v1/publisher/skills/:slug/versions/:version/submitPOST /v1/prices

Developer

Project install state, saved skills, policy approval, keys, runtime tests, invoices, and updates.

GET /v1/developer/projectsPOST /v1/projects/:projectId/installed-skillsPOST /v1/projects/:projectId/api-keysPOST /v1/projects/:projectId/runtime-test

Admin

Review, trust, incidents, launch readiness, finance, payouts, notifications, webhook outbox, and audit.

GET /v1/admin/reviewsGET /v1/admin/launch-readinessGET /v1/admin/payoutsGET /v1/admin/audit-logs

Shared state language

These names must stay consistent across marketplace cards, skill detail, publish preflight, project policy, publisher workspace, admin review, finance, and launch readiness.

Skill lifecycle

Publishing and review state for a skill version.

draftsubmittedin_reviewverifiedrejecteddeprecatedsuspended

Runtime checks

Automated evidence state for review and repair loops.

queuedrunningpassedwarningfailed

Balances and payouts

Commercial readiness and money movement state.

pendingavailablelockedpaidfailedblockedreversed

Delivery

Notification and webhook delivery state before provider integrations are final.

queuedpendingprocessingsentskippedfailedretry_ready

Launch and operator guardrails

Payment capture, provider-specific payout automation, tax/KYC automation, final legal terms, and final email provider operations are intentionally last integrations. P0 publisher payouts use manual PayPal/Alipay transfer records.

Operating terms Agent integration

Run launch readiness before customer demos and public launch.

Keep production demo fallback disabled unless a controlled demo explicitly enables it.

Use email-code access first; Google and GitHub become live only after OAuth credentials and callback URLs are configured.

Resolve active notification-template, migration, runtime-key-salt, commission, and payout-state blockers before paid launch.

Never expose OAuth secrets, email provider keys, service tokens, API salts, webhook secrets, verification codes, user tokens, or passwords.