> For AI agents: the complete documentation index is available at /en/llms.txt, the full documentation bundle is available at /en/llms-full.txt.

# 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](/en/guide/guides/private-market.md). **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

```text
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.

```bash
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.

```yaml
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

```text
/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`:

```json
{
  "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`:

```json
{
  "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.

```nginx
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`.

```text
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.

```bash
SKILLSET_ORIGIN=http://market.internal:9000
```

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

| Field                      | Use                                                               |
| -------------------------- | ----------------------------------------------------------------- |
| `slug`                     | Skillset id. It must match the slug in the path.                  |
| `displayName` or `name`    | Name of the new skill package.                                    |
| `summary` or `description` | Package description.                                              |
| `iconUrl`                  | Package icon. It must be an `http` or `https` URL Octop can open. |
| `scene`                    | Used to pick a built-in icon name when there is no icon.          |
| `skillSlugs`               | Skill 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 see                                                     | What to check                                                                                                                                                                                       |
| ---------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Skill market still shows the public catalog                      | `SKILL_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 immediately                          | The origin scheme or host is invalid, or a ranking or search did not return valid JSON in time.                                                                                                     |
| The card is there, but install fails                             | `GET /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 blank                                                | `iconUrl` still points at the public internet, or the browser cannot open it.                                                                                                                       |
| Skill-package import still asks the public site for the skillset | `SKILLSET_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`.                            |
