Skillhub

<div align="center"> <img src="./skillhub-logo.svg" alt="SkillHub Logo" width="120" height="120" /> <h1>SkillHub</h1> <p>An enterprise-grade, open-source agent skill registry — publish, discover, and manage reusable skill packages across your organization.</p> </div> <div align="center">

</div> <div align="center">

English | 中文

</div>

---

SkillHub is a self-hosted platform that gives teams a private, governed place to share agent skills. Publish a skill package, push it to a namespace, and let others find it through search or install it via CLI. Built for on-premise deployment behind your firewall, with the same polish you'd expect from a public registry.

📖 Full Documentation →

Highlights

• Self-Hosted & Private — Deploy on your own infrastructure. Keep proprietary skills behind your firewall with full data sovereignty. One make dev-all command to get running locally.
• Publish & Version — Upload agent skill packages with semantic versioning, custom tags (beta, stable), and automatic latest tracking.
• Discover — Full-text search with filters by namespace, downloads, ratings, and recency. Visibility rules ensure users only see what they're authorized to.
• Team Namespaces — Organize skills under team or global scopes. Each namespace has its own members, roles (Owner / Admin / Member), and publishing policies.
• Review & Governance — Team admins review within their namespace; platform admins gate promotions to the global scope. Governance actions are audit-logged for compliance.
• Social Features — Star skills, rate them, and track downloads. Build a community around your organization's best practices.
• Account Merging — Consolidate multiple OAuth identities and API tokens under a single user account.
• API Token Management — Generate scoped tokens for CLI and programmatic access with prefix-based secure hashing.
• CLI-First — Native REST API plus a compatibility layer for existing ClawHub-style registry clients. Native CLI APIs are the primary supported path while protocol compatibility continues to expand.
• Pluggable Storage — Local filesystem for development, S3 / MinIO for production. Swap via config.
• Internationalization — Multi-language support with i18next.

Quick Start

Start the full local stack with one of the following commands:

Official images:

rm -rf /tmp/skillhub-runtime
curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime-github.sh | sh -s -- up

The default command pulls the latest stable release images. Use --version edge if you want the newest build from main.

Aliyun mirror shortcut:

rm -rf /tmp/skillhub-aliyun
curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- up --home /tmp/skillhub-aliyun --aliyun --version latest

If deployment runs into problems, clear the existing runtime home and retry.

Prerequisites

• Docker & Docker Compose

Local Development

make dev-all

Then open:

• Web UI: http://localhost:3000
• Backend API: http://localhost:8080

By default, make dev-all starts the backend with the local profile. In that mode, local development keeps the mock-auth users below and also creates a password-based bootstrap admin account by default:

• local-user for normal publishing and namespace operations
• local-admin with SUPER_ADMIN for review and admin flows

Use them with the X-Mock-User-Id header in local development.

The local bootstrap admin is enabled by default in application-local.yml:

• username: admin
• password: ChangeMe!2026
• To disable it, set BOOTSTRAP_ADMIN_ENABLED=false before starting the backend.

Stop everything with:

make dev-all-down

Reset local dependencies and start from a clean slate with:

make dev-all-reset

Run make help to see all available commands.

Useful backend commands:

make test
make test-backend-app
make build-backend-app

Do not run ./mvnw -pl skillhub-app clean test directly under server/. skillhub-app depends on sibling modules in the same repo, and a standalone clean build can fall back to stale artifacts from the local Maven repository, which surfaces misleading cannot find symbol and signature-mismatch errors. Use -am, or the make test-backend-app and make build-backend-app targets above.

For the full development workflow (local dev → staging → PR), see docs/dev-workflow.md.

API Contract Sync

OpenAPI types for the web client are checked into the repository. When backend API contracts change, regenerate the SDK and commit the updated generated file:

make generate-api

For a stricter end-to-end drift check, run:

./scripts/check-openapi-generated.sh

This starts local dependencies, boots the backend, regenerates the frontend schema, and fails if the checked-in SDK is stale.

