SkillHub

企业级开源智能体技能注册中心 — 在组织内发布、发现和管理可复用的技能包

SkillHub 是一个自托管平台，为团队提供私有的、受治理的智能体技能共享空间。发布技能包，推送到命名空间，让其他人通过搜索发现或通过 CLI 安装。专为防火墙后的本地部署而构建，提供与公共注册中心相同的精致体验。

⭐ 如果 SkillHub 适合你的团队，欢迎 Star 本仓库帮助更多团队发现它；点 Watch → Custom → Releases 可在新版本发布时收到通知。

分享优秀 Skill

优秀的 Skill 在分享中产生更大价值。如果你有一个在真实工作或生活场景中反复打磨、确实好用的 Skill，欢迎分享给 SkillHub 社区，与大家一起丰富开放、实用的 Skill 生态。无论是日常生活、办公协作、学习研究、旅行活动、内容创作、数据分析还是软件开发，都可以成为有价值的分享。

经过验证的社区贡献还有机会进入精选 Skill 集合，让每个新部署的 SkillHub 开箱即用。不必完成全部适配后才能参与：你可以先创建 issue，说明 Skill 的来源和它解决的问题；也可以按照Skill 分享指南直接提交 PR。

文档

📖 用户指南 — 技能发布、搜索、CLI 使用等用户操作指南
🛠️ 开发者文档 — 架构设计、API 参考、本地开发、部署运维等技术文档
🐍 Python 示例 — 使用 REST API 在 Python 中搜索、下载和发布技能

核心特性

自托管与私有化 — 部署在您自己的基础设施上。将专有技能保留在防火墙后，完全掌控数据主权。一条 make dev-all 命令即可在本地运行。
发布与版本管理 — 上传智能体技能包，支持语义化版本控制、自定义标签（beta、stable）和自动 latest 跟踪。
发现 — 全文搜索，支持按命名空间、下载量、评分和时间筛选。可见性规则确保用户只能看到其有权访问的内容。
团队命名空间 — 在团队或全局范围下组织技能。每个命名空间拥有自己的成员、角色（Owner / Admin / Member）和发布策略。
审核与治理 — 团队管理员在其命名空间内审核；平台管理员控制向全局范围的推广。治理操作记录审计日志以满足合规要求。
社交功能 — 收藏技能、评分并跟踪下载量。围绕组织的最佳实践构建社区。
账户合并 — 将多个 OAuth 身份和 API 令牌整合到单个用户账户下。
API 令牌管理 — 为 CLI 和程序化访问生成作用域令牌，采用基于前缀的安全哈希。
CLI 优先 — 原生 REST API，加上对现有 ClawHub 风格注册中心客户端的兼容层。原生 CLI API 是主要支持路径，协议兼容性持续扩展中。
可插拔存储 — 开发环境使用本地文件系统，生产环境使用 S3 / MinIO。通过配置切换。
国际化 — 使用 i18next 支持多语言。

快速开始

使用以下命令启动完整的本地环境：

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

默认命令会拉取 latest 稳定版镜像；如果你想跟随 main 的最新构建，请显式传 --version edge。

配置公网访问地址（生产环境推荐）：

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

--public-url 参数用于设置 SkillHub 实例的公网访问地址。配置后：

CLI 安装命令会显示正确的注册中心地址
Agent 设置指引会显示正确的 skill.md URL
OAuth 回调和设备认证链接能正常工作

国内用户（阿里云镜像）：

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

如果部署遇到问题，请清除现有的运行时目录并重试。

前置要求

Docker & Docker Compose

访问应用

Web UI: http://localhost:3000
后端 API: http://localhost:8080

默认账户

默认执行 make dev-all 时，后端以 local profile 启动。在这个模式下，本地开发会保留下面两个模拟用户，同时默认创建一个可账号密码登录的 bootstrap 管理员：

local-user — 普通用户，用于发布和命名空间操作
local-admin — 超级管理员，用于审核和管理流程

在本地开发中使用 X-Mock-User-Id 请求头切换用户。本地 bootstrap 管理员默认已在 application-local.yml 中开启：

用户名：admin
密码：ChangeMe!2026
如需关闭，请在启动后端前设置环境变量 BOOTSTRAP_ADMIN_ENABLED=false

