SkillHub

What It Does

SkillHub is a self-hosted registry platform for AI agent skills, built by iFlytek (China's leading AI company). It provides a REST API backend (Spring Boot, Java 21), a React 19 web UI, a security scanner, a CLI tool for publishing and installing skills, and Kustomize-based Kubernetes manifests for production deployment. Teams publish skill packages under namespaces with semantic versioning, and governance flows (review, approval, audit logging) control what gets distributed. The platform targets enterprises that need to keep proprietary skills behind their firewall while giving internal teams a polished discovery and install experience.

The repository also includes 8 internal SKILL.md files under .agents/skills/ that teach contributing agents about the codebase conventions, backend module structure, API design, skill lifecycle state machine, frontend conventions, testing/CI, PR submission, and dev workflow. A 599-line AGENTS.md file provides the full directory map, quick reference table, and architecture context.

The Good

CLI installs in seconds and works as advertised. Running npm install -g @astron-team/skillhub completed without errors in a clean sandbox (Node 20.19.4, npm 9.2.0). The skillhub version command reported SkillHub CLI 0.1.6. All documented subcommands (search, install, list, publish, login, whoami, logout, doctor, remove) appear in --help output. The CLI's error handling is clean: pointing skillhub search at a nonexistent registry produced Error: registry unreachable with context and a suggested next step, not a stack trace.

The codebase is serious, not a weekend project. The server side is a 7-module Maven project (skillhub-app, skillhub-domain, skillhub-auth, skillhub-search, skillhub-storage, skillhub-infra, skillhub-notification) with 775 Java files. The domain layer uses clean architecture patterns: entities, domain services, and domain events are separated from the application and infrastructure layers. The frontend has 537 TypeScript/TSX files with TanStack Router, TanStack Query, and OpenAPI-generated types checked into the repository at web/src/api/generated/schema.d.ts. The design docs folder contains 74 markdown files covering everything from authentication design to parallel workflow to SMTP password reset setup.

Internal SKILL.md files show the project eats its own dog food. All 8 SKILL.md files under .agents/skills/ have proper YAML frontmatter with name, description, and license fields. The skill-lifecycle skill, at roughly 150 lines, documents a complete state machine: container states (ACTIVE/HIDDEN/ARCHIVED), version states (DRAFT/SCANNING/SCAN_FAILED/UPLOADED/PENDING_REVIEW/PUBLISHED/REJECTED/YANKED), review task states, visibility rules, permission boundaries, domain events, and common pitfalls. This is the kind of internal documentation that makes a codebase maintainable.

The Bad

Operational complexity is high. Running the full stack requires PostgreSQL 16, Redis 7, Java 21, a container runtime, and optionally S3/MinIO for storage. The quick-start command (curl -fsSL ... | sh -s -- up) pulls Docker images, but the prerequisite list is still heavyweight for small teams or solo developers who just want a private skill registry. There is no lightweight single-binary mode or embedded database option.

The CLI subcommand coverage is narrower than the README implies. The README mentions skillhub list and skillhub install pdf-parser --agent codex, but the actual --help output shows a more limited set: version, update, login, logout, whoami, search, install, list, remove, doctor, and publish. There is no skillhub info, skillhub star, or skillhub namespace command yet, even though the web UI supports namespaces, starring, and ratings. The CLI is at v0.1.6, so this is expected, but the README does not clearly flag the gap.

Default admin password is committed to documentation. The bootstrap admin account uses admin / ChangeMe!2026 as the default credentials. The README does note that validate-release-config.sh rejects this password and recommends changing it, but the credential pair appears in at least three places (README, AGENTS.md, and the runtime script). For an enterprise product, this is a minor security hygiene concern.

Smoke Test Results

We ran three sandboxed test passes in clean Linux sandboxes (ubuntu 24.04, aarch64).

Run A. Fresh sandbox, no deps preinstalled

$ node --version
✅ PASS: Node.js is available (v20.19.4)

$ npm --version
✅ PASS: npm is available (9.2.0)

$ npm install -g @astron-team/skillhub
✅ PASS: npm install -g @astron-team/skillhub

$ skillhub version
SkillHub CLI 0.1.6
✅ PASS: skillhub version ran

$ skillhub --help
✅ PASS: skillhub --help ran

$ skillhub search test --registry https://nonexistent.invalid 2>&1 | head -3
Error: registry unreachable
✅ PASS: skillhub search produced output (expected connection error)

$ git clone --depth 1 https://github.com/iflytek/skillhub.git /tmp/skillhub-struct
✅ PASS: git clone succeeded

$ test -f AGENTS.md
✅ PASS: AGENTS.md exists

$ find . -name SKILL.md | wc -l
8
✅ PASS: Found 8 SKILL.md files (expected >= 8)

$ test -d cli/src && test -d server && test -f docker-compose.yml && test -f Makefile
✅ PASS: CLI source, server source, docker-compose, Makefile all present

$ test -d docs && test -f scripts/smoke-test.sh && test -f LICENSE
✅ PASS: docs, smoke-test.sh, LICENSE all present

Pass rate: 17 of 17. Everything installs and validates cleanly from a fresh sandbox.

Full sandbox log

Run B. Sandbox with deps preinstalled

$ npm install -g @astron-team/skillhub
✅ PASS: CLI install with preinstalled deps

$ skillhub version
SkillHub CLI 0.1.6
✅ PASS: skillhub version

$ skillhub --help (checking for subcommands)
✅ PASS: skillhub has 'search' subcommand
✅ PASS: skillhub has 'install' subcommand
✅ PASS: skillhub has 'list' subcommand
✅ PASS: skillhub has 'publish' subcommand
✅ PASS: skillhub has 'login' subcommand

$ docker --version
Docker version 29.4.3
✅ PASS: Docker is available

$ ls server/skillhub-*/ | wc -l
7 modules
✅ PASS: Found 7 Maven modules (expected >= 7)

$ test -d web/src && test -d web/src/features && test -f web/src/api/generated/schema.d.ts
✅ PASS: web/src/, web/src/features/, schema.d.ts all present

$ wc -l AGENTS.md
599 lines
✅ PASS: AGENTS.md is substantial (599 lines)

$ find . -name '*.java' | wc -l
775 Java files
✅ PASS: Substantial Java codebase (775 files)

$ SKILL.md files with YAML frontmatter: 8
✅ PASS: 8 SKILL.md files have frontmatter (expected >= 8)

$ find docs/ -name '*.md' | wc -l
74 doc files
✅ PASS: 74 design docs (expected >= 15)

Pass rate: 16 of 16. All structural checks pass with deps preinstalled.

Full sandbox log

Run C. Functional verification (does it do what it claims?)

$ skillhub version 2>&1
SkillHub CLI 0.1.6
✅ PASS: version output contains semver

$ skillhub --help (checking all expected commands)
✅ PASS: 'search' command present
✅ PASS: 'install' command present
✅ PASS: 'list' command present
✅ PASS: 'publish' command present
✅ PASS: 'login' command present
✅ PASS: 'version' command present

$ skillhub search pdf --registry https://skill.xfyun.cn 2>&1 | head -10
Error: registry unreachable
✅ PASS: search produced output (even if error, CLI handled it)

$ which skillhub
/usr/local/share/npm-global/bin/skillhub
✅ PASS: CLI binary located

Functional pass rate: 9 of 9. The CLI installs, runs, and handles errors gracefully. The public registry (skill.xfyun.cn) was unreachable from the sandbox, so we could not verify actual search results or skill installation end-to-end.

Full functional log

What the runs tell you

The CLI is polished and installable in under 10 seconds on a clean machine. All structural claims (7 Maven modules, 775 Java files, 8 SKILL.md files, 599-line AGENTS.md) checked out. The full server stack could not be validated in the sandbox because it needs PostgreSQL, Redis, and Java 21, but the CLI and project structure are solid.

Setup Walkthrough

1. Install the CLI:

npm install -g @astron-team/skillhub

This installs the skillhub binary globally. Version 0.1.6 at time of testing.

1. Verify the install:

skillhub version
# SkillHub CLI 0.1.6

1. Point the CLI at your registry:

skillhub login --token sk_xxx --registry https://skillhub.your-company.com

1. Search and install skills:

skillhub search pdf
skillhub install pdf-parser --agent codex

1. Deploy the full stack (requires Docker):

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

For China-based teams, append --aliyun to use Aliyun mirrors. The stack includes PostgreSQL, Redis, the Spring Boot backend, the React frontend, and an optional security scanner.

1. For Kubernetes deployment, apply the Kustomize manifests under deploy/k8s/:

kubectl apply -k deploy/k8s/base/

Post-install gotcha: the default bootstrap admin password (ChangeMe!2026) must be changed before production use. The included validate-release-config.sh script rejects it.

Alternatives

1. npm as a skill registry - If your skills are already JavaScript packages, publishing to npm (or a private npm registry like Verdaccio) gives you versioning, namespacing, and CLI tooling without the operational overhead of a full SkillHub deployment.
2. sickn33/antigravity-awesome-skills - A 1,400+ skill library with an installer CLI. Not a registry (no RBAC, no review workflows, no on-premise hosting), but useful for discovering and installing public skills quickly.
3. Verdaccio - A lightweight, self-hosted npm proxy registry. Simpler than SkillHub (Node.js only, no Java/PostgreSQL/Redis), but lacks skill-specific features like security scanning, governance workflows, and the SKILL.md lifecycle model.