For AI agents: the complete documentation index is available at /en/llms.txt, the full documentation bundle is available at /en/llms-full.txt, and this page is available as Markdown at /en/guide/guides/skill-market.md.
  • English
  • 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

    Open Skill market
            │
            ▼
    Octop process   GET {SKILL_MARKET_ORIGIN}/api/v1/showcase/hot
                    GET …/featured  …/newest  …/recommended  …/trending  …/paid
            │
            │  Six rankings, requested separately. One failure leaves the others in place.
            ▼
    You search
            │
            ▼
    Octop process   GET {SKILL_MARKET_ORIGIN}/api/v1/search?q=…&limit=…
            │
    You click Install
            │
            ▼
    Octop process   GET {SKILL_MARKET_ORIGIN}/api/v1/download?slug=…

    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.

    SKILL_MARKET_ORIGIN=http://market.internal:9000

    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.

    openapi: 3.0.3
    info:
      title: Octop private skill market
      version: "1"
      description: >
        Read by the Octop server. Search and the six showcase paths return
        JSON. Download returns a ZIP. There is no combined rankings path.
    servers:
      - url: http://market.internal:9000
    paths:
      /api/v1/search:
        get:
          operationId: searchSkills
          summary: Search skills
          parameters:
            - in: query
              name: q
              required: true
              schema: { type: string }
            - in: query
              name: limit
              schema: { type: integer, minimum: 1, maximum: 100 }
          responses:
            "200":
              description: Search envelope
              content:
                application/json:
                  schema:
                    $ref: "#/components/schemas/SearchResponse"
      /api/v1/showcase/{kind}:
        get:
          operationId: showcaseSkills
          summary: One ranking section
          parameters:
            - in: path
              name: kind
              required: true
              schema:
                type: string
                enum: [hot, featured, newest, recommended, trending, paid]
          responses:
            "200":
              description: Ranking object. Octop passes it through.
              content:
                application/json:
                  schema:
                    $ref: "#/components/schemas/Ranking"
      /api/v1/download:
        get:
          operationId: downloadSkill
          summary: Skill package bytes
          parameters:
            - in: query
              name: slug
              required: true
              schema: { type: string }
          responses:
            "200":
              description: ZIP archive
              content:
                application/zip:
                  schema: { type: string, format: binary }
            "404":
              description: Skill is not published
    components:
      schemas:
        SearchResponse:
          type: object
          required: [results]
          properties:
            results:
              type: array
              items: { $ref: "#/components/schemas/Skill" }
        Ranking:
          type: object
          properties:
            section: { type: string }
            total: { type: integer }
            skills:
              type: array
              items: { $ref: "#/components/schemas/Skill" }
        Skill:
          type: object
          required: [slug]
          properties:
            slug: { type: string }
            displayName: { type: string }
            name: { type: string }
            summary: { type: string }
            description: { type: string }
            version: { type: string }
            description_zh: { type: string }
            iconUrl: { type: string, description: "http(s) URL the browser can load" }
            downloads: { type: integer }
            installs: { type: integer }
            stars: { type: integer }
            category: { type: string }
            labels:
              type: object
              additionalProperties: true

    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

    /srv/skill-market/
    ├── api/v1/search                 # A fixed JSON body is enough if you ignore the query
    ├── api/v1/showcase/recommended
    ├── api/v1/showcase/hot
    ├── api/v1/showcase/featured
    ├── api/v1/showcase/newest
    ├── api/v1/showcase/trending
    ├── api/v1/showcase/paid
    └── api/v1/download               # Return the ZIP for the slug query parameter

    Body of api/v1/search:

    {
      "results": [
        {
          "slug": "weather",
          "displayName": "天气",
          "summary": "查询城市天气",
          "version": "0.1.0",
          "description_zh": "查询城市天气",
          "iconUrl": "http://market.internal:9000/icons/weather.png"
        }
      ]
    }

    Body of api/v1/showcase/recommended:

    {
      "section": "recommended",
      "total": 1,
      "skills": [
        {
          "slug": "weather",
          "displayName": "天气",
          "summary": "查询城市天气",
          "version": "0.1.0"
        }
      ]
    }

    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.

    server {
        listen 9000;
        server_name market.internal;
        root /srv/skill-market;
        location /api/v1/showcase/ {
            default_type application/json;
        }
        location = /api/v1/search {
            default_type application/json;
        }
    }

    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.

    Import on the skill-package page
            │
            ▼
    Octop process   GET {SKILLSET_ORIGIN}/api/v1/skillsets/{slug}
            │
            │  If the detail has no skillSlugs, also fetch the archive
            ▼
    Octop process   GET {SKILLSET_ORIGIN}/api/v1/skillsets/{slug}/download
            │
            ▼
    Octop process   GET {SKILL_MARKET_ORIGIN}/api/v1/download?slug=…   (each skill in the set)

    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.

    SKILLSET_ORIGIN=http://market.internal:9000

    The detail response is a JSON object. Import reads these fields:

    FieldUse
    slugSkillset id. It must match the slug in the path.
    displayName or nameName of the new skill package.
    summary or descriptionPackage description.
    iconUrlPackage icon. It must be an http or https URL Octop can open.
    sceneUsed to pick a built-in icon name when there is no icon.
    skillSlugsSkill slugs to download.

    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.

    When search or import fails

    What you seeWhat to check
    Skill market still shows the public catalogSKILL_MARKET_ORIGIN is not in the environment of octop run, or you did not restart. From the Octop machine, curl the search URL and confirm it returns JSON with results within 10 seconds.
    The market reports an error immediatelyThe origin scheme or host is invalid, or a ranking or search did not return valid JSON in time.
    The card is there, but install failsGET /api/v1/download?slug= is not a ZIP, the archive has no SKILL.md, or it exceeds a size limit. 404 means that slug has no archive.
    The icon is blankiconUrl still points at the public internet, or the browser cannot open it.
    Skill-package import still asks the public site for the skillsetSKILLSET_ORIGIN is not in the environment of octop run, or you did not restart. Import reads {SKILLSET_ORIGIN}/api/v1/skillsets/{slug}, not SKILL_MARKET_ORIGIN.