SkillHub: a self-hosted skill registry for enterprise agents

The problem SkillHub solves, and for whom

Once more than one team writes agent skills, distribution becomes an operations problem. A skill is a package: instructions, tool definitions, sometimes scripts. Teams copy them through chat, paste them into wikis, or keep them in a Git repository that has no notion of a version, an owner, or who is allowed to install what. The README frames SkillHub as "a private, governed place to share agent skills": publish a package to a namespace, and other people find it through search or install it with a CLI. The audience is an organization that already runs agents and wants the same controls it applies to internal packages. The repository is written in Java and licensed under Apache-2.0, so it fits shops that already run a JVM service and a Postgres database. It is not aimed at an individual developer who wants to download a skill from a public marketplace; the project's own homepage is a hosted instance, but the code is built for on-premise deployment. The README states the goal directly: keep proprietary skills behind your firewall with full data sovereignty.

Namespaces, versions and the governance model

The unit of organization is the namespace, which can be scoped to a team or to the global scope. Each namespace carries its own members and three roles: Owner, Admin and Member. Publishing policies live at that level too. Review follows the same hierarchy. Team admins review submissions inside their namespace, while platform admins gate promotion of a skill to the global scope. The README says governance actions are audit-logged, which is the feature that separates this from a plain package index: when someone approves a skill or changes a role, there is a record. Packages themselves are versioned with semantic versioning, custom tags such as beta or stable, and automatic latest tracking. Discovery is full-text search with filters for namespace, downloads, ratings and recency, and visibility rules restrict results to what the caller is authorized to see. That last point matters more than it looks. Search that ignores permissions leaks the existence and names of skills across teams, and the README explicitly claims visibility rules are enforced. Social features (stars, ratings, download counts) sit on top, which is a deliberate choice: the project wants internal skills to accumulate reputation the way public packages do.

What the deployment actually consists of

The repository exposes its topology in docker-compose.yml rather than hiding it behind a single image. The stack is four backing services plus the application: Postgres 16 (database skillhub, user skillhub), Redis 7 for caching or coordination, MinIO as the S3-compatible object store, and a separate skill-scanner service built from ./scanner that listens on port 8000 and exposes a /health endpoint. The scanner takes three environment variables, SKILL_SCANNER_LLM_API_KEY, SKILL_SCANNER_LLM_BASE_URL and SKILL_SCANNER_LLM_MODEL, which indicates it calls an LLM to inspect uploaded packages. That is an interesting design decision: content inspection is delegated to a model endpoint you supply, so the scanner is only as good as the model behind it, and it adds an external dependency to an otherwise self-contained deployment. The Makefile confirms how the pieces are wired for development. SKILLHUB_SECURITY_SCANNER_ENABLED, SKILLHUB_SECURITY_SCANNER_URL and SKILLHUB_SECURITY_SCANNER_MODE (set to upload) are passed to the backend, so scanning can be turned off entirely. Storage is pluggable: local filesystem for development, S3 or MinIO for production, swapped by configuration. The web UI runs on port 3000, the backend API on 8080, and Helm charts under charts/ cover Kubernetes.

Installing SkillHub and publishing a first skill

The README's quick start does not ask you to clone the repository. It pipes a hosted script into a shell, which is fast and also the first thing a security reviewer will object to. The command below starts the full local stack and pulls the latest stable release images.

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

The README notes you can pass --version edge to get the newest build from main instead of the stable release. For a real deployment, set the public URL, because the CLI install commands, the agent setup instructions and OAuth callbacks all derive from it.

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

There is an Aliyun mirror variant for users in China that adds --aliyun. If the deployment fails, the README's advice is to clear the runtime home and retry. The client side is an npm package, not a Java artifact.

npm install -g @astron-team/skillhub
skillhub login --token sk_xxx --registry https://skill.xfyun.cn
skillhub search pdf
skillhub install pdf-parser --agent codex

