Chapter 52

Hooks in Plugins: Injecting Lifecycle Events for Deterministic Engineering Control

Chapter 52: Publishing to the Skills Marketplace: Packaging, Review, and Version Management

52.1 clawhub.ai: The Claude Ecosystem Marketplace

clawhub.ai is the official Claude Plugin and Skill marketplace (referred to as "the Hub" or "the marketplace"). It plays a role similar to npm, PyPI, or the VS Code Marketplace — the central platform where developers publish extensions and users discover and install them.

As of April 2026, clawhub.ai hosts more than 12,000 Plugins and 85,000 standalone Skills, with over 2 million monthly active installs. Understanding its publishing workflow and review standards is essential for every developer in the Claude ecosystem.

Core Marketplace Features

Discovery: category browsing, keyword search, curated recommendations
Installation: one-click install to local Claude Code or organizational workspaces
Version management: viewing changelogs, rolling back to historical versions
Review system: user ratings and usage statistics
Dependency resolution: automatic installation of Plugin dependencies

52.2 Pre-Publication Preparation

Registering a Developer Account

# Login via CLI (opens browser for OAuth authorization)
claude-plugin login

# Verify login status
claude-plugin whoami
# Logged in as: [email protected]
# Publisher namespace: janedoe
# Verified: ✓

Publishing requires email verification. Enterprise developers also need to complete an organization verification process to receive an organization publishing namespace (e.g., acmecorp).

Final Checklist

□ plugin.json version number updated
□ All TypeScript compiled (npm run build)
□ claude-plugin validate passes (no errors)
□ README.md written (required for marketplace listing)
□ CHANGELOG.md updated (documents changes in this version)
□ LICENSE file exists
□ No .env or secret-containing files included
□ Sensitive config items marked "secret": true
□ Tests pass locally
□ Manually verified in Claude Code with local install

README.md Requirements

The marketplace listing renders the Plugin's root README.md directly. A good README must include:

# Weather Plugin

A Claude Plugin providing real-time weather data and forecasts.

## Features

- Current weather conditions for any city worldwide
- 1–7 day forecasts with temperature, precipitation, and wind
- Automatic geocoding for city names (English and Chinese)

## Installation

```bash
claude plugin install weather-plugin

Configuration

Field	Type	Required	Description
defaultCity	string	No	Default city (default: Beijing)
temperatureUnit	string	No	celsius or fahrenheit

Included Skills

weather-query: Query current weather or forecasts for any city

Requirements

Claude Code >= 1.0.0
Internet access (for Open-Meteo API)

Privacy

This plugin makes outbound HTTP requests to:

geocoding-api.open-meteo.com — city name geocoding
api.open-meteo.com — weather data

No personal data is transmitted to these services.


## 52.3 Packaging

### Pack Command

```bash
# Basic packaging
claude-plugin pack

# Specify output path
claude-plugin pack --output ./releases/weather-plugin-1.0.0.clpkg

# Include source maps (useful for debugging, increases package size)
claude-plugin pack --include-sourcemaps

# Strict mode (runs full validation before packing)
claude-plugin pack --strict

The .clpkg Format

.clpkg (Claude Plugin Package) is a specialized ZIP format containing:

weather-plugin-1.0.0.clpkg (essentially a ZIP)
├── manifest.json          ← generated from plugin.json, with extra metadata
├── dist/                  ← compiled JavaScript
│   ├── mcp/server.js
│   ├── hooks/pre-tool.js
│   └── monitor/collector.js
├── skills/                ← Skill files (original Markdown)
│   └── weather-query.md
├── README.md
├── CHANGELOG.md
├── LICENSE
└── signature.sig          ← package signature (from your developer private key)

The signature mechanism guarantees package integrity: Claude Code verifies the signature during installation to prevent tampering in transit.

Inspecting Package Contents

claude-plugin pack inspect weather-plugin-1.0.0.clpkg