Container Runtime

Published runtime images are built by GitHub Actions and pushed to GHCR. This is the supported path for anyone who wants a ready-to-use local environment without building the backend or frontend on their machine. Published images target both linux/amd64 and linux/arm64.

1. Copy the runtime environment template.
2. Pick an image tag.
3. Start the stack with Docker Compose.

cp .env.release.example .env.release

Recommended image tags:

• SKILLHUB_VERSION=edge for the latest main build
• SKILLHUB_VERSION=vX.Y.Z for a fixed release

Start the runtime:

make validate-release-config
docker compose --env-file .env.release -f compose.release.yml up -d

Then open:

• Web UI: SKILLHUB_PUBLIC_BASE_URL 对应的地址
• Backend API: http://localhost:8080

Stop it with:

docker compose --env-file .env.release -f compose.release.yml down

The runtime stack uses its own Compose project name, so it does not collide with containers from make dev-all.

The production Compose stack now defaults to the docker profile only. It does not enable local mock auth. The release template (.env.release.example) enables the bootstrap admin by default, so zero-config quickstart via runtime.sh works out of the box:

• username: admin
• password: ChangeMe!2026

Recommended production baseline:

• set SKILLHUB_PUBLIC_BASE_URL to the final HTTPS entrypoint
• keep PostgreSQL / Redis bound to 127.0.0.1
• use external S3 / OSS via SKILLHUB_STORAGE_S3_*
• change BOOTSTRAP_ADMIN_PASSWORD to a strong password (validate-release-config.sh rejects the default ChangeMe!2026)
• rotate or disable the bootstrap admin after initial setup
• run make validate-release-config before docker compose up -d

If the GHCR package remains private, run docker login ghcr.io before docker compose up -d.

Upload Allowlist Override

Skill package upload validation uses the default extension allowlist from SkillPackagePolicy.java. SkillPublishProperties uses that same list by default for skillhub.publish.allowed-file-extensions.

If you need to replace the default allowlist at runtime, set:

SKILLHUB_PUBLISH_ALLOWED_FILE_EXTENSIONS=.md,.json,.xsd,.xsl,.dtd,.docx,.xlsx,.pptx

Spring Boot binds this environment variable to skillhub.publish.allowed-file-extensions. When set, it replaces the default allowlist instead of appending to it.

Monitoring

A Prometheus + Grafana monitoring stack lives under monitoring/. It scrapes the backend's Actuator Prometheus endpoint.

Start it with:

cd monitoring
docker compose -f docker-compose.monitoring.yml up -d

Then open:

• Prometheus: http://localhost:9090
• Grafana: http://localhost:3001 (admin / admin)

By default Prometheus scrapes http://host.docker.internal:8080/actuator/prometheus, so start the backend locally on port 8080 first.

Kubernetes

Basic Kubernetes manifests are available under deploy/k8s/:

• configmap.yaml
• secret.yaml.example
• backend-deployment.yaml
• frontend-deployment.yaml
• services.yaml
• ingress.yaml

Apply them after creating your own secret:

kubectl apply -f deploy/k8s/configmap.yaml
kubectl apply -f deploy/k8s/secret.yaml
kubectl apply -f deploy/k8s/backend-deployment.yaml
kubectl apply -f deploy/k8s/frontend-deployment.yaml
kubectl apply -f deploy/k8s/services.yaml
kubectl apply -f deploy/k8s/ingress.yaml

Smoke Test

A lightweight smoke test script is available at scripts/smoke-test.sh.

Run it against a local backend:

./scripts/smoke-test.sh http://localhost:8080

Architecture

┌─────────────┐     ┌─────────────┐     ┌──────────────┐
│   Web UI    │     │  CLI Tools  │     │  REST API    │
│  (React 19) │     │             │     │              │
└──────┬──────┘     └──────┬──────┘     └──────┬───────┘
       │                   │                   │
       └───────────────────┼──────────────────