skillhub README

The project's README from github.com/iflytek/skillhub. As one markdown file: README.md.

SkillHub Logo

SkillHub

An enterprise-grade, open-source agent skill registry — publish, discover, and manage reusable skill packages across your organization.

DeepWiki Docs Discord License Build Docker Java React

GitHub Stars GitHub Watchers

iflytek%2Fskillhub | Trendshift  AAIF Associate Member

English | 中文

SkillHub Demo

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.

⭐ If SkillHub fits your team, star the repo to help other teams find it, and Watch → Custom → Releases to get notified when a new version ships.

Share Great Skills

Great Skills become more valuable when they are shared. If you have a Skill that has proved useful in real work or everyday life, share it with the SkillHub community and help grow an open, practical Skill ecosystem. We welcome Skills for daily life, office work, learning and research, travel and events, content creation, data analysis, and software development—not only engineering workflows.

High-quality community contributions may join the curated starter collection, making new SkillHub deployments useful from day one. You do not need to finish the full adaptation before joining in: open an issue with the Skill's source and the problem it solves, or submit a PR by following the Skill sharing guide.

Documentation

Governance and Safety

Highlights

Quick Start

Start the full local stack with:

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

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

Configure public URL (recommended for production):

curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- up --public-url https://skillhub.your-company.com

The --public-url parameter sets the public access URL for your SkillHub instance. This ensures:

For users in China (Aliyun mirror):

curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- up --aliyun --public-url https://skillhub.your-company.com --version latest

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

SkillHub CLI

Install and manage Agent skills from the command line:

# Install CLI
npm install -g @astron-team/skillhub

# Or run directly
npx @astron-team/skillhub@latest version

# Login
skillhub login --token sk_xxx --registry https://skill.xfyun.cn

# Search and install skills
skillhub search pdf
skillhub install pdf-parser --agent codex

# List installed skills
skillhub list

📖 Full guide: docs/skillhub/en/guide/cli.md

Prerequisites

Local Development

make dev-all

For developers in China: If Maven dependency download times out, configure Aliyun mirror. See Local Development Guide for details.

Then open:

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:

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

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

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 server and web images target linux/amd64, linux/arm64, and linux/riscv64; the scanner image currently targets linux/amd64 and linux/arm64.

Quick deployment with curl:

# Default (GHCR images)
curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- up --public-url https://skillhub.your-company.com

# Aliyun mirror (recommended for users in China)
curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- up --aliyun --public-url https://skillhub.your-company.com --version latest

Deployment parameters:

Parameter Description Example
--public-url <url> Public access URL (recommended) --public-url https://skill.example.com
--version <tag> Specific image tag --version v0.2.0
--aliyun Use Aliyun mirror (China) --aliyun
--home <dir> Runtime directory --home /opt/skillhub
--no-scanner Disable security scanner --no-scanner

Important: Configure --public-url for production deployments to ensure CLI install commands and Agent setup instructions display the correct URLs.

For sub-path deployments, keep the public URL and runtime base path aligned in .env.release: set SKILLHUB_PUBLIC_BASE_URL=https://skill.example.com/skillhub, SKILLHUB_WEB_BASE_PATH=/skillhub/, and SKILLHUB_WEB_API_BASE_URL=/skillhub.

Manual deployment:

  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:

Start the runtime:

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

Then open:

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:

Recommended production baseline:

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:

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

For a configurable deployment with bundled PostgreSQL and Redis dependencies, use the Helm chart under charts/skillhub/:

helm dependency build ./charts/skillhub
helm upgrade --install skillhub ./charts/skillhub \
  --namespace skillhub \
  --create-namespace \
  -f values-production.yaml

See the Helm chart guide for required secrets, Ingress/TLS, external data services, storage migration, and upgrade constraints.

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

Local Compose and staging runs can keep using one backend URL. For an ingress deployment where the public URL exposes application APIs but keeps Actuator on the backend service, set a separate Actuator target:

ACTUATOR_BASE_URL=http://skillhub-server:8080 \
  ./scripts/smoke-test.sh https://skillhub.example.com

The health check requires an Actuator JSON response, so an HTML SPA fallback is reported as a routing or target error instead of a successful health response.

Admin label-management smoke checks run only when current admin credentials are supplied explicitly:

SMOKE_ADMIN_USERNAME=admin SMOKE_ADMIN_PASSWORD='current-password' \
  ./scripts/smoke-test.sh http://localhost:8080

Use SMOKE_ADMIN_CHECKS=false for persistent environments where only non-admin smoke checks should run. The script no longer falls back to bootstrap admin password defaults.