# manifest.json (3.2 KB)
# dist/mcp/server.js (28.5 KB)
# dist/hooks/pre-tool.js (4.1 KB)
# skills/weather-query.md (1.8 KB)
# README.md (2.3 KB)
# CHANGELOG.md (0.9 KB)
# LICENSE (1.1 KB)
# signature.sig (0.5 KB)
# ─────────────────────
# Total: 42.4 KB (compressed: 16.2 KB)

52.4 The Publication Workflow

Submitting to the Marketplace

claude-plugin publish weather-plugin-1.0.0.clpkg

The publish command executes:

Local pre-validation (format, signature, required files)
Upload to clawhub.ai CDN
Automated review triggered
Returns review tracking URL

✓ Package validated locally
✓ Uploaded to clawhub.ai (16.2 KB)
✓ Automated checks started

Package ID: janedoe/[email protected]
Review URL: https://clawhub.ai/publisher/reviews/abc123
Status: pending_automated_checks
Estimated review time: 2-4 hours

Automated Review Phase

Automated review runs in Anthropic's secure environment and typically completes within 1–2 hours:

Automated review checklist:

□ Static code analysis
  ├── No known malicious code patterns
  ├── No hardcoded API keys or passwords
  └── No dependencies with known CVEs (high severity or above)

□ Permission compliance
  ├── Actual permissions used match plugin.json declarations
  ├── No network requests to undeclared endpoints
  └── No undeclared filesystem access

□ MCP protocol compliance
  ├── Tool definitions conform to JSON Schema spec
  ├── Response format follows MCP standard
  └── No protocol version incompatibilities

□ Skill file quality
  ├── YAML frontmatter is syntactically valid
  ├── All required fields present
  └── No obvious malicious instruction injection attempts

Manual Review Phase

Some Plugins enter the manual review queue after passing automated checks. Triggers include:

Requesting highly sensitive permissions (execute:arbitrary-code, access:credentials)
Contains outbound requests to unknown domains
Automated tools flagged edge cases requiring human judgment
This is the developer's first published Plugin (new developer first-publish review)

Manual review typically completes within 24–48 hours. Reviewers check:

Whether Skill behavioral instructions pose security risks
Whether the Plugin description matches actual functionality
Whether the name is misleading (impersonating official or well-known Plugins)

Handling Review Outcomes

# Check review status
claude-plugin review status abc123

# Possible statuses:
# pending_automated_checks   - waiting for automated review
# automated_passed           - automated checks passed, awaiting manual
# under_manual_review        - in manual review
# approved                   - approved and published
# changes_requested          - requires changes before resubmission
# rejected                   - rejected (with reason)

If you receive changes_requested:

Review feedback for janedoe/[email protected]:

[REQUIRED] Network access transparency
  Your plugin makes requests to api.open-meteo.com, but your README
  does not mention this. Please add a Privacy section documenting all
  external endpoints your plugin communicates with.

[SUGGESTED] Skill quality improvement
  The weather-query skill's "Edge Cases" section does not cover the
  scenario where the Open-Meteo API is temporarily unavailable.

After making the required changes, bump the patch version, rebuild, and resubmit:

# Update plugin.json: "version": "1.0.1"
npm run build
claude-plugin pack
claude-plugin publish weather-plugin-1.0.1.clpkg

52.5 Version Management Strategy

Semantic Versioning in Practice

In the clawhub.ai ecosystem, version numbers are not just numbers — they are a compatibility contract with users:

1.0.0 → 1.0.1  Patch: bug fix, documentation improvement, no behavior change
1.0.0 → 1.1.0  Minor: new features, backward-compatible
1.0.0 → 2.0.0  Major: breaking changes, migration required

When to issue a major version (breaking change):

Removing or renaming an existing MCP tool (Skills depending on it will break)
Modifying a Skill's required parameters (existing invocations will error)
Changing a tool's return format (code relying on the old format will crash)
Removing a Hook implementation (behaviors relying on the Hook's side effects will change)

CHANGELOG.md Format

Follow the Keep a Changelog format:

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/).

## [Unreleased]

## [1.1.0] - 2026-04-28

### Added
- `get_weather_alerts` tool for severe weather warnings
- `weather-alerts` skill
- Fahrenheit support in forecast tool

### Changed
- Improved geocoding accuracy for Chinese city names

