claude-code-plugin

Complete Guide to Claude Code Plugin

Complete guide to creating, publishing, installing, updating, and syncing Claude Code Plugins

Use Cases

Developing a new Claude Code Plugin
Publishing a Plugin to a Marketplace
Installing and updating Plugins
Managing Plugin versions
Syncing the latest version
Creating a custom Marketplace

Part 1: Plugin Architecture

Directory Structure

my-plugin/
├── .claude-plugin/
│   ├── plugin.json          # Plugin manifest（必要）
│   └── marketplace.json     # Marketplace 索引（選用）
├── commands/                # Slash 命令（在根目錄！）
│   └── my-command.md
├── skills/                  # Agent Skills
│   └── my-skill/
│       └── SKILL.md
├── hooks/
│   └── hooks.json           # Hook 配置
├── agents/                  # Subagent 定義
├── .mcp.json               # MCP 伺服器配置
├── CHANGELOG.md
└── README.md

⚠️ Important: commands/, skills/, hooks/ must be in the root directory, do not put them in .claude-plugin/

plugin.json Specification

{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "Plugin 功能描述",
  "author": {
    "name": "作者名稱",
    "email": "email@example.com"
  },
  "license": "MIT",
  "keywords": ["keyword1", "keyword2"]
}

The Four Major Components

Component	Purpose	Trigger Method	File Format
Commands	Slash commands executed by the user	`/command` Manual	Markdown
Skills	Teaching Claude how to do things	Automatically based on context	SKILL.md
Hooks	Event-driven automation	Triggered by system events	JSON + Shell
MCP	Providing tool capabilities	Called by Claude	.mcp.json

Part 2: Publishing a Plugin

Method 1: GitHub Marketplace (Recommended)

Step 1: Create marketplace.json

{
  "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
  "name": "my-marketplace",
  "description": "我的 Plugin 集合",
  "owner": {
    "name": "username",
    "email": "email@example.com"
  },
  "plugins": [
    {
      "name": "my-plugin",
      "version": "1.0.0",
      "source": "./",
      "description": "Plugin 描述",
      "category": "development"
    }
  ]
}

Step 2: Push to GitHub

git add .
git commit -m "feat: add Plugin marketplace format"
git tag -a v1.0.0 -m "Release v1.0.0"
git push origin main
git push origin v1.0.0

Step 3: User Installation

# 添加 marketplace
/plugin marketplace add owner/repo

# 安裝 plugin
/plugin install my-plugin@my-marketplace

Method 2: npm Publishing

# 1. 在 package.json 中命名（加 claude-plugin- 前綴）
{
  "name": "claude-plugin-my-plugin",
  "version": "1.0.0"
}

# 2. 發布
npm publish

# 3. 用戶安裝
npm install -g claude-plugin-my-plugin

Method 3: Direct Sharing

# 用戶下載後本地安裝
/plugin install /path/to/my-plugin

Part 3: Installing Plugins

Installing from a Marketplace

# 1. 先添加 marketplace（只需一次）
/plugin marketplace add owner/repo

# 2. 列出可用 plugins
/plugin marketplace list

# 3. 安裝 plugin
/plugin install plugin-name@marketplace-name

Installing Directly from GitHub

# 完整路徑安裝
/plugin install github:owner/repo#path/to/plugin

# 範例
/plugin install github:miles990/evolve-plugin

Local Installation

# 從本地目錄安裝
/plugin install /path/to/my-plugin

Viewing Installed

# 列出所有已安裝的 plugins
/plugin list

# 查看詳細資訊
/plugin info plugin-name@marketplace

Uninstalling

# 解除安裝特定 plugin
/plugin uninstall plugin-name@marketplace

# 範例
/plugin uninstall evolve@evolve-plugin

# 強制解除安裝（忽略相依性）
/plugin uninstall plugin-name@marketplace --force

Uninstallation Notes：

Uninstalling does not remove the marketplace, only the installed plugin
If other plugins depend on this plugin, a warning will appear
After uninstalling, it can be reinstalled at any time

