SkillHub – 企业级自托管智能体技能仓库

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

• 📖 Full Documentation →

---

✨ 核心特性

自托管与隐私保护

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 管理

API Token Management — Generate scoped tokens for CLI and programmatic access with prefix-based secure hashing.

CLI 优先

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.

---

🚀 快速开始

官方镜像

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.

本地开发

Docker & Docker Compose

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 类型生成

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.

---

📦 运行时部署

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

---

📄 技能包验证

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.

---

📊 监控栈

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

---

🧪 冒烟测试

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

---

🏗 技术架构

┌─────────────┐ ┌─────────────┐ ┌──────────────┐
│   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

---

🔗 平台集成

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:

# Configure registry URL
export CLAWHUB_REGISTRY=https://skillhub.your-company.com

# Authenticate once if needed
clawhub login --token YOUR_API_TOKEN

# Search and install skills
npx clawhub search email
npx clawhub install my-skill
npx clawhub install my-namespace--my-skill

# Publish a skill
npx clawhub publish ./my-skill

💡 Tip: The above commands are not only applicable to OpenClaw, but also to other CLI Coding Agents or Agent assistants by specifying the installation directory (–dir). For example:

npx clawhub --dir ~/.claude/skills install my-skill

📖 Complete OpenClaw Integration Guide →

AstronClaw 集成

AstronClaw is a cloud AI assistant built on OpenClaw’s core capabilities, providing 24/7 online service through enterprise platforms like WeChat Work, DingTalk, and Feishu. It features a built-in skill system with over 130 official skills. You can connect it to a self-hosted SkillHub registry to enable one-click skill installation, search repository, dialogue-based automatic installation, and even custom skills management within your organization.

Loomy 集成

Loomy is a desktop AI work partner focusing on real office scenarios. It integrates deeply with local files and system tools to build efficient automated workflows for individuals and small teams. By connecting Loomy to your SkillHub registry, you can easily discover and install organization-specific skills to enhance your local desktop automation and productivity.

astron-agent 集成

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

---

🤝 贡献指南

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
• 💬 Community Discussion: GitHub Discussions
• 🐛 Bug Reports: Issues
• 👥 WeChat Work Group: https://github.com/iflytek/astron-agent/raw/main/docs/imgs/WeCom_Group.png

---

📄 许可证

Apache License 2.0

---

原文来源：https://github.com/iflytek/skillhub