Architecture

┌─────────────┐     ┌─────────────┐     ┌──────────────┐
│   Web UI    │     │  CLI Tools  │     │  REST API    │
│  (React 19) │     │             │     │              │
└──────┬──────┘     └──────┬──────┘     └──────┬───────┘
       │                   │                   │
       └───────────────────┼───────────────────┘
                           │
                    ┌──────▼──────┐
                    │   Nginx     │
                    └──────┬──────┘
                           │
                    ┌──────▼──────┐
                    │ Spring Boot │  Auth · RBAC · Core Services
                    │   (Java 21) │  OAuth2 · API Tokens · Audit
                    └──────┬──────┘
                           │
              ┌────────────┼────────────┐
              │            │            │
       ┌──────▼───┐  ┌─────▼────┐  ┌────▼────┐
       │PostgreSQL│  │  Redis   │  │ Storage │
       │    16    │  │    7     │  │ S3/MinIO│
       └──────────┘  └──────────┘  └─────────┘

Backend (Spring Boot 3.2.3, Java 21):

Frontend (React 19, TypeScript, Vite):

SkillHub and the Agent Skills Ecosystem

SkillHub is a registry and governance platform — not a skill collection. It is complementary to open skill catalogs such as anthropics/skills: that repository popularized the Agent Skill format (a SKILL.md with name / description frontmatter plus supporting files) and ships a curated set of example skills. SkillHub is where your organization hosts, versions, governs, and distributes those skills privately.

anthropics/skills SkillHub
What it is A curated collection of example Agent Skills + the format spec A self-hosted registry & governance platform for skills
Layer Content — the skills themselves Infrastructure — hosting, versioning, discovery, access control
Hosting Public GitHub repository Your own infrastructure, behind your firewall
V

skillhub (iflytek/skillhub)

s3
Searching Database…

5.2K ·GitHub
Skillhub
What is this?SkillHub is a self-hosted, open-source agent skill registry that lets enterprises publish, version, and govern reusable agent skill packages behind their own firewall.
Is this a skill collection like anthropics/skills, or something different?No, SkillHub is infrastructure, not content: it is a registry and governance platform for hosting, versioning, and distributing Agent Skill packages privately, complementary to curated skill collections such as 'anthropics/skills'.
How do I get it running?Run the full local stack with `make dev-all`, or pull the published runtime images and deploy them with the provided curl-based installer script, passing --public-url for production use.
What do I need installed before running SkillHub?Docker and Docker Compose are the stated prerequisites for the CLI/registry stack; local backend development additionally needs Maven and Java 21.
Any gotchas when building or deploying it?Running `./mvnw -pl skillhub-app clean test` directly under server/ can pull stale artifacts and produce misleading errors, so use the make targets instead. The bootstrap admin also ships with a default password (ChangeMe!2026) that must be rotated before going to production.
Who is SkillHub built for?Enterprise and platform teams that want a private, governed registry for agent skills instead of relying on public skill repositories, with namespace ownership, review workflows, and audit logging.
Can I run this on Kubernetes, or only Docker?Both: SkillHub ships a Docker Compose stack for quick deployment plus basic Kubernetes manifests and a Helm chart bundling PostgreSQL/Redis for cluster deployments; published images target linux/amd64, arm64, and riscv64.
Does it keep proprietary skills private?Yes, it is built for on-premise hosting with full data sovereignty, and separate governance docs cover data categories, retention, portability, and incident handling for self-hosted instances.
What is the ClawHub compatibility layer for?It lets existing ClawHub-style registry clients talk to SkillHub, while SkillHub's native REST API and CLI remain the primary supported interface going forward.
What stack powers the backend and frontend?The backend runs Spring Boot 3.2.3 on Java 21 with PostgreSQL 16 and Redis; the frontend is React 19 with TypeScript, Vite, TanStack Router/Query, and Tailwind CSS/Radix UI.
How is skill package storage handled?Packages are stored on the local filesystem for development and in S3 or MinIO for production, swappable through config without code changes.
Can I monitor a running deployment?Yes, a bundled Prometheus + Grafana stack scrapes the backend's Actuator metrics endpoint for monitoring.
What are similar projects?casdoor, JeecgBoot, labtether, OpenBot, edict, clevis, paperclip, Clawith
Which topics is it in?ai-infrastructure, ai-governance, openclaw-skills, audit-log, s3, version-control, rbac, openclaw, agent-framework, redis, skill, skills
Creator
iflytek
Size
65.9 MB
Stars
5.2K
Updated
CommitOct 16Releasev0.2.22Oct 10
Age
7mo
Commits · 90 Days