skill-hub-query

• Version: 1.4.0
• 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 suite — see 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.

> Heads-up: this tool talks to Hubs that implement the API contract below.
> It does NOT target 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.

Requirements

> unzip is not required. Extraction goes through Python's zipfile
> because Info-ZIP unzip 6.00 ignores the ZIP spec's UTF-8 filename flag and
> mangles non-ASCII filenames — the installed skill then crashes on first run
> with a FileNotFoundError that points at the wrong culprit. Run
> bash scripts/doctor.sh to verify filename handling on your machine.

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:

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)

# 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

"Manage team members"

Runs team.sh (team member management: search / my teams / detail / member
list / add / remove). Optional Hub capability — contract in
references/api.md §5; if your Hub does not implement
it, set SKILL_HUB_DISABLE_TEAM=1.

Field-tested pitfalls the script already defends against (do not bypass):

• add returns success even for non-existent emails and writes a dangling
  record — the script re-verifies every add against the member list.
• add is idempotent for existing members — the script de-duplicates first
  and reports the existing role (never silently changes it).
• The pagination parameter is current= (page= is silently ignored).
• Valid roles: member / admin / viewer.
• Write operations show the target team + full roster and wait for
  confirmation; --yes must be user-authorized (an agent must never pass it).

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.

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)

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:

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 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:

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)

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)

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 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).

> 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".

Do not treat cached latestVersion as authoritative

query.sh list/slug queries read the local cache. When that cache is stale the
latestVersion field is stale too — and a stale value looks exactly like a fresh
one. There is no signal telling you to doubt it.

Observed failure: a cache left untouched for 67 days reported an old release as
"latest", which nearly caused a publish against the wrong version baseline.

• query.sh now warns when the cache is older than 7 days (notice) or
  older than 30 days (loud). Warnings go to stderr only and never block —
  offline use stays intentional. When you see one, run sync.sh before trusting
  the numbers.
• For anything version-critical — deciding a release number, comparing
  versions, checking whether an upgrade exists — re-sync first and only then read
  the number:

bash scripts/sync.sh && bash scripts/query.sh slug <slug>

> Note: the skillhub_cn provider queries the hub live and never reads this
> cache, so the warning does not apply there — it also offers a dedicated
> query.sh versions <slug> listing.

> Rule of thumb: use the cache for discovery (search, browse, read summaries);
> never let a cached number decide a release.

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

Scenario 2: install / update

> --yes is a user-authorization flag; an LLM/agent caller must not add it on its own.
> The user must explicitly say "yes" / "go ahead" / "install" first; SKILL.md examples in
> automated paths intentionally omit --yes.

Scenario 3: version history

Scenario 4: diagnose / refresh

Scenario 5: edit a skill's card metadata

Use edit.sh to modify the Hub card for a skill you own. You can only edit
skills you own; non-owners get 403 from the Hub.

> Hub compatibility: This requires your Hub to implement
> PUT /edit/<slug> and GET /detail/<slug>. If your Hub does not implement
> them, run: export SKILL_HUB_DISABLE_EDIT=1 and edit.sh will refuse to run
> with an informative message instead of producing confusing errors.

> Agent caller rule (same as install.sh): --yes is a user-authorization
> flag. An agent must NOT add it on its own; the human user must explicitly
> approve. Without --yes, edit.sh blocks on stdin in a TTY and refuses to
> proceed in non-interactive mode.

> Array fields (tags / scene / business / ...) are full overwrites, not
> additive. To append, first --show to read the current list, then submit
> the merged list.

> Supported fields: see bash edit.sh --help for the full list of CLI flags.

> Safety guarantees (five-stage flow):
> 1. GET the authoritative current value
> 2. Owner pre-check (server-side 403 is the ultimate safety net)
> 3. Build patch + show diff (skip PUT if no actual diff)
> 4. Backup to disk + user confirm (backups in ${SKILL_HUB_CACHE_DIR}/edit-backups/, latest 20 per slug)
> 5. PUT + dual-channel verify with retry + auto-rollback on mismatch
> (visibility silent-downgrade is a documented partial-success edge case)

Self-hosted Hub: API contract

Your Hub must implement these endpoints (response envelope
{code: 200, message: "", data: {...}}):

GET  <endpoint><SKILL_HUB_API_PREFIX>/search?page=N&size=N&orderBy=updatedAt&order=desc
     -> data: {records: [<skill>...], total: <number>}

GET  <endpoint><SKILL_HUB_API_PREFIX>/versions/<slug>?limit=N
     -> data: {items: [{version, changelog, ...}, ...]}

GET  <endpoint><SKILL_HUB_API_PREFIX>/versions/<slug>/<version>
     -> data: {version: {...}}

