SkillHub

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

---

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: curl -fsSL https://raw.githubusercontent.com/iflytek/skillhub/main/scripts/runtime.sh | sh -s -- up

Prerequisites

• Docker & Docker Compose

Local Development

make dev-all

Then open:

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

Local profile seeds two mock-auth users automatically:

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

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.

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

Use the bundled Aliyun mirror shortcut when a nearer registry is configured:

curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- up --aliyun --version edge

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. Instead, the backend bootstraps a local admin account from environment variables for the first login:

• username: BOOTSTRAP_ADMIN_USERNAME
• password: BOOTSTRAP_ADMIN_PASSWORD

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_*
• 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.

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) │     │             │     │              │
└──────┬──────┘     └──────┬──────┘     └──────┬───────┘
       │                   │                   │
       └───────────────────┼───────────────────┘
                           │
                    ┌──────▼──────┐
                    │   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):

• Multi-module Maven project with clean architecture
• Modules: app, domain, auth, search, storage, infra
• PostgreSQL 16 with Flyway migrations
• Redis for session management
• S3/MinIO for skill package storage

Frontend (React 19, TypeScript, Vite):

• TanStack Router for routing
• TanStack Query for data fetching
• Tailwind CSS + Radix UI for styling
• OpenAPI TypeScript for type-safe API client
• i18next for internationalization

Usage with Agent Platforms

SkillHub works as a skill registry backend for several agent platforms. Point any of the clients below at your SkillHub instance to publish, discover, and install skills.

openclaw

openclaw is an open-source agent skill CLI. Configure it to use your SkillHub endpoint as the registry:

# Log in to your SkillHub instance
openclaw login --registry https://<your-skillhub-host>

# Publish a skill
openclaw push <skill-package>

# Search and install skills
openclaw search <keyword>
openclaw install <namespace>/<skill>

AstronClaw

AstronClaw is the skill marketplace provided by iFlytek's Astron platform. You can connect it to a self-hosted SkillHub registry to manage and distribute private skills within your organization, or browse publicly shared skills on the Astron platform.

astron-agent

astron-agent is the iFlytek Astron agent framework. Skills stored in SkillHub can be referenced and loaded directly by astron-agent, enabling a governed, versioned skill lifecycle from development to production.

---

🌟 Show & Tell — Have you built something with SkillHub? We'd love to hear about it! Share your use case, integration, or deployment story in the Discussions → Show and Tell category.

Contributing

Contributions are welcome. Please open an issue first to discuss what you'd like to change.

• Contribution guide: CONTRIBUTING.md
• Code of conduct: CODE_OF_CONDUCT.md

License

Apache License 2.0