Part 4: Updating Plugins

Checking for Updates

# 檢查所有 plugins 是否有更新
/plugin update --check

# 檢查特定 plugin
/plugin update --check plugin-name@marketplace

Performing Updates

# 更新特定 plugin
/plugin update plugin-name@marketplace

# 更新所有 plugins
/plugin update --all

Automatic Version Check Process

本地版本 → 遠端版本 → 比較
    ↓           ↓
plugin.json  GitHub API / marketplace.json
    ↓
若遠端較新 → 提示用戶更新

Manual Version Check

# 取得本地版本
cat ~/.claude/plugins/installed_plugins.json | jq '.plugins["plugin@marketplace"][0].version'

# 取得遠端版本
curl -s https://raw.githubusercontent.com/owner/repo/main/.claude-plugin/plugin.json | jq -r '.version'

Part 5: Version Control

Version Locations (Must Be Synchronized)

Location	Description
`.claude-plugin/plugin.json`	Plugin manifest
`.claude-plugin/marketplace.json`	Marketplace Index
`skills/*/SKILL.md`	Skill Version (if applicable)
`CHANGELOG.md`	Change Log
Git tag	Release Tag

Semantic Versioning

MAJOR.MINOR.PATCH
  │     │     └── Bug fixes（修復）
  │     └── 新功能（向後相容）
  └── 破壞性變更（不相容）

Release Checklist

# 更新所有版本位置
- [ ] plugin.json → version
- [ ] marketplace.json → plugins[].version
- [ ] SKILL.md → version: (如適用)
- [ ] CHANGELOG.md → 新條目
- [ ] README.md → 版本徽章

# Git 操作
git add .
git commit -m "chore: bump version to vX.Y.Z"
git tag -a vX.Y.Z -m "Release vX.Y.Z: 描述"
git push origin main
git push origin vX.Y.Z

CHANGELOG.md Format

## [1.1.0] - 2026-01-16

### Added
- 新功能描述

### Changed
- 變更描述

### Fixed
- 修復描述

### Security
- 安全修復

Part 6: Syncing the Latest Version

Syncing from the Main repo to a Standalone Plugin repo

When the plugin was split off from the main project:

# 1. 複製 skills 目錄
cp -r /path/to/main-project/skills /path/to/plugin-repo/

# 2. 更新版本
# 編輯 plugin.json, marketplace.json

# 3. 提交並推送
cd /path/to/plugin-repo
git add -A
git commit -m "chore: sync with main-project vX.Y.Z"
git push origin main

Sync Script Example

#!/bin/bash
# sync-plugin.sh - 同步 plugin 到獨立 repo

MAIN_REPO="$1"
PLUGIN_REPO="$2"
VERSION="$3"

# 複製 skills
rm -rf "$PLUGIN_REPO/skills"
cp -r "$MAIN_REPO/skills" "$PLUGIN_REPO/"

# 更新版本
sed -i '' "s/\"version\": \".*\"/\"version\": \"$VERSION\"/" \
    "$PLUGIN_REPO/.claude-plugin/plugin.json"

# 提交
cd "$PLUGIN_REPO"
git add -A
git commit -m "chore: sync with main-project v$VERSION"
git push origin main

Automatic Sync (Using GitHub Actions)

# .github/workflows/sync-plugin.yml
name: Sync Plugin

on:
  push:
    branches: [main]
    paths:
      - 'skills/**'
      - 'evolve-plugin/**'

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Sync to plugin repo
        run: |
          # Clone plugin repo
          git clone https://github.com/owner/plugin-repo.git

          # Copy files
          cp -r skills/ plugin-repo/
          cp evolve-plugin/.claude-plugin/* plugin-repo/.claude-plugin/

          # Push
          cd plugin-repo
          git add -A
          git commit -m "chore: auto-sync from main repo"
          git push

Part 7: Marketplace Management

Creating Your Own Marketplace