通过 runtime.sh 或 compose.release.yml 部署时，发布模板同样默认开启管理员，使用相同的默认账号密码（admin / ChangeMe!2026），零配置即可登录。 生产环境请务必修改密码——validate-release-config.sh 会拒绝默认值

停止服务

/tmp/skillhub-runtime/runtime.sh down

SkillHub CLI

通过命令行安装和管理 Agent 技能：

# 安装 CLI
npm install -g @astron-team/skillhub

# 或直接运行
npx @astron-team/skillhub@latest version

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

# 搜索和安装技能
skillhub search pdf
skillhub install pdf-parser --agent codex

# 查看已安装技能
skillhub list

📖 完整指南：docs/skillhub/guide/cli.md

开发

前置要求

Java 21+
Node.js 20+
Docker & Docker Compose
Make

启动开发环境

# 克隆仓库
git clone https://github.com/iflytek/skillhub.git
cd skillhub

# 启动完整的本地开发栈（后端 + 前端 + 依赖）
make dev-all

# 或者分别启动
make dev-backend    # 仅后端
make dev-web        # 仅前端

国内开发者：如果 Maven 依赖下载超时，需配置阿里云镜像。详见本地开发指南。

常用命令

make help                    # 显示所有可用命令
make test                    # 运行后端测试
make test-backend-app        # 运行 skillhub-app 及其依赖模块测试
make build-backend-app       # 构建 skillhub-app 及其依赖模块
make typecheck-web          # TypeScript 类型检查
make build-web              # 构建前端
make generate-api           # 重新生成 OpenAPI 类型
./scripts/check-openapi-generated.sh  # 验证 API 契约同步
./scripts/smoke-test.sh http://localhost:8080  # 运行冒烟测试

管理员标签管理冒烟测试只会在显式提供当前管理员凭证时运行：

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

持久化环境只跑非管理员冒烟检查时，可设置 SMOKE_ADMIN_CHECKS=false。脚本不再回退使用 bootstrap 管理员默认密码。

说明：不要在 server/ 下直接执行 ./mvnw -pl skillhub-app clean test。skillhub-app 依赖同仓库的 sibling modules，单独 clean 构建时会回退到本地 Maven 仓库里的旧产物并出现大量 cannot find symbol / 签名不匹配错误。需要使用 -am，或者直接使用上面的 make test-backend-app / make build-backend-app。

项目结构

skillhub/
├── server/                 # 后端（Java/Spring Boot）
│   ├── skillhub-app/      # 主应用程序
│   ├── skillhub-domain/   # 核心业务逻辑
│   ├── skillhub-auth/     # 认证授权
│   ├── skillhub-search/   # 搜索功能
│   ├── skillhub-storage/  # 存储层
│   └── skillhub-infra/    # 基础设施
├── web/                   # 前端（React/TypeScript）
├── docs/                  # 文档
├── scripts/               # 实用脚本
├── deploy/                # 部署配置
├── monitoring/            # Prometheus + Grafana
├── Makefile              # 常用任务
└── docker-compose.yml    # 本地开发栈

部署

使用 Docker Compose

# 默认（GHCR 镜像）
curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- up --public-url https://skillhub.your-company.com

# 阿里云镜像（国内推荐）
curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- up --aliyun --public-url https://skillhub.your-company.com --version latest

配置参数说明

参数	说明	示例
`--public-url <url>`	公网访问地址（推荐配置）	`--public-url https://skill.example.com`
`--version <tag>`	指定镜像版本	`--version v0.2.0`
`--aliyun`	使用阿里云镜像（国内推荐）	`--aliyun`
`--home <dir>`	指定运行时目录	`--home /opt/skillhub`
`--no-scanner`	禁用安全扫描服务	`--no-scanner`

重要：生产环境请务必配置 --public-url，确保 CLI 安装命令和 Agent 设置指引显示正确的地址。

如果通过 /skillhub/ 这类子路径对外发布，需要让公网地址和前端基础路径保持一致。请在 .env.release 中设置 SKILLHUB_PUBLIC_BASE_URL=https://skill.example.com/skillhub、 SKILLHUB_WEB_BASE_PATH=/skillhub/ 和 SKILLHUB_WEB_API_BASE_URL=/skillhub。

使用 Kubernetes

# 应用 Kubernetes 清单
kubectl apply -f deploy/k8s/

