mirror of
https://github.com/iflytek/skillhub.git
synced 2026-09-11 22:51:04 +00:00
346 lines
12 KiB
Markdown
346 lines
12 KiB
Markdown
<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">
|
|
|
|
[](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)
|
|
|
|
</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 →](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://<your-skillhub-host>
|
|
|
|
# Publish a skill
|
|
openclaw push <skill-package>
|
|
|
|
# Search and install skills
|
|
openclaw search <keyword>
|
|
openclaw install <namespace>/<skill>
|
|
```
|
|
|
|
### [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
|