SkillHub Operations

Interact with a SkillHub registry to search, install, publish, and manage skills using curl.

Environment Variables

• SKILLHUB_REGISTRY — Registry URL (default: http://localhost:10070)
• SKILLHUB_TOKEN — API token for authenticated operations (Bearer token)
• SKILLHUB_AGENT_SECRET — Shared secret for agent auto-provisioning

Set the base URL:

REGISTRY="${SKILLHUB_REGISTRY:-http://localhost:10070}"

Authenticated requests use Authorization: Bearer $SKILLHUB_TOKEN.

1. Auto-Provisioning (Get Token)

Internal agents can auto-register and obtain an API token using a shared secret:

curl -s -X POST "$REGISTRY/api/v1/agent/provision" \
  -H 'Content-Type: application/json' \
  -d "{\"handle\":\"$(hostname)-agent\",\"secret\":\"$SKILLHUB_AGENT_SECRET\"}" | jq .

Response: {"token":"clh_...","handle":"my-agent","userId":"uuid"}

Save the token for subsequent requests:

TOKEN=$(curl -s -X POST "$REGISTRY/api/v1/agent/provision" \
  -H 'Content-Type: application/json' \
  -d "{\"handle\":\"$(hostname)-agent\",\"secret\":\"$SKILLHUB_AGENT_SECRET\"}" | jq -r .token)
export SKILLHUB_TOKEN="$TOKEN"

The endpoint returns 404 if SKILLHUB_AGENT_SECRET is not set server-side.

2. Search Skills

Search by keyword (public, approved, non-deleted only):

curl -s "$REGISTRY/api/v1/search?q=$ARGUMENTS" | jq '.hits[] | {slug, displayName, summary}'

Query params: q (required), limit (≤100, default 20), offset, sort. Response: {hits: [...], estimatedTotalHits, ...}.

3. List Skills

curl -s "$REGISTRY/api/v1/skills?sort=downloads&limit=20" \
  | jq '.data[] | {slug, displayName, category, downloads}'

Query params: sort (created|updated|downloads|stars, default created), limit (≤100), cursor, category.

Filter by category:

curl -s "$REGISTRY/api/v1/skills?category=devops&sort=downloads" | jq '.data[] | {slug, displayName}'

Paginate with cursor:

NEXT=$(curl -s "$REGISTRY/api/v1/skills?limit=20" | jq -r .nextCursor)
curl -s "$REGISTRY/api/v1/skills?limit=20&cursor=$NEXT" | jq .

Categories: devops, security, data, frontend, backend, infra, testing, ai, general.

4. Inspect a Skill

curl -s "$REGISTRY/api/v1/skills/SLUG" | jq .

List versions:

curl -s "$REGISTRY/api/v1/skills/SLUG/versions" | jq '.versions[] | {version, createdAt}'

Get a specific version:

curl -s "$REGISTRY/api/v1/skills/SLUG/versions/1.0.0" | jq .

Read a file from a version (defaults: version=latest, path=SKILL.md):

curl -s "$REGISTRY/api/v1/skills/SLUG/file?path=SKILL.md&version=latest"

5. Install a Skill

Download as ZIP and extract to a local skills directory:

SLUG="my-skill"
VERSION="latest"
SKILLS_DIR="${HOME}/.skillhub/skills"

mkdir -p "$SKILLS_DIR/$SLUG"
curl -sfL -o /tmp/skill.zip "$REGISTRY/api/v1/download?slug=$SLUG&version=$VERSION"
unzip -o /tmp/skill.zip -d "$SKILLS_DIR/$SLUG"
rm /tmp/skill.zip

Resolve a fingerprint (content hash) to a version:

curl -s "$REGISTRY/api/v1/resolve?fingerprint=HEX" | jq .

6. Publish a Skill

Upload a skill using multipart form. slug and version are required (semver); slug is not auto-inferred from SKILL.md. Requires authentication.

curl -s -X POST "$REGISTRY/api/agent/skills" \
  -H "Authorization: Bearer $SKILLHUB_TOKEN" \
  -F "slug=my-skill" \
  -F "version=1.0.0" \
  -F "displayName=My Skill" \
  -F "files=@./SKILL.md" \
  -F "files=@./script.sh"

Form fields: slug (required), version (required, semver), displayName, visibility, overwrite, files (repeatable; SKILL.md required).

Version must be strictly greater than the current latest. New skills default to visibility=private, moderationStatus=approved.

7. Skill Lifecycle

Delete (soft delete, owner/admin only):

curl -s -X DELETE "$REGISTRY/api/v1/skills/SLUG" -H "Authorization: Bearer $SKILLHUB_TOKEN"

Undelete:

curl -s -X POST "$REGISTRY/api/v1/skills/SLUG/undelete" -H "Authorization: Bearer $SKILLHUB_TOKEN"

Request public visibility (triggers moderation review):

curl -s -X POST "$REGISTRY/api/v1/skills/SLUG/request-public" -H "Authorization: Bearer $SKILLHUB_TOKEN"

Check current identity:

curl -s "$REGISTRY/api/v1/whoami" -H "Authorization: Bearer $SKILLHUB_TOKEN" | jq .

8. Stars

Star / unstar a skill (authenticated):

curl -s -X POST   "$REGISTRY/api/v1/stars/SLUG" -H "Authorization: Bearer $SKILLHUB_TOKEN"
curl -s -X DELETE "$REGISTRY/api/v1/stars/SLUG" -H "Authorization: Bearer $SKILLHUB_TOKEN"

9. Ratings

Rate a skill (score 1-5):

curl -s -X POST "$REGISTRY/api/v1/skills/SLUG/ratings" \
  -H "Authorization: Bearer $SKILLHUB_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"score":5,"comment":"great"}'

List ratings (public, cursor paginated):

curl -s "$REGISTRY/api/v1/skills/SLUG/ratings?limit=20" | jq '.data[] | {score, comment, user}'

Delete your own rating:

curl -s -X DELETE "$REGISTRY/api/v1/skills/SLUG/ratings" -H "Authorization: Bearer $SKILLHUB_TOKEN"

10. API Tokens

List your tokens:

curl -s "$REGISTRY/api/v1/tokens" -H "Authorization: Bearer $SKILLHUB_TOKEN" | jq .

Create a token (scope: full|read|publish):

curl -s -X POST "$REGISTRY/api/v1/tokens" \
  -H "Authorization: Bearer $SKILLHUB_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"label":"ci-token","scope":"publish","expiresIn":"720h"}'

Revoke a token by ID:

curl -s -X DELETE "$REGISTRY/api/v1/tokens/TOKEN_ID" -H "Authorization: Bearer $SKILLHUB_TOKEN"

11. Namespaces (Organizations)

Create a namespace:

curl -s -X POST "$REGISTRY/api/v1/namespaces" \
  -H "Authorization: Bearer $SKILLHUB_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"slug":"acme","displayName":"Acme Inc","description":"...","type":"org"}'

List your namespaces / get / update / delete:

curl -s        "$REGISTRY/api/v1/namespaces"      -H "Authorization: Bearer $SKILLHUB_TOKEN"
curl -s        "$REGISTRY/api/v1/namespaces/acme" -H "Authorization: Bearer $SKILLHUB_TOKEN"
curl -s -X PUT "$REGISTRY/api/v1/namespaces/acme" -H "Authorization: Bearer $SKILLHUB_TOKEN" \
  -H 'Content-Type: application/json' -d '{"displayName":"Acme Corp"}'
curl -s -X DELETE "$REGISTRY/api/v1/namespaces/acme" -H "Authorization: Bearer $SKILLHUB_TOKEN"

Members:

curl -s "$REGISTRY/api/v1/namespaces/acme/members" -H "Authorization: Bearer $SKILLHUB_TOKEN"
curl -s -X POST "$REGISTRY/api/v1/namespaces/acme/members" \
  -H "Authorization: Bearer $SKILLHUB_TOKEN" -H 'Content-Type: application/json' \
  -d '{"handle":"alice","role":"member"}'
curl -s -X DELETE "$REGISTRY/api/v1/namespaces/acme/members/alice" \
  -H "Authorization: Bearer $SKILLHUB_TOKEN"

12. Notifications

curl -s "$REGISTRY/api/v1/notifications?limit=20"       -H "Authorization: Bearer $SKILLHUB_TOKEN" | jq .
curl -s "$REGISTRY/api/v1/notifications/unread"         -H "Authorization: Bearer $SKILLHUB_TOKEN" | jq .unread
curl -s -X POST "$REGISTRY/api/v1/notifications/NOTIF_ID/read" -H "Authorization: Bearer $SKILLHUB_TOKEN"
curl -s -X POST "$REGISTRY/api/v1/notifications/read-all"      -H "Authorization: Bearer $SKILLHUB_TOKEN"

13. Admin Operations

All endpoints under /api/v1/admin require role=admin.

Users:

curl -s "$REGISTRY/api/v1/users"                 -H "Authorization: Bearer $SKILLHUB_TOKEN"
curl -s -X POST "$REGISTRY/api/v1/users"         -H "Authorization: Bearer $SKILLHUB_TOKEN" \
  -H 'Content-Type: application/json' -d '{"handle":"bob","role":"user","email":"b@x.com"}'
curl -s -X POST "$REGISTRY/api/v1/users/role"    -H "Authorization: Bearer $SKILLHUB_TOKEN" \
  -H 'Content-Type: application/json' -d '{"userId":"UUID","role":"moderator"}'
curl -s -X POST "$REGISTRY/api/v1/users/ban"     -H "Authorization: Bearer $SKILLHUB_TOKEN" \
  -H 'Content-Type: application/json' -d '{"userId":"UUID","reason":"spam"}'

Skill moderation:

curl -s "$REGISTRY/api/v1/admin/skills?visibility=pending" -H "Authorization: Bearer $SKILLHUB_TOKEN"
curl -s -X POST "$REGISTRY/api/v1/admin/skills/SLUG/review" \
  -H "Authorization: Bearer $SKILLHUB_TOKEN" -H 'Content-Type: application/json' \
  -d '{"action":"approve"}'      # or "reject"
curl -s -X POST "$REGISTRY/api/v1/admin/skills/SLUG/visibility" \
  -H "Authorization: Bearer $SKILLHUB_TOKEN" -H 'Content-Type: application/json' \
  -d '{"visibility":"public"}'   # or "private"

Audit logs (filter by action, resource_type, actor_id):

curl -s "$REGISTRY/api/v1/admin/audit-logs?limit=50&action=ban_user" \
  -H "Authorization: Bearer $SKILLHUB_TOKEN" | jq .

Create a token for any user:

curl -s -X POST "$REGISTRY/api/v1/admin/tokens" \
  -H "Authorization: Bearer $SKILLHUB_TOKEN" -H 'Content-Type: application/json' \
  -d '{"userId":"UUID","label":"service","scope":"full"}'

14. Webhooks (Git Import)

Incoming webhook endpoints (signature-verified, configured server-side):

POST /api/v1/webhooks/github   # X-Hub-Signature-256
POST /api/v1/webhooks/gitlab   # X-Gitlab-Token
POST /api/v1/webhooks/gitea    # X-Gitea-Signature

These are called by git providers, not by agents. Enable via server config.

15. Health

curl -s "$REGISTRY/healthz"   # liveness
curl -s "$REGISTRY/readyz"    # readiness (DB check)

SKILL.md Format

When publishing, include a SKILL.md file with YAML frontmatter:

---
name: my-skill
description: What this skill does
allowed-tools: Bash
keywords: [example, demo]
---

Skill instructions go here...

Required fields: name, description. Optional: allowed-tools, keywords, user-invocable, argument-hint, arguments, model, when_to_use.

Response Conventions

• List endpoints return {data: [...], nextCursor: "..."} — paginate by passing cursor back.
• Search returns {hits: [...], estimatedTotalHits: N}.
• Mutating endpoints return {message: "..."} or the created resource.
• Errors return {error: "..."} with appropriate HTTP status (400/401/403/404/500).