### Fixed
- Fixed crash when city name contains special characters

## [1.0.1] - 2026-04-10

### Fixed
- Added Privacy section to README (per review feedback)

## [1.0.0] - 2026-04-01

### Added
- Initial release
- `get_current_weather` and `get_weather_forecast` tools
- `weather-query` skill

Supporting Multiple Major Versions

clawhub.ai supports maintaining multiple major versions simultaneously. Publishing 2.0.0 does not automatically deprecate 1.x — users can choose to remain on 1.x.

Mark old versions with the deprecation field in plugin.json:

{
  "version": "1.0.1",
  "deprecation": {
    "message": "Please upgrade to v2.x for improved performance",
    "since": "2026-05-01",
    "sunset": "2026-11-01"
  }
}

After the sunset date, the old version is delisted from the marketplace, but existing installations continue working — users just can't make new installs of the deprecated version.

52.6 Private Publishing and Enterprise Options

Not all Plugins are meant for public release. clawhub.ai offers three visibility levels:

Visibility	Description	Use Case
`public`	Searchable and installable by everyone	Open-source tools, generic Skills
`unlisted`	Installable via direct link, not in search results	Internal tools, beta versions
`private`	Visible only to org members (requires enterprise account)	Enterprise-internal Plugins

# Publish as unlisted
claude-plugin publish weather-plugin-1.0.0.clpkg --visibility unlisted

# Publish as private (requires enterprise account)
claude-plugin publish weather-plugin-1.0.0.clpkg --visibility private \
  --org acmecorp

Enterprise private registry configuration is covered in detail in Chapter 56.

52.7 Automated Publishing with CI/CD

Configure automated publishing in GitHub Actions:

# .github/workflows/publish.yml
name: Publish to clawhub.ai

on:
  push:
    tags:
      - 'v*.*.*'

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          
      - run: npm ci
      - run: npm run build
      - run: npm install -g @claude/plugin-cli
      - run: claude-plugin validate --strict
      - run: claude-plugin pack
      
      - name: Publish
        env:
          CLAWHUB_TOKEN: ${{ secrets.CLAWHUB_TOKEN }}
        run: |
          claude-plugin login --token $CLAWHUB_TOKEN
          claude-plugin publish *.clpkg

Generate CLAWHUB_TOKEN from the clawhub.ai developer settings page and store it as a GitHub Actions secret. The workflow triggers automatically when you push a version tag (e.g., git tag v1.1.0 && git push origin v1.1.0).

52.8 Post-Publication Operations

Monitoring Usage

claude-plugin stats weather-plugin

# Package: janedoe/weather-plugin
# ─────────────────────────────
# Total installs:     3,847
# Active this month:  1,204
# Rating:             4.7 / 5.0 (89 reviews)
# 
# Version distribution:
#   1.1.0:  68%
#   1.0.1:  28%
#   1.0.0:   4%

Responding to User Feedback

The clawhub.ai Issues feature allows users to submit bug reports and feature requests. Developers are expected to:

Respond to P1 (crash) bugs within 7 days
Respond to general bugs within 30 days
Provide clear accept/reject reasons for feature requests

Response quality influences the Plugin's marketplace ranking weight.

Emergency Unpublishing

If a critical security vulnerability is discovered:

# Unpublish a specific version
claude-plugin unpublish [email protected] \
  --reason "Security vulnerability in geocoding"

# Unpublish all versions
claude-plugin unpublish weather-plugin --all \
  --reason "Critical security issue"

Existing users receive a security warning recommending they update or uninstall.

Summary

The clawhub.ai publication workflow covers the complete path from code to users: packaging (generating a signed .clpkg) → submission (triggering automated and manual review) → publication (going live in the marketplace) → operations (monitoring stats, responding to feedback, iterating versions). Semantic versioning is not just a convention — it is a compatibility contract with users. The CHANGELOG.md is a fundamental part of a responsible publishing culture. CI/CD automation is the best practice for continuous iteration. The next chapter shifts to a specialized Plugin type: themes and appearance plugins.

Rate this chapter

4.5 / 5 (3 ratings)