# 或使用 Helm Chart
helm dependency build ./charts/skillhub
helm upgrade --install skillhub ./charts/skillhub -n skillhub --create-namespace \
  -f values-production.yaml

环境变量

关键配置选项：

# 数据库
SPRING_DATASOURCE_URL=jdbc:postgresql://localhost:5432/skillhub
SPRING_DATASOURCE_USERNAME=skillhub
SPRING_DATASOURCE_PASSWORD=skillhub

# Redis
SPRING_DATA_REDIS_HOST=localhost
SPRING_DATA_REDIS_PORT=6379

# 存储（S3/MinIO）
STORAGE_TYPE=s3
STORAGE_S3_ENDPOINT=http://localhost:9000
STORAGE_S3_ACCESS_KEY=minioadmin
STORAGE_S3_SECRET_KEY=minioadmin
STORAGE_S3_BUCKET=skillhub

# 认证
AUTH_JWT_SECRET=your-secret-key
AUTH_SESSION_TIMEOUT=30m

完整配置参考请查看 application.yml。

上传白名单覆盖

技能包上传校验默认使用 SkillPackagePolicy.java 中的扩展名白名单。SkillPublishProperties 默认也会把这份列表作为 skillhub.publish.allowed-file-extensions 的值。

如果需要在运行时整体替换默认白名单，可以设置：

SKILLHUB_PUBLISH_ALLOWED_FILE_EXTENSIONS=.md,.json,.xsd,.xsl,.dtd,.docx,.xlsx,.pptx

Spring Boot 会把这个环境变量绑定到 skillhub.publish.allowed-file-extensions。一旦设置，该配置会替换默认白名单，而不是在默认列表后追加。

架构

SkillHub 采用清晰的分层架构：

表现层：REST API（Spring Boot）+ React 前端
应用层：用例编排和 DTO 转换
领域层：核心业务逻辑和实体
基础设施层：数据库、存储、搜索

关键设计决策：

多模块 Maven 项目：清晰的模块边界和依赖管理
领域驱动设计：丰富的领域模型和业务规则
CQRS 模式：读写分离以优化性能
事件溯源：审计日志和治理操作
可插拔存储：通过配置在本地/S3/MinIO 之间切换

详细架构文档请参阅 docs/ 目录。

技术栈

后端

语言：Java 21
框架：Spring Boot 3.2.3
数据库：PostgreSQL 16 + Flyway 迁移
缓存：Redis 7
存储：S3/MinIO
搜索：PostgreSQL 全文搜索

前端

语言：TypeScript
框架：React 19
构建工具：Vite
路由：TanStack Router
数据获取：TanStack Query
样式：Tailwind CSS + Radix UI
API 客户端：OpenAPI TypeScript（类型安全）
国际化：i18next

基础设施

容器化：Docker & Docker Compose
监控：Prometheus + Grafana
部署：Kubernetes 清单与 Helm Chart
CI/CD：GitHub Actions

路线图

核心技能注册功能
命名空间和团队管理
审核和治理工作流
全文搜索和筛选
社交功能（收藏、评分、下载）
API 令牌管理
账户合并
国际化支持
Helm Chart 部署
高级搜索过滤器
技能依赖管理
Webhook 集成
审计日志导出
LDAP/SAML 集成

完整路线图请参阅 docs/10-delivery-roadmap.md。

SkillHub 与 Agent Skills 生态

SkillHub 是一个注册与治理平台，而不是一个技能集合。它与 anthropics/skills 这类开放技能仓库是 互补关系：那个仓库推广了 Agent Skill 格式（带 name / description frontmatter 的 SKILL.md 加上配套文件），并提供了一批精选的示例技能；而 SkillHub 则是你的组织私有地托管、版本化、治理和分发这些技能的地方。

	`anthropics/skills`	SkillHub
定位	精选的示例 Agent Skills 集合 + 格式规范	自托管的技能注册与治理平台
层次	内容层 —— 技能本身	基础设施层 —— 托管、版本、发现、访问控制
托管	公开的 GitHub 仓库	你自己的基础设施，部署在防火墙之内
版本	Git 提交历史	语义化版本、标签（`beta` / `stable`）、`latest` 追踪
访问控制	公开	命名空间、RBAC、审核与审计日志
分发	克隆 / 拷贝文件	全文搜索 + CLI 安装

