The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the OnlyHarness Registry listing page.
superskill.sh is the single human-facing product for finding and installing reviewed AI-agent capabilities. It preserves existing registrations and workspaces, exposes one universal install link for Codex and Claude Code, and keeps exact release, trust, revocation and consent gates explicit.
The old OnlyHarness UI and host are compatibility-only: human routes redirect to SuperSkill, while old API/MCP coordinates, npm/package names, database identifiers and immutable archive URLs remain available for installed clients and data continuity. Internal package names still use @harnesshub/*; the published compatibility CLI package remains onlyharness.
A native harness package is the strict, verified package format inside the broader OnlyHarness resource catalog:
harness.yaml manifest with runtime, tools, permissions, quality gates, and risk profile.Supabase auth is enabled for signup/login, stars, local remix drafts, thread posts, and authenticated publish.
New Resource Wizard) that imports markdown into a small unverified scaffold.harness_flex.exe), Wild West awards, Paint heat chart, and a paperclip mascot that opens the wizard.onlyharness with hh compatibility commands plus superskill install; HH_REGISTRY_URL targets another registry, default https://superskill.sh/api./llms.txt, /api/openapi.json, /server.json, and /mcp.gate_escrow rail; paid is set only after a matching escrow purchase captures against the delivered gate receipt.Open:
http://127.0.0.1:5177http://127.0.0.1:8787/healthzhttp://127.0.0.1:3000Payout reporting and ledger creation are manual-ops only. The script reads settled purchases plus payout_accounts, applies the current rates, and can create an idempotent draft payout ledger. It never calls a payout provider and never marks items paid.
Use SUPABASE_URL + SUPABASE_SERVICE_ROLE_KEY, or local JSON fixtures via --purchases and --payout-accounts. --record-ledger upserts payout_runs/payout_items through Supabase service role. Rows without creator_user_id are marked MISSING_CREATOR_ID; rows without payout account are blocked as MISSING_PAYOUT_ACCOUNT.
The npm package is published:
Resource catalog, immutable publish-resource, workspace approval/setup/gates, membership expiry, the manual/provider-agnostic workspace subscription lifecycle, universal install, and SuperSkill managed commands are available in published onlyharness@0.2.19; 0.2.18 is a known-bad one-link release because its published universal-skill digest is stale. Server catalog flows are also available through MCP/HTTP.
For local development, build the workspace bundle and run it directly:
SuperSkill is the task-first managed capability layer built on OnlyHarness. The checked-in catalog currently contains 12 exact immutable candidates and intentionally exposes zero approved showroom items until real Claude Code, Codex, and human review attestations exist.
GET /api/showroom/capabilities and GET /api/showroom/capabilities/{id}. These routes never recommend, download, or activate files.GET /api/showroom/selected exposes the current reviewed-intake candidates as selected_unreviewed cards. They can fill the Daylight catalog, but cannot be recommended or activated until exact-release approval evidence exists./api/recommendations, /api/capabilities/{id}, exact release/archive routes, hosted proof publish and managed lifecycle events use one confirmed Supabase user credential plus an active server-side superskill:managed grant. Headless clients inherit HH_TOKEN explicitly. HH_SUPERSKILL_TOKEN is legacy internal-alpha compatibility only and cannot produce public-GO evidence.onlyharness@0.2.19 is the current one-link release, published and verified through a clean npx install, and pinned to official npm integrity in plugins/superskill/runtime.json. It binds hosted skill detail, archive headers and archive bytes to one immutable version/digest/size/trust tuple. 0.2.14 and 0.2.18 are known-bad one-link releases; never substitute latest for the exact runtime pin.superskill.sh; legacy query or stored skin state cannot switch it.Plugin sources live under plugins/superskill with one byte-identical shared skill for Claude Code and Codex. A capability handoff uses one immutable https://superskill.sh/api/superskill/install/{id}/{version}/{sha256} URL; the pinned local installer selects exactly one unambiguous client, while routing and activation consent remain separate. Marketplace publication and clean new-session plugin proof remain separate rollout actions.
/llms.txt, /AGENTS.md, /api/openapi.json, MCP Registry metadata at /server.json, and OAuth protected-resource metadata at /.well-known/oauth-protected-resource. SuperSkill does not advertise a vanity authorization server: managed headless flows receive a confirmed account token manually through HH_TOKEN, and /.well-known/oauth-authorization-server intentionally returns 404 until one issuer owns a complete standards-valid flow.https://superskill.sh/mcp with the exact inventory search_harnesses, harness_detail, search_resources, resource_detail, resource_use_instructions, pull_instructions, pull_harness, search_docs, publish_markdown_to_harness, and publish_resource_package. Resource detail/use tools accept an optional exact version; explicit historical reads never drift to latest. Tool results use structuredContent; logical failures set isError: true with stable machine codes and sanitized details.unreviewed until separate review evidence exists. A static-v2 fail is rejected before any archive, catalog or event mutation with sanitized rule/file evidence; HTTP uses SECURITY_SCAN_FAILED, while MCP keeps its stable VALIDATION_FAILED envelope. Accepted pass/warn releases remain unreviewed, and static pass does not claim a known runtime risk tier.server.json is remote-only at canonical https://superskill.sh/mcp; com.onlyharness/registry remains the compatibility identifier. Publication still requires MCP Registry authorization/publication proof for superskill.sh, the exact published runtime pin, and a clean client proof; onlyharness.com is compatibility-only.hh setup @acme reads GET /api/orgs/{slug}/bundle; hh publish --org acme writes an org-private harness. Both use HH_ORG_TOKEN when ORGS_ENABLED=true. Org auth/bundles/audit read Supabase service-role tables first and keep HARNESS_ORGS_PATH/HARNESS_ORG_AUDIT_PATH as the local smoke fallback.GET /api/orgs/{slug}/workspace with the same org token and returns org-private cards, sanitized audit rows, and a permission/risk summary.POST /api/workspaces; the transaction also creates owner membership, the invite policy and the default approved collection. GET /api/workspaces/{slug}/workspace, GET/PUT /api/workspaces/{slug}/setup-bundle, GET /api/workspaces/{slug}/resources, GET /api/workspaces/{slug}/resources/{id}, GET /api/workspaces/{slug}/resources/{id}/archive, POST /api/workspaces/{slug}/imports/resource-package, POST /api/workspaces/{slug}/resources/approve, and /api/workspaces/{slug}/collections... are gated by WORKSPACES_ENABLED=true. API/web reads accept either an active, non-expired workspace member session or HH_WORKSPACE_TOKEN; CLI stays token-based for now, with HH_ORG_TOKEN as a migration fallback. hh workspace setup acme --target claude-code installs workspace-hosted packages and writes instructions for approved public resources without pretending those have workspace archives. GET/POST /api/workspaces/{slug}/members, POST /api/workspaces/{slug}/invites, POST /api/workspaces/{slug}/join, and DELETE /api/workspaces/{slug}/members/{userId} manage membership through member:write/invite:write; POST /members accepts optional expiresAt, and expired or removed members cannot use private install/archive paths. Raw invite codes are returned once, only hashed values are stored, and the web share URL keeps the raw code after # so it is not sent to the server before the explicit join. Workspace gates add GET/PUT /api/workspaces/{slug}/join-policies, POST /api/workspaces/{slug}/join-code, read-only POST /api/workspaces/{slug}/join-code/verify, and explicit POST /api/workspaces/{slug}/join-grants for Telegram/Discord/entitlement checks with gate:verify/gate:write scopes. Active paid_subscription join policies require WORKSPACE_SUBSCRIPTIONS_ENABLED=true; POST /subscriptions/checkout creates an incomplete receipt only, the signed POST /webhooks/workspace-subscriptions activates/renews/graces/cancels access idempotently, does not restore removed/suspended members, and POST /subscriptions/sweep expires ended access without charging money. Use hh resources approve onlyharness:harnesses/deep-market-researcher --workspace acme --collection approved to add a scanned public listing to a workspace collection as local curation, not OnlyHarness verification; not_scanned and failed resources are rejected for installable approval.hh sync <git-url-or-local-path> --org acme clones/scans markdown skills and runbooks, then imports them through the org publish endpoint. First version has no webhooks.hh publish <harness-dir> requires local .harnesshub/results.json; hh publish <git-url> --path <harness-dir> clones to a temp dir, runs local eval/gate there, then publishes only if the server rechecks schema, security and gate successfully.hh publish-resource <dir-or-git-url> --name <slug> --type <type> packages safe bounded text files from skills, plugins, workflows, MCP servers, command packs, scripts, docs or source bundles into OnlyHarness archive storage and lists the result in /api/resources. It is not a Verified harness badge.hh publish-resource <dir-or-git-url> --workspace acme --name <slug> --type <type> publishes the same full package into a private workspace catalog as @acme/name; it does not go through the markdown scaffold path and does not claim a Verified badge.HH_ORG_TOKEN=<org-token> hh pull @acme/private-harness.directories. They show open <url> in search results and GET /api/repos/directories/{name}/archive returns 409 DIRECTORY_LINK_ONLY instead of runnable files.POST /api/repos/{owner}/{repo}/remixes creates a free unverified local/{name} copy from archive files only and records the source -> fork edge. Paid, org/private, directory, link-only and unspecified-license sources fail closed; copied fallback recipes do not increment forks or store prompts/local paths./healthz only returns status, and maintainer review in detail is explicitly a local-demo preview until a real forge PR source is connected./api/resources is the primary mixed source-aware catalog for skills, plugins, workflows, MCP servers, configs, guides, runtimes, directories and native harness-format packages. /api/registry keeps the harness-plus-link-only-directory contract for existing agent clients.hh benchmark <suite.yaml> compares candidate and analog harnesses from local paths using declared eval case scores. Suites live in benchmarks/, smoke runs every YAML suite there, and this remains a runner/comparison layer, not an independent LLM quality measurement.hh suggest <task> --json searches, returns ranked candidates with trust fields, fetches detail for the selected harness, prints a full trust summary, and records a privacy-safe suggested event. Use --pick <rank> to inspect/apply another candidate. hh suggest <task> --apply --out <dir> installs the selected harness through the same archive path as hh pull, records accepted when --apply is chosen, and records applied only after files are written. Add --target cli|claude-code|codex|cursor to run the full adapter install path before applied.versions[]; hh pull owner/name --version <semver> and hh install owner/name --version <semver> request the same immutable /archive?version= path and keep .harnesshub/source.json pinned to the resolved version.hh eval and hh gate record privacy-safe eval/gate events for pulled harnesses when they pass; detail payloads expose verification.lastVerifiedAt from those events. Registry runs are counted only from passed gate events, never from hh run sample preview.hh gate --receipt writes a signed gate receipt with harness ref, version, resultsHash, verdict and timestamp. POST /api/receipts verifies the ed25519 signature only; it is side-effect-free and does not store prompts, local paths, payments or entitlements.pricing.model: gate_escrow checkout/webhook creates reserved plus an expiring escrow_reserved archive entitlement. POST /api/billing/escrow/receipt captures on a valid passing receipt or refunds on a valid failing receipt; POST /api/billing/escrow/timeout refunds after the 72h window./api/bounties* supports create, claim, deliver and accept; accept verifies the delivered receipt, escrow target, amount and currency, blocks escrow reuse, and writes paid only after capture.hh run executes locally as sample preview only, and HTTP/MCP surfaces deliver harness files rather than running author code server-side. pricing.model=per_call returns 409 HOSTED_EXECUTION_NOT_AVAILABLE until a runner/partner path is shipped and smoked.PAYMENTS_ENABLED=true, X402_ENABLED=true, and X402_PAY_TO is set, the archive response also includes an x402 v2 PAYMENT-REQUIRED header. Successful hh install --pay or hh pull --pay archive delivery requires X402_FACILITATOR_URL to verify/settle and then grants a wallet entitlement./checkout: without provider_ref the web UI asks the buyer to log on and create a manual checkout session; with provider_ref it shows a pending manual handoff. Neither state grants access client-side.PAYMENT_PROVIDER unset or manual). Any other provider value fails closed before creating a purchase; x402 remains a separate archive-payment rail.GET /api/billing/receipt?provider_ref=<ref> returns the authenticated user's pending/paid purchase status and entitlement flag, but never settles providers or grants access.GET /api/entitlements/check?subject=user:<id>&harness=owner/name with an org token that has entitlements:read; this returns a decision only, never archive files.POST /api/community/invite-code after entitlement, then the Telegram/Discord bot calls POST /api/community/verify-code with a scoped org token before granting access. COMMUNITY_INVITE_SECRET must be configured on the API.installConfirms; only authenticated kind=install&client=claude-code events count toward the works in Claude Code: N confirms badge.claude plugin marketplace add elvismusli/onlyharness then claude plugin install superskill@superskill. The one-link installer is the primary path.codex mcp add superskill --url https://superskill.sh/mcp --bearer-token-env-var HH_TOKEN.npm run check:mcp-registry && npm run check:plugin; when Claude CLI is installed, also run claude plugin validate . && claude plugin validate plugins/onlyharness.Create local env from the examples:
The current VPS uses a shared system Caddy on ports 80/443. OnlyHarness runs behind it on 127.0.0.1:8097.
scripts/deploy-production.sh runs public smoke by default after containers reload: /api/healthz, /server.json, /.well-known/oauth-protected-resource, the intentional 404 at /.well-known/oauth-authorization-server, /checkout, and /mcp. Override PUBLIC_BASE_URL for a non-default hostname or set RUN_DEPLOY_SMOKE=0 only for a deliberately partial deploy.
For authenticated production smoke without creating throwaway users, set the compatibility QA credentials in the ignored production env and run scripts/smoke-production-auth.ts against https://superskill.sh/api.
Deployment artifacts:
infra/production-compose.ymlinfra/production-system-caddy.override.ymlinfra/Caddyfile.local-smokescripts/deploy-production.shscripts/smoke-production-compose.shscripts/smoke-production-auth.tsProduction smoke:
Current verification gates:
The production auth smoke creates a QA Supabase user and verifies that email confirmation blocks immediate sign-in. To test authenticated publish with a pre-confirmed token, pass HH_TOKEN to the CLI publish flow or run the API publish smoke against a confirmed session.
.env.local, app env, and infra/production.env files are gitignored.HARNESS_WEBHOOK_TOKEN when configured.ORGS_ENABLED; org tokens are stored as sha256: hashes in Supabase or the local fallback store, and audit logs must not contain raw tokens.