Host a skill market
Skill market on the Skills page calls https://api.skillhub.cn unless you replace it. When that host cannot reach the public internet, serve the three read APIs below on your own network. You do not need to run all of SkillHub.
Plugin and expert catalogs are a different service. See Plugin and expert market. Import from skill market on the skill-package page reads skillsets from SKILLSET_ORIGIN. Each skill ZIP inside a skillset still comes from SKILL_MARKET_ORIGIN.
How Octop calls the market
Requests are unauthenticated. Put the market on a private network.
Search and rankings time out after 10 seconds. One JSON body must be at most 4 MiB. Download times out after 30 seconds. One ZIP must be at most 32 MiB. Octop sends User-Agent: octop-skillhub-market/1.0. Search and rankings use Accept: application/json. Download uses Accept: application/zip,application/octet-stream,*/*.
An empty query is replaced with a. limit is clamped to 1–100. There is no combined all rankings path. Octop requests the six paths itself, then builds { "rankings": { "hot": … } } locally.
A failed request is reported as an error. Octop does not fall back to a local skillhub command.
Point Octop at your market
Set the variable on the machine that runs octop run, then restart the process. Write it in ~/.octop/env, which the service loads at startup, or in a systemd Environment= line.
Use scheme, host, and port only. Do not add a path. A value written as market.internal:9000 is treated as https://. A path, query string, or userinfo is discarded. Requests still go to {origin}/api/v1/.... An unset or empty value uses https://api.skillhub.cn. A scheme other than http or https, or a missing host, fails that request. Octop does not silently switch back to the public site.
HTTP API
Search and the six showcase paths return JSON. Download returns a ZIP. There is no combined rankings path.
Search results without slug are dropped. The card title uses displayName, then name, then slug. The summary uses summary, then description. version is stored as a string. Other fields are passed through to the page, including iconUrl, description_zh, downloads, and labels.
A ranking object is returned as Octop received it. The page reads the skills array. Those objects use the same fields as search. section and total are optional and are not used for install.
Download must be a ZIP. The archive needs a SKILL.md at its root. If every file sits in one top-level directory and that directory contains SKILL.md, Octop strips that directory. After extraction, the archive may contain at most 2000 entries and 64 MiB uncompressed. Symlinks, absolute paths, .., and encrypted entries are rejected. HTTP 404 means that slug has no archive.
The browser loads iconUrl itself. Do not use an address that only the Octop process can open.
Minimal deployment
Body of api/v1/search:
Body of api/v1/showcase/recommended:
Publish that directory with Nginx on any port. 9000 below is only an example. Paths with no extension need an explicit JSON type. The download route must choose a ZIP from the slug query. A static file is not enough for that route. A small reverse proxy can serve it.
Restart Octop after you set SKILL_MARKET_ORIGIN. Rankings and search on Skill market should list your items. Install requests ask only this origin for the ZIP.
Skillsets
Import from skill market on the skill-package page does not read the rankings above. It lists cards from the expert market. After you import one, Octop asks the skillset origin for that card's slug, then downloads each skill slug from SKILL_MARKET_ORIGIN.
Set SKILLSET_ORIGIN on the machine that runs octop run, then restart. The rules match SKILL_MARKET_ORIGIN: scheme, host, and port only. A bare host is treated as https://. A path or query is discarded. An unset or empty value uses https://api.skillhub.cn. A scheme other than http or https, or a missing host, fails that import. Octop does not switch back to the public site.
The detail response is a JSON object. Import reads these fields:
When skillSlugs is present, Octop does not call /download. When it is absent, /download must return a ZIP that contains manifest.json and lists skills in skillSlugs or skillSets[].skillSlugs. The archive also needs a workflow note: skillsets/{slug}.md first, otherwise any skillsets/*.md, otherwise identify.md. Detail and download each time out after 30 seconds. One response must be at most 32 MiB. Octop sends Accept: application/json for the detail, Accept: application/zip,*/* for the download, and User-Agent: octop-expert-skillhub/1.0.
The import action does not call GET /api/v1/skillsets for a full list.