由于 SkillHub 使用同一套 SKILL.md 格式，anthropics/skills 中的技能——或任何 Agent Skill 目录——都可以直接发布到你的注册中心：

# 从开放集合中获取一个技能……
git clone https://github.com/anthropics/skills

# ……并将其发布到你的私有 SkillHub 注册中心
export SKILLHUB_REGISTRY=https://skillhub.your-company.com
export SKILLHUB_TOKEN=YOUR_API_TOKEN
npx @astron-team/skillhub@latest publish ./skills/<分类>/<技能名>

⚖️ 许可提示：转发布时请遵守每个技能各自的许可证。anthropics/skills 中大多数技能采用 Apache 2.0，但文档类技能（DOCX/PDF/PPTX/XLSX）是 source-available 而非开源，再分发前请先查看该技能的 LICENSE。

一句话总结：用 anthropics/skills 这类集合提供内容，用 SkillHub 在组织内进行受治理的分发。

与智能体平台集成

SkillHub 设计为与各种智能体平台和框架无缝集成。

OpenClaw

OpenClaw 是开源的智能体技能 CLI 工具。配置它使用您的 SkillHub 端点作为注册中心：

# 配置注册中心地址
export CLAWHUB_REGISTRY=https://skillhub.your-company.com

# 如需认证，先登录一次
clawhub login --token YOUR_API_TOKEN

# 搜索和安装技能
npx clawhub search email
npx clawhub install my-skill
npx clawhub install my-namespace--my-skill

# 发布请使用第一方 SkillHub CLI
export SKILLHUB_REGISTRY=https://skillhub.your-company.com
export SKILLHUB_TOKEN=YOUR_API_TOKEN
npx @astron-team/skillhub@latest publish ./my-skill --namespace my-space

其中 my-space--my-skill 是兼容层使用的 canonical slug，SkillHub 会将其解析为 namespace my-space 和 skill slug my-skill。

ClawHub 兼容范围包含搜索、查看和安装；其发布协议与 SkillHub 不兼容。发布请使用上面的第一方 CLI。

💡 提示：上述命令不仅适用于 OpenClaw，通过指定安装目录（--dir），也可适用于其他的 CLI Coding Agent 或 Agent 助手。例如：npx clawhub --dir ~/.claude/skills install my-skill

📖 完整 OpenClaw 集成指南 →

Hermes Agent

Hermes Agent 使用标准 SKILL.md 格式，并会递归发现 $HERMES_HOME/skills/ 中的技能。通过 SkillHub CLI 的 --dir 参数即可把完整技能包安装到 Hermes，无需新增 registry 适配器；安装后可使用 hermes skills list 验证。

📖 完整 Hermes Agent 集成指南 →

HarnessClaw Engine

HarnessClaw Engine 是基于 Go 的 LLM 编程助手引擎，通过 WebSocket 协议对外提供能力。它从 SKILL.md 文件加载技能，支持 YAML frontmatter 与参数替换，并按配置顺序扫描各目录下的 skill-name/SKILL.md（默认 ~/.harnessclaw/workspace/skills/，靠前的目录在重名时优先）。通过 SkillHub CLI 的 --dir 参数即可把技能包直接安装到该目录，无需新增 registry 适配器：

npx clawhub --dir ~/.harnessclaw/workspace/skills install my-skill

贡献

欢迎贡献。请先开启 issue 讨论您想要更改的内容。

贡献指南：CONTRIBUTING.md
行为准则：CODE_OF_CONDUCT.md

📞 支持

💬 社区讨论：GitHub Discussions
🐛 Bug 报告：Issues
👾 Discord：加入我们的服务器
👥 企业微信群：

许可证

Apache License 2.0

SkillHub

分享优秀 Skill

文档

核心特性

快速开始

前置要求

访问应用

默认账户

停止服务

SkillHub CLI

开发

前置要求

启动开发环境

常用命令

项目结构

部署

使用 Docker Compose

配置参数说明

使用 Kubernetes

环境变量

上传白名单覆盖

架构

技术栈

后端

前端

基础设施

路线图

SkillHub 与 Agent Skills 生态

与智能体平台集成

OpenClaw

Hermes Agent

HarnessClaw Engine

AstronClaw

Loomy

astron-agent

相关项目

贡献

📞 支持

许可证