SkillHub
An enterprise-grade, open-source agent skill registry β publish, discover, and manage reusable skill packages across your organization.
[](https://zread.ai/iflytek/skillhub)
[](./LICENSE)
[](https://github.com/iflytek/skillhub/actions/workflows/publish-images.yml)
[](https://ghcr.io/iflytek/skillhub)
[](https://openjdk.org/projects/jdk/21/)
[](https://react.dev)
---
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 β](https://zread.ai/iflytek/skillhub)**
## 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:
```bash
rm -rf /tmp/skillhub-runtime
curl -fsSL https://raw.githubusercontent.com/iflytek/skillhub/main/scripts/runtime.sh | sh -s -- up
```
Aliyun mirror shortcut:
```bash
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 edge
```
If deployment runs into problems, clear the existing runtime home and retry.
### Prerequisites
- Docker & Docker Compose
### Local Development
```bash
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.
The backend can bootstrap a local-login super admin for first-time access
when you explicitly set `BOOTSTRAP_ADMIN_ENABLED=true`:
- username: `BOOTSTRAP_ADMIN_USERNAME` (`admin` by default)
- password: `BOOTSTRAP_ADMIN_PASSWORD` (`ChangeMe!2026` by default)
Stop everything with:
```bash
make dev-all-down
```
Reset local dependencies and start from a clean slate with:
```bash
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](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:
```bash
make generate-api
```
For a stricter end-to-end drift check, run:
```bash
./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.
```bash
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:
```bash
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:
```bash
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. Bootstrap admin is disabled by default;
if you turn it on explicitly, the backend seeds 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_*`
- keep `BOOTSTRAP_ADMIN_ENABLED=false` unless you intentionally need bootstrap login
- 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/`](./monitoring).
It scrapes the backend's Actuator Prometheus endpoint.
Start it with:
```bash
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/`](./deploy/k8s):
- `configmap.yaml`
- `secret.yaml.example`
- `backend-deployment.yaml`
- `frontend-deployment.yaml`
- `services.yaml`
- `ingress.yaml`
Apply them after creating your own secret:
```bash
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`](./scripts/smoke-test.sh).
Run it against a local backend:
```bash
./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](https://github.com/openclaw/openclaw)
[openclaw](https://github.com/openclaw/openclaw) is an open-source agent skill CLI. Configure it to use your SkillHub endpoint as the registry:
```bash
# Log in to your SkillHub instance
openclaw login --registry https://
# Publish a skill
openclaw push
# Search and install skills
openclaw search
openclaw install /
```
### [AstronClaw](https://agent.xfyun.cn/astron-claw)
[AstronClaw](https://agent.xfyun.cn/astron-claw) 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](https://github.com/iflytek/astron-agent)
[astron-agent](https://github.com/iflytek/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**](https://github.com/iflytek/skillhub/discussions/categories/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`](./CONTRIBUTING.md)
- Code of conduct: [`CODE_OF_CONDUCT.md`](./CODE_OF_CONDUCT.md)
## π Support
- π¬ **Community Discussion**: [GitHub Discussions](https://github.com/iflytek/skillhub/discussions)
- π **Bug Reports**: [Issues](https://github.com/iflytek/skillhub/issues)
- π₯ **WeChat Work Group**:
## License
Apache License 2.0