skill-hub-query

# skill-hub-query - **Version**: 1.1.4 - **License**: MIT - **Author**: Evan Song (<https://github.com/Songhonglei>) - **Repository**: <https://github.com/Songhonglei/build-better-skills/tree/main/skills/skill-hub-query> - **Part of**: [`build-better-skills`](https://github.com/Songhonglei/build-better-skills) suite — see [Stages](https://github.com/Songhonglei/build-better-skills#stages) for the lifecycle map. > Drive any compatible Skill Hub from the command line with a single, > predictable interface. Works with self-hosted Hubs that implement the > [documented API contract](#self-hosted-hub-api-contract). > **Heads-up**: this tool talks to Hubs that implement the API contract below. > It does NOT target [clawhub.ai](https://clawhub.ai) — that Hub has its own > API surface and an official CLI named `clawhub`. Use this tool when you have > a private or compatible Hub to drive. --- ## Agent workflow ### Dual-channel auto-selection When the user asks a Hub-related question ("what's on the hub", "install X", "search for Y"), run `sync.sh` / `query.sh` / `install.sh` directly — the scripts pick the right channel: | User state | Channel | Capability | |------------|---------|------------| | Token set (env or credentials file) | **OpenAPI** (`<HUB_API_PREFIX>/*` with auth header) | Full features incl. private skills | | No token | **Legacy fallback** (`<HUB_LEGACY_API_PREFIX>/*` without auth) | Search & install public skills | When falling back the first time, the script emits a one-shot notice suggesting the user request a token for long-term stability. After that it stays silent. ### When to actively suggest the user configure a token Only when the user explicitly needs to: - install a **private** skill (search finds it, but download requires auth) - get **contract-stable, long-term** behavior (legacy fallback may be removed) - when `doctor.sh` explicitly recommends it ### Setting up the token (after the user provides one) ```bash # Option A: env var (CI / temporary) export SKILL_HUB_URL="https://hub.your-company.com" export SKILL_HUB_TOKEN="<your-token>" # Option B: credentials file (recommended, cross-skill reusable) mkdir -p "${XDG_CONFIG_HOME:-$HOME/.config}/skill-hub-query" cat > "${XDG_CONFIG_HOME:-$HOME/.config}/skill-hub-query/credentials.json" <<EOF { "endpoint": "https://hub.your-company.com", "token": "<your-token>", "authHeader": "Authorization", "authScheme": "Bearer " } EOF chmod 600 "${XDG_CONFIG_HOME:-$HOME/.config}/skill-hub-query/credentials.json" ``` Then verify with `bash scripts/doctor.sh`. > Never echo a full token back to the user, write it outside the credentials > directory, or commit it to git. ### "What's on the hub for X?" 1. Silently `bash sync.sh` (incremental; zero HTTP if nothing changed) 2. `bash query.sh keyword X` 3. Reply with a user-readable table (**name / author / version / updated / summary**), not raw IDs 4. If ≤5 hits include the summary; if many, list top 10 + total count ### "Install X" 1. `bash sync.sh` then `bash query.sh slug X` to get the latest version and summary 2. **Confirm first**: "Will install **{displayName}** v{latest} (author X). Proceed?" 3. After user approves, run: `bash install.sh X --yes` 4. Without `--yes`, install.sh blocks on stdin for already-installed skills; in non-interactive mode it refuses outright — preventing silent overwrite 5. Show: "installed; will be loaded on the next agent session" ### "Install a batch" 1. Query each slug for version + permission info 2. Show one combined manifest + estimated download size, wait for approval 3. After approval, install **serially** with `install.sh <slug> --yes` (avoid rate limiting); report failures separately --- ## Configuration > ⚠️ **You MUST configure `SKILL_HUB_URL`** (or `.endpoint` in the credentials > file) before any network call. There is no baked-in default, because no > single public Hub is guaranteed to implement this contract. Run > `bash scripts/doctor.sh` first — it will tell you exactly what's missing. | Env variable | Default | Purpose | |---|---|---| | `SKILL_HUB_PROVIDER` | (unset) | Select a **built-in adapter** for a known public Hub instead of the generic contract. Currently supports `skillhub_cn` (see [Built-in provider: skillhub.cn](#built-in-provider-skillhubcn)). When unset, the generic-contract behavior below applies. | | `SKILL_HUB_URL` | **(must be set)** | Hub base URL, e.g. `https://hub.your-company.com` (ignored when `SKILL_HUB_PROVIDER` is set) | | `SKILL_HUB_API_PREFIX` | `/api/v1/skill` | Primary API path | | `SKILL_HUB_LEGACY_API_PREFIX` | `/api/skill` | Fallback API path | | `SKILL_HUB_AUTH_HEADER` | `Authorization` | HTTP header name for auth | | `SKILL_HUB_AUTH_SCHEME` | `Bearer ` | Header value prefix (note trailing space; set to `""` for API-key auth) | | `SKILL_HUB_TOKEN` | (unset) | API token (takes precedence over credentials file) | | `SKILL_HUB_TOKEN_FILE` | `${XDG_CONFIG_HOME:-~/.config}/skill-hub-query/credentials.json` | Credentials file | | `SKILL_HUB_SKILLS_DIR` | (auto-detect) | Where installed skills land | | `SKILL_HUB_CACHE_DIR` | `${XDG_CACHE_HOME:-~/.cache}/skill-hub-query` | Where the local cache lives | | `SKILL_HUB_EDIT_PREFIX` | same as `SKILL_HUB_LEGACY_API_PREFIX` | Path prefix for `/edit` and `/detail` (edit.sh only) | | `SKILL_HUB_DISABLE_EDIT` | `0` | Set to `1` to disable `edit.sh` when your Hub does not implement `/edit` | | `SKILL_HUB_BACKUP_RETENTION` | `20` | How many recent edit.sh backups to keep per slug (older are pruned) | | `SKILL_HUB_DOWNLOAD_TIMEOUT` | `120` | curl `--max-time` (seconds) for skill ZIP download in install.sh | | `SKILL_HUB_OWNER_EMAIL` | (auto: `git config user.email`) | Email used by edit.sh owner pre-check; override if your git identity differs from your Hub identity | ### Skills install directory Resolved in order: `SKILL_HUB_SKILLS_DIR` -> `~/.claude/skills/` -> `~/.openclaw/workspace/skills/` -> `~/.config/skills/` (first existing wins). ### Setting up Hub URL + token (one-time) ```bash echo 'export SKILL_HUB_URL="https://hub.your-company.com"' >> ~/.bashrc echo 'export SKILL_HUB_TOKEN="<your-token>"' >> ~/.bashrc source ~/.bashrc ``` Or — for richer per-Hub profiles — use the credentials file: ```bash mkdir -p "${XDG_CONFIG_HOME:-$HOME/.config}/skill-hub-query" cat > "${XDG_CONFIG_HOME:-$HOME/.config}/skill-hub-query/credentials.json" <<EOF { "endpoint": "https://hub.your-company.com", "token": "<your-token>", "authHeader": "Authorization", "authScheme": "Bearer " } EOF chmod 600 "${XDG_CONFIG_HOME:-$HOME/.config}/skill-hub-query/credentials.json" ``` > Never commit tokens to git, never hardcode them in scripts, and never > echo the full token to the user. --- ## Built-in provider: skillhub.cn [skillhub.cn](https://skillhub.cn) is a China-optimized public skills hub. Because its API shape differs from the generic contract above, this skill ships a **built-in adapter** for it. Activate it with: ```bash export SKILL_HUB_PROVIDER=skillhub_cn # one-off # or persist it: echo 'export SKILL_HUB_PROVIDER=skillhub_cn' >> ~/.bashrc ``` When the provider is active, `SKILL_HUB_URL` / token / API-prefix env vars are **ignored** — the adapter targets `https://api.skillhub.cn` directly. No token is needed (all supported operations are public, read-only). ### Capability matrix (skillhub.cn) | Operation | Command | Supported? | |---|---|---| | Search / browse | `query.sh keyword <kw>` · `query.sh today` · `query.sh combo --keyword= --category= --source=` | ✅ live (no local cache) | | Skill detail | `query.sh slug <slug>` | ✅ | | Version history | `query.sh versions <slug>` | ✅ | | Install | `install.sh <slug> [--yes]` | ✅ | | `sync.sh` | — | ⚪ no-op (live search needs no cache; informational, exit 0) | | `query.sh author <handle>` | — | ❌ no author-filter param on skillhub.cn (use `keyword`) | | `edit.sh` (edit card metadata) | — | ❌ not available — see below | ### Why edit is not supported on skillhub.cn skillhub.cn card metadata (displayName / summary / tags / category) is a **one-way mirror synced from the upstream source** (clawhub / GitHub). The only write endpoints the platform exposes are publish / unlist / relist / delete / claim — **none of which edit card fields**. To change a card, update the **upstream source** and re-publish/let it re-sync. (This differs from a generic Hub that implements a `PUT /edit` contract, which `edit.sh` drives.) ### Examples (skillhub.cn) ```bash export SKILL_HUB_PROVIDER=skillhub_cn bash scripts/query.sh keyword code # search bash scripts/query.sh today # browse newest bash scripts/query.sh slug skill-creator # detail bash scripts/query.sh versions skill-creator # versions bash scripts/install.sh skill-creator --yes # install bash scripts/doctor.sh # shows the capability matrix ``` --- ## Self-check / diagnosis ```bash bash scripts/doctor.sh ``` `doctor.sh` probes both channels (OpenAPI with token, legacy without) plus optionally the `/edit` endpoint. If at least one channel works, the skill is usable. --- ## Cache & performance All list queries hit a local JSON cache (`${SKILL_HUB_CACHE_DIR}/skill-cache.json`), parsed with jq (sub-ms). | Trigger | Sync action | |---|---| | Cache missing or corrupt | Full sync | | User asks "refresh cache" | Forced full sync | | Routine query | Incremental (records with `updatedAt` newer than cursor) | | Incremental page 1 entirely new (= 100 records) | Upgrade to full sync | > Incremental sync does NOT prune removed/withdrawn skills (it only unions > new records). If you hit a "found in cache but install 404s" case, run > `bash sync.sh --full`. The full sync log will report "pruned N removed". --- ## Multi-user / shared-host caveat The legacy channel (no token) identifies callers by **source IP**. On shared hosts (containers, CI runners), all agents/users share one identity. `scope=mine` returns the list for that shared identity. For per-user isolation on shared hosts, configure a per-user `SKILL_HUB_TOKEN`. --- ## Quick reference: scenarios ### Scenario 1: search | User request | Action | |---|---| | "Search for calendar-related skills" | `bash sync.sh && bash query.sh keyword calendar` | | "What was published this week?" | `bash sync.sh && bash query.sh time this_week` | | "Anything on 2026-05-20?" | `bash query.sh time 2026-05-20` (single day: 00:00 - 23:59) | | "Between 5/18 and 5/22?" | `bash query.sh time 2026-05-18:2026-05-22` | | "Last week by user X?" | `bash sync.sh && bash query.sh combo --since=last_week --author=X` | | "**Only this account (avoid prefix collisions)**" | `bash query.sh author alice@example.com --exact` | | "Official skills today?" | `bash sync.sh && bash query.sh combo --since=today --source=official` | | "Show details of skill XX" | `bash query.sh slug XX` | ### Scenario 2: install / update | User request | Action | |---|---| | "Install calendar" | 1) Check cached version 2) Confirm with user 3) After approval: `bash install.sh calendar --yes` | | "Update html-go-live to latest" | First `query.sh slug html-go-live` for new version + confirm with user -> after approval `bash install.sh html-go-live --yes` (`--yes` must be user-authorized) | | "Install html-go-live 2.4.0" | Same confirmation flow -> after approval `bash install.sh html-go-live 2.4.0 --yes` | | "Search skillhub.cn for X" | `SKILL_HUB_PROVIDER=skillhub_cn bash query.sh keyword X` (no token; see [Built-in provider: skillhub.cn](#built-in-provider-skillhubcn)) |