GET  <endpoint><SKILL_HUB_LEGACY_API_PREFIX>/download/<slug>?version=<v>&track=true
     -> body: zip bytes (Content-Type may be application/octet-stream)

Each <skill> record minimally contains:

{
  "slug": "string",
  "displayName": "string",
  "summary": "string",
  "owner": {"displayName": "...", "handle": "...", "email": "..."},
  "source": "official|personal|external",
  "updatedAt": <epoch_ms>,
  "latestVersion": {"version": "x.y.z"}
}

For edit.sh (optional), additionally:

PUT  <endpoint><SKILL_HUB_EDIT_PREFIX>/edit/<slug>
     body = JSON patch (any subset of editable fields)
     empty body returns the current snapshot
     -> data: <full skill metadata>

GET  <endpoint><SKILL_HUB_EDIT_PREFIX>/detail/<slug>
     -> data: {skill: <full metadata>}

If your Hub uses a different auth scheme, override SKILL_HUB_AUTH_HEADER and
SKILL_HUB_AUTH_SCHEME (e.g. SKILL_HUB_AUTH_HEADER=X-API-Key
SKILL_HUB_AUTH_SCHEME="").

> 📖 Need the full request/response field reference? When implementing or
> debugging a self-hosted Hub, read references/api.md —
> it documents every endpoint's exact parameters, response envelope, and field
> semantics in detail.

File layout

skill-hub-query/
├── SKILL.md                          # this file
├── credentials.example.json          # template for the credentials file
├── references/
│   └── api.md                        # detailed API contract reference
└── scripts/
    ├── _lib.sh                       # path discovery + token + curl wrapper (sourced)
    ├── _edit_lib.sh                  # edit.sh internals (sourced)
    ├── _zip_safe.py                  # zip list/extract with correct filename decoding
    ├── doctor.sh                     # one-shot self-check
    ├── sync.sh                       # full / incremental cache sync
    ├── query.sh                      # query the local cache
    ├── install.sh                    # download + safe extract + atomic dir replace
    └── edit.sh                       # five-stage safe metadata editor (optional Hub features)

Cache & credentials (NOT in skill directory, NOT git-tracked):

${SKILL_HUB_CACHE_DIR:-~/.cache/skill-hub-query}/
├── skill-cache.json                  # full skill index (key = slug)
├── skill-cache-meta.json             # sync cursor + metadata
├── skill-versions.json               # locally installed skill versions
└── edit-backups/                     # snapshots before each edit (latest 20 per slug)

${XDG_CONFIG_HOME:-~/.config}/skill-hub-query/credentials.json   (chmod 600)

Direct API call pattern (advanced)

# 1) source the lib (loads token / paths / curl wrapper)
source ./scripts/_lib.sh

# 2) call any API path (api_get auto-routes: token -> OpenAPI; none -> legacy)
api_get "${HUB_API_PREFIX}/search?keyword=calendar&size=20"
api_get "${HUB_API_PREFIX}/versions/html-go-live?limit=10"
api_get "${HUB_API_PREFIX}/versions/html-go-live/2.4.0"

# 3) download a zip (public skills don't need auth; private skills do)
api_download "html-go-live" "2.4.0" "/tmp/x.zip"

For direct curl calls, pass the auth header when you have a token:
-H "$(load_auth_header): $(load_auth_scheme)$SKILL_HUB_TOKEN".

Error reference

Known limitations

1. The ZIP download endpoint is not part of the formal OpenAPI spec on all Hubs; install.sh uses the legacy /download/<slug> path (public skills: no auth needed; private: token required).
2. Some legacy fields (starredAt, starred, litToday, etc.) are deprecated and may be missing depending on Hub version.
3. Incremental sync does not prune removed skills (see "Cache" section).
4. The legacy channel is a transition path; for production / long-term use, configure a token.
5. edit.sh requires optional /edit and /detail endpoints; not all Hubs expose them.
6. The cached latestVersion.version is not a source of truth. It is a snapshot written by sync.sh and is not invalidated when the Hub publishes afterwards (observed drift: cache 1.3.0 vs. real latest 2.2.2). install.sh therefore queries /versions/<slug>?limit=1 first and only falls back to the cache — with a loud warning — when that call fails. If you write your own logic, use items[0].version, never the cached field.
7. A Hub's download endpoint may serve a version other than the one requested (observed: requested v2.2.2, received the v1.3.0 package). Before replacing anything, install.sh compares the version declared in the package's SKILL.md and records the actual value with a warning. It warns rather than fails, because some packages legitimately ship an un-bumped SKILL.md. When you need an exact version, pass it explicitly and check the output.

Version

Currently v1.2.0. Full history: CHANGELOG.md.