ClawHub: The Complete Guide to the Public Skill Registry for AI Agents
The rise of autonomous AI agents has created a new challenge: how do you share, discover, and manage the capabilities these agents can use? Just as npm revolutionized JavaScript package management and Docker Hub standardized container distribution, ClawHub is emerging as the definitive skill registry for the AI agent ecosystem.
Built as the official marketplace for OpenClaw — the open-source, self-hosted AI agent platform — ClawHub lets developers publish, version, search, and install text-based agent skills through a polished web interface and a powerful CLI. With 5,200+ GitHub stars, 832 forks, and 72 contributors, it has rapidly become the largest community-driven skill registry in the agent space.
In this comprehensive guide, we'll explore everything you need to know about ClawHub: its architecture, CLI workflows, security considerations, the SKILL.md format, and how it compares to alternative registries.
What Is ClawHub?
ClawHub is the public skill directory for Clawdbot (the AI agent at the core of OpenClaw). A "skill" in this context is a SKILL.md file plus optional supporting text files that define what an agent can do — from searching the web and managing Git repositories to automating email and controlling IoT devices.
Think of it this way:
| Analogy | Package Manager | Registry |
|---|---|---|
| JavaScript | npm CLI | npmjs.com |
| Python | pip | PyPI |
| Containers | docker CLI | Docker Hub |
| AI Skills | clawhub CLI | clawhub.ai |
The registry is accessible at clawhub.ai and provides:
- Browsing & rendering of SKILL.md files with full Markdown support
- Semantic vector search powered by OpenAI embeddings (
text-embedding-3-small), so you can find skills with natural language queries instead of exact keyword matches - Versioning with changelogs, semver, and tags (including
latest) - Stars & comments for community curation
- Moderation hooks for admins and moderators to approve, hide, or ban skills
- SOUL.md registry via onlycrabs.ai — a sister registry for "system lore" that defines how an agent behaves (as opposed to what it can do)
Key Project Stats
| Metric | Value |
|---|---|
| GitHub Stars | 5,200+ |
| Forks | 832 |
| Contributors | 72 |
| Language | TypeScript |
| License | MIT |
| Created | January 2026 |
| Last Updated | March 2026 |
| Topics | directory, skill |
Architecture & Tech Stack
ClawHub is built on a modern, full-stack TypeScript architecture:
Web Application
- Framework: TanStack Start (React + Vite/Nitro)
- Rendering: Server-side rendering (SSR) with Vite for development and Nitro for production builds
Backend
- Database & File Storage: Convex — a reactive backend that handles the DB, file storage, and HTTP actions
- Authentication: Convex Auth with GitHub OAuth
- Search: OpenAI embeddings (
text-embedding-3-small) combined with Convex vector search for semantic skill discovery
Shared Packages
packages/schema(clawhub-schema): Shared API types and route definitions used by both the web app and the CLI
Repository Layout
src/ → TanStack Start app (routes, components, styles)
convex/ → Schema, queries, mutations, actions, HTTP API routes
packages/schema/ → Shared API types/routes for CLI and app
docs/ → Project documentation (architecture, CLI, auth, deployment)
This architecture provides several advantages: real-time reactivity through Convex subscriptions, type-safe API contracts via the shared schema package, and blazing-fast search through vector embeddings rather than brittle keyword matching.
The SKILL.md Format
At the heart of ClawHub is the SKILL.md file — a Markdown document with YAML frontmatter that declares everything an agent needs to know about a skill:
---
name: my-skill
description: Does a thing with an API.
metadata:
openclaw:
requires:
env:
- MY_API_KEY
bins:
- curl
primaryEnv: MY_API_KEY
---
# My Skill
Instructions for the agent go here...
Frontmatter Fields
| Field | Purpose |
|---|---|
name | Human-readable skill name |
description | Brief summary of what the skill does |
metadata.openclaw.requires.env | Required environment variables |
metadata.openclaw.requires.bins | Required system binaries |
metadata.openclaw.primaryEnv | The main API key needed |
The body of the SKILL.md contains natural language instructions that tell the agent how to use the skill. This is what makes the format powerful — skills are essentially prompt engineering documents that any LLM-powered agent can interpret.
Nix Plugin Support
For more complex skills that bundle CLI binaries alongside their instructions, ClawHub supports Nix plugin pointers in the frontmatter:
---
name: peekaboo
description: Capture and automate macOS UI with the Peekaboo CLI.
metadata:
clawdbot:
nix:
plugin: "github:clawdbot/nix-steipete-tools?dir=tools/peekaboo"
systems: ["aarch64-darwin"]
---
This allows a skill to declare its Nix package bundle, configuration requirements, and even include CLI help output — making the installation experience seamless for developers using nix-clawdbot.
Security Analysis
ClawHub's backend performs security analysis on skill metadata declarations, checking that the runtime requirements (env vars, binaries, install specs) declared in the frontmatter match the actual skill behavior. This adds a layer of protection against skills that might request more access than they need.
CLI: The Complete Command Reference
The ClawHub CLI is the primary way developers interact with the registry from the terminal. Here is a comprehensive overview of every command:
Authentication
# Browser-based login (opens clawhub.ai/cli/auth)
clawhub login
# Headless/CI login with a token
clawhub login --token clh_...
# Check your identity
clawhub whoami
Discovery
# Semantic search (natural language!)
clawhub search "calendar management"
# Browse latest skills
clawhub explore
clawhub explore --sort trending --limit 50
# Inspect a skill without installing
clawhub inspect my-skill
clawhub inspect my-skill --versions # Version history
clawhub inspect my-skill --files # List files
clawhub inspect my-skill --file SKILL.md # View a file
The explore command supports multiple sort modes: newest, downloads, rating, installs, installsAllTime, and trending. Output is in a human-friendly table format by default, with --json available for machine consumption.
Installation & Management
# Install the latest version of a skill
clawhub install my-skill
# Install into a custom directory
clawhub install my-skill --workdir /tmp/demo --dir skills
# List installed skills
clawhub list
# Update a specific skill or all skills
clawhub update my-skill
clawhub update --all
# Uninstall (local removal only)
clawhub uninstall my-skill
When you install a skill, ClawHub resolves the latest version via its API, downloads a zip archive, and extracts it into your workspace. It writes lock files (.clawhub/lock.json) and origin metadata (.clawhub/origin.json) for tracking.
Publishing
# Publish a new skill version
clawhub publish ./my-skill \
--slug my-unique-skill \
--name "My Skill" \
--version 1.0.0 \
--tags latest \
--changelog "Initial release"
Important: Publishing a skill means it is released under the MIT-0 license on ClawHub. Published skills are free to use, modify, and redistribute without attribution.
Sync (Batch Publish)
# Scan for local skill folders and publish new/changed ones
clawhub sync
# Dry run (preview only)
clawhub sync --all --dry-run --no-input
# Control concurrency and versioning
clawhub sync --bump minor --concurrency 8
The sync command is particularly powerful for developers managing multiple skills. It automatically discovers skill folders (including Clawdbot workspace skills), compares them with the registry, and publishes any new or updated ones.
Moderation
# Soft-delete a skill (owner, moderator, or admin)
clawhub delete my-skill
# Restore a soft-deleted skill
clawhub undelete my-skill
# Transfer ownership
clawhub transfer request my-skill target-user
clawhub transfer accept my-skill
# Ban a user (admin only)
clawhub ban-user malicious-user --reason "Malware distribution"
# Change user role (admin only)
clawhub set-role username moderator
Getting Started: Local Development Setup
Setting up a local ClawHub development environment requires Bun as the JavaScript runtime:
Step 1: Clone and Install
git clone https://github.com/openclaw/clawhub.git
cd clawhub
bun install
Step 2: Configure Environment
cp .env.local.example .env.local
Edit .env.local with the following required variables:
| Variable | Purpose |
|---|---|
VITE_CONVEX_URL | Convex deployment URL |
VITE_CONVEX_SITE_URL | Convex site URL |
AUTH_GITHUB_ID | GitHub OAuth App ID |
AUTH_GITHUB_SECRET | GitHub OAuth App Secret |
JWT_PRIVATE_KEY | Convex Auth JWT key |
JWKS | Convex Auth JWKS |
OPENAI_API_KEY | For embeddings and search |
Step 3: Start Development Servers
# Terminal A: Local Convex backend
bunx convex dev
# Terminal B: Web app (port 3000)
bun run dev
# Optional: Seed sample data
bunx convex run --no-push devSeed:seedNixSkills
Step 4: Test the CLI
bun clawhub --help
bun clawhub login
bun clawhub search gif --limit 5
For detailed setup instructions including GitHub OAuth configuration, JWT key generation, and database seeding, refer to the CONTRIBUTING.md.
Security: Understanding the Risks and Mitigations
Security is the most discussed topic in the ClawHub ecosystem, and for good reason. Because skills are executable instructions that run with the agent's permissions, a malicious skill can potentially access sensitive files, environment variables, and system resources.
Known Risks
Community reports and security analyses have identified several risk vectors:
- Supply-chain attacks: Skills can request access to environment variables, download external scripts, or execute system commands. Some malicious skills have been reported to contain obfuscated base64-encoded commands or instructions to download malware from external URLs.
- Delegated compromise: Because skills run with the same permissions as the agent itself, a compromised skill effectively gains access to everything the agent can access.
- Social engineering: Skills with attractive names or high download counts are not necessarily safe. Reports suggest some popular skills have contained malicious payloads.
Mitigations
ClawHub and the OpenClaw ecosystem have implemented several security measures:
-
VirusTotal Integration: OpenClaw has partnered with VirusTotal to scan all published skills. VirusTotal's Code Insight capability performs security-focused analysis of skill packages, flagging suspicious content and blocking known malware.
-
Metadata Validation: ClawHub's security analysis checks that declared runtime requirements (env vars, binaries) match actual skill behavior.
-
Soft-Delete & Moderation: Admins and moderators can quickly hide or remove problematic skills using
clawhub deleteandclawhub ban-user. -
Telemetry Controls: ClawHub tracks minimal install telemetry for computing install counts, but this can be disabled:
export CLAWHUB_DISABLE_TELEMETRY=1
Best Practices for Users
| Practice | Details |
|---|---|
| Review SKILL.md | Always read the full skill file before installing |
| Check for red flags | Watch for base64-encoded content, external downloads, excessive env var requirements |
| Use sandboxed workspaces | Run untrusted skills in isolated environments |
| Pin versions | Use --version when installing rather than always getting latest |
| Report suspicious skills | Use the moderation tools to flag concerning content |
Real-World Use Cases
Community discussions on Reddit and developer blogs reveal several categories of popular ClawHub skills:
Developer Workflows
Skills for managing repositories, handling pull requests, creating issues, and automating CI/CD pipelines are among the most popular. These transform the agent into a coding assistant that can interact directly with GitHub, GitLab, and other platforms.
Productivity & Communication
Skills for creating "agent mail" (real inboxes for agents), daily briefing generators, and memory search capabilities have turned agents from simple chatbots into comprehensive personal assistants.
Web Search & Research
Web search skills, combined with the agent's ability to synthesize information, enable automated research workflows. Users report using these for competitive analysis, market research, and content aggregation.
IoT & Automation
Nix plugin skills like "peekaboo" (macOS UI automation) and "padel" (court booking management) demonstrate the breadth of possibilities when skills can bundle CLI binaries alongside instructions.
ClawHub vs Alternatives
This is a skill registry for AI agents. Alternatives must also be skill registries or similar discovery platforms. Here's how ClawHub compares:
| Feature | ClawHub | awesome-agent-skills | Agent Skills Directory | Agent Skills Open Standard |
|---|---|---|---|---|
| GitHub Stars | 5,200+ | 2,850+ | 7 | N/A (specification) |
| Type | Full registry + CLI | Curated awesome-list | Discovery tool | Open specification |
| Semantic Search | ✅ Vector embeddings | ❌ Static Markdown | ✅ Smart recommendations | ❌ N/A |
| CLI | ✅ Full install/publish | ❌ None | ❌ None | N/A |
| Versioning | ✅ Semver + tags | ❌ Git commits only | ❌ None | ❌ N/A |
| Security Scanning | ✅ VirusTotal | ❌ Manual review | ✅ Built-in scanning | ❌ N/A |
| Multi-Agent Support | OpenClaw/Clawdbot | Claude, Codex, Copilot | 41 provider repos | All compatible agents |
| License | MIT | MIT | MIT | Various |
When to Choose Each
- ClawHub: Best for OpenClaw/Clawdbot users who want a full package management experience with publish, version, install, and search workflows. The largest community and most active development.
- awesome-agent-skills: Best for cross-platform discovery. If you use Claude Code, Codex, or Copilot and want a curated catalog of compatible skills across multiple agents.
- Agent Skills Directory: Best for quality-focused discovery with built-in security scanning and maintenance tracking across 41 provider repositories.
- Agent Skills Open Standard: Best for interoperability. If you want skills that work across multiple agent platforms (Claude Code, VS Code, GitHub Copilot, OpenAI Codex), the open standard ensures portability.
Advanced Configuration
SOUL.md Registry (onlycrabs.ai)
In addition to skills (what an agent does), ClawHub's ecosystem includes SOUL.md — files that define how an agent behaves. The SOUL.md registry lives on onlycrabs.ai and is architecturally similar to ClawHub:
- On the onlycrabs.ai host, the home page defaults to "souls"
- On ClawHub, souls are accessible under
/souls - Soul bundles only accept SOUL.md (no extra files)
CLI Configuration File
The ClawHub CLI supports a configuration file for persisting settings like custom skill directories and proxy configuration:
# HTTP proxy support
export HTTP_PROXY=http://proxy.example.com:8080
Environment Variables Reference
| Variable | Purpose |
|---|---|
CLAWHUB_DISABLE_TELEMETRY | Set to 1 to disable install telemetry |
CLAWDBOT_CONFIG_PATH | Custom Clawdbot config path |
CLAWDBOT_STATE_DIR | Custom Clawdbot state directory |
OPENCLAW_CONFIG_PATH | OpenClaw config path |
OPENCLAW_STATE_DIR | OpenClaw state directory |
Frequently Asked Questions
Does installing a skill give it access to my entire system?
Yes — skills run with the same permissions as the agent. This is why reviewing SKILL.md before installation and using sandboxed environments for untrusted skills is critical.
Can I use ClawHub skills without OpenClaw?
ClawHub is designed as the skill registry for the OpenClaw/Clawdbot ecosystem. While the SKILL.md format is essentially Markdown that any agent could interpret, the CLI and registry infrastructure are tightly integrated with OpenClaw.
Is there a way to publish private skills?
Currently, all skills published to ClawHub are public and released under the MIT-0 license. For private skills, you would need to host your own skill directory.
How does the semantic search work?
ClawHub uses OpenAI's text-embedding-3-small model to generate vector embeddings for skill descriptions and content. When you search, your query is also embedded, and Convex's vector search finds the closest matches — meaning you can search with natural language like "manage my calendar" rather than exact keywords.
What happens when I delete a skill?
clawhub delete performs a soft delete — the skill is hidden from search and browsing but not permanently removed. Owners, moderators, and admins can restore soft-deleted skills with clawhub undelete. Only admins can perform hard deletes.
How is ownership transfer handled?
ClawHub has a full ownership transfer workflow: the current owner sends a transfer request, the recipient accepts or rejects it, and either party can cancel a pending transfer.
Can I run ClawHub locally?
Yes! The project is fully open-source. You need Bun, a Convex deployment, a GitHub OAuth app, and an OpenAI API key. See the quickstart guide for instructions.
What's the difference between Skills and Souls?
Skills define what an agent can do (e.g., "search the web", "manage GitHub issues"). Souls define how an agent behaves (e.g., personality, communication style, guardrails). Skills live on ClawHub; souls live on onlycrabs.ai.
Conclusion
ClawHub represents a critical piece of infrastructure for the AI agent ecosystem. As agents become more capable and autonomous, the need for a standardized, secure, and discoverable skill registry becomes increasingly important.
With its semantic vector search, comprehensive CLI, versioning and moderation systems, and growing community of 5,200+ stargazers, ClawHub has established itself as the leading skill registry in the space. While security challenges remain — as they do with any open package registry — the integration with VirusTotal and the community's active moderation efforts show a commitment to building a trustworthy ecosystem.
Whether you're building skills for your own AI agent, publishing tools for the community, or simply exploring what's possible with AI agent capabilities, ClawHub provides the infrastructure to make it happen.