After login, search returns matching skills from the registry and install places the chosen package for the named agent. The README points to docs/skillhub/en/guide/cli.md for the full command set. If you prefer to work from source, the prerequisites are Docker and Docker Compose, and make dev-all starts the backend with the local profile, bringing up the web UI on http://localhost:3000 and the API on http://localhost:8080.

Where the design creates friction

The scanner is the weakest link in the story. It needs an LLM endpoint, and the compose file defaults all three SKILL_SCANNER_LLM_* variables to empty strings. Nothing in the README explains what the scanner does when those are unset, whether uploads are rejected or pass through unchecked. If you enable SKILLHUB_SECURITY_SCANNER_MODE=upload without a working model endpoint, you may believe packages are being inspected when they are not. The second constraint is storage. Skills live in MinIO or S3, and the compose defaults are minioadmin/minioadmin with Postgres credentials of skillhub/skillhub_dev. Those are development values, but they are the ones in the repository, so any production deployment has to replace them deliberately. Third, the CLI compatibility layer deserves caution: the README says native CLI APIs are the primary supported path while protocol compatibility with ClawHub-style clients "continues to expand", which is a polite way of saying the compatibility surface is incomplete. Finally, the install path itself. Piping a remote script into sh, and running rm -rf on a runtime directory first, is convenient for a demo and awkward to defend in a change-management process. The repository does provide docker-compose.yml, compose.release.yml and Helm charts, so building your own deployment path from those files is possible, but the README documents the script as the supported quick start.

How it differs from a Git repository or a public marketplace

The obvious alternative is a Git repository of skill folders. Git gives you versioning, review through pull requests, and access control through repository permissions. What it does not give you is a searchable catalog with per-skill metadata, download counts, or a CLI that installs a package into a specific agent by name. It also does not give you audit logs scoped to skill promotion decisions, or a distinction between a team namespace and a global scope. If your organization has five skills and one team, Git wins on operational cost: no Postgres, no Redis, no object store, no scanner. SkillHub starts to pay off when the number of skills and consumers grows past the point where a README index is enough. The other comparison is a public registry such as the one behind the project's own homepage or ClawHub. Those are hosted, they are outside your firewall, and you do not control retention or visibility. SkillHub's pitch is the opposite trade: you operate the infrastructure, and in exchange the data stays inside your network. The README's own governance documents, docs/PRIVACY_AND_DATA_GOVERNANCE.md and docs/CONTENT_SAFETY.md, spell out that split between public and self-hosted instances.

Maintenance, upgrades and the licence

The repository is not archived, and the last push was on 2026-08-21, the same day as release v0.2.17. The two prior releases, v0.2.16 and v0.2.15, landed on 2026-08-07 and 2026-07-30, so the project has been cutting releases roughly every one to two weeks through that window. That cadence is a real maintenance cost for operators: the quick start pulls latest by default, which means a restart can move you across several versions. The README offers --version edge for main builds and --version latest for the stable line, and there is a .env.release.example plus a validate-release-config make target, so pinning is possible, but you have to do it explicitly. Upgrading a self-hosted service also means migrating Postgres, and the README does not describe a rollback procedure or a downgrade path. The licence is Apache-2.0, which permits commercial and internal use and requires that you keep the licence and notice files; the repository's LICENSE file is the authoritative text. That is a permissive licence, and it does not oblige you to publish modifications. It also provides no warranty, so the compliance burden for what your agents do with installed skills stays with your organization, which is why the privacy and content-safety documents exist.

Editorial conclusion

Adopt SkillHub if you have to distribute agent skills across several teams and need per-namespace roles plus audit-logged governance, and if you can run Postgres, Redis and an S3-compatible store. Do not adopt it if a single team shares skills through a repository, or if your skills contain secrets that cannot be stored in an object bucket. Before rolling it out, verify the --public-url setting against your real hostname, confirm which storage backend the production profile selects, and check the scanner configuration if SKILLHUB_SECURITY_SCANNER_MODE is